API Documentation for Testers: Request/Response Examples and Testing Strategies

API documentation for QA teams requires a different focus than developer documentation. Testers need comprehensive examples, error scenarios, authentication flows, and edge cases—not just happy-path documentation. Effective API docs for testing enable rapid test case creation, consistent validation, and thorough coverage.

Essential Components for QA-Focused API Documentation

1. Authentication and Authorization

Document all auth methods with test credentials:

## Authentication

### Method: Bearer Token (JWT)

**Obtaining a Token**:
```http
POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "test@example.com",
  "password": "Test123!"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "user": {
    "id": 123,
    "email": "test@example.com",
    "role": "customer"
  }
}

Using the Token:

GET /api/v1/orders
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Test User Accounts

Role	Email	Password	Permissions
Admin	admin@test.com	Admin123!	Full access
Customer	customer@test.com	Customer123!	Read orders, create orders
Guest	guest@test.com	Guest123!	Read-only
Suspended	suspended@test.com	Suspended123!	Should receive 403 errors


### 2. Request/Response Examples for All Scenarios

**Success Cases**:
```markdown
## Create Order - Success

**Request**:
```http
POST /api/v1/orders
Authorization: Bearer {token}
Content-Type: application/json

{
  "items": [
    {"product_id": 101, "quantity": 2},
    {"product_id": 205, "quantity": 1}
  ],
  "shipping_address": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102"
  },
  "payment_method": "credit_card",
  "payment_token": "tok_visa"
}

Response: 201 Created:

{
  "id": 789,
  "status": "pending",
  "total": 129.99,
  "created_at": "2024-10-06T14:30:00Z",
  "items": [...],
  "shipping_address": {...}
}

Error Cases:

400 Bad Request - Invalid Data:

POST /api/v1/orders
{
  "items": [],  // Empty items array
  "shipping_address": null
}

Response:

{
  "error": "validation_error",
  "message": "Invalid request data",
  "details": [
    {"field": "items", "error": "must contain at least one item"},
    {"field": "shipping_address", "error": "required field missing"}
  ]
}

401 Unauthorized - Missing/Invalid Token:

GET /api/v1/orders
Authorization: Bearer invalid_token

Response:

{
  "error": "unauthorized",
  "message": "Invalid or expired authentication token"
}

403 Forbidden - Insufficient Permissions:

DELETE /api/v1/orders/789
Authorization: Bearer {customer_token}

Response:

{
  "error": "forbidden",
  "message": "Insufficient permissions to delete orders"
}

404 Not Found:

GET /api/v1/orders/99999

Response:

{
  "error": "not_found",
  "message": "Order with ID 99999 not found"
}

500 Internal Server Error:

{
  "error": "internal_server_error",
  "message": "An unexpected error occurred",
  "request_id": "req_abc123"
}

3. Error Code Reference

## Error Codes

| HTTP Code | Error Code | Description | Test Scenario |
|-----------|-----------|-------------|---------------|
| 400 | validation_error | Request data validation failed | Send invalid/missing fields |
| 400 | invalid_format | Data format incorrect | Send malformed JSON, wrong types |
| 401 | unauthorized | Authentication required or invalid | No token, expired token, invalid token |
| 403 | forbidden | Insufficient permissions | Customer tries admin operation |
| 404 | not_found | Resource doesn't exist | Request non-existent ID |
| 409 | conflict | Resource state conflict | Duplicate creation, concurrent update |
| 422 | unprocessable_entity | Business logic validation failed | Insufficient funds, out of stock |
| 429 | rate_limit_exceeded | Too many requests | Exceed 1000 requests/hour |
| 500 | internal_server_error | Server-side error | Test with invalid backend state |
| 503 | service_unavailable | Service temporarily down | Test during maintenance window |

4. Postman Collection

Export collection for testers:

{
  "info": {
    "name": "E-commerce API - QA Collection",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Authentication",
      "item": [
        {
          "name": "Login - Success",
          "request": {
            "method": "POST",
            "header": [{"key": "Content-Type", "value": "application/json"}],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"{{test_email}}\",\n  \"password\": \"{{test_password}}\"\n}"
            },
            "url": "{{base_url}}/api/v1/auth/login"
          },
          "response": []
        },
        {
          "name": "Login - Invalid Credentials",
          "request": {
            "method": "POST",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"test@test.com\",\n  \"password\": \"wrong_password\"\n}"
            },
            "url": "{{base_url}}/api/v1/auth/login"
          }
        }
      ]
    },
    {
      "name": "Orders",
      "item": [
        {
          "name": "Create Order - Success",
          "request": {
            "method": "POST",
            "header": [
              {"key": "Authorization", "value": "Bearer {{auth_token}}"}
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"items\": [{\"product_id\": 101, \"quantity\": 2}]\n}"
            },
            "url": "{{base_url}}/api/v1/orders"
          }
        }
      ]
    }
  ]
}

5. Rate Limits and Throttling

## Rate Limiting

**Limits**:
- Unauthenticated: 100 requests/hour
- Authenticated users: 1,000 requests/hour
- Admin users: 10,000 requests/hour

**Headers**:
```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1696593600

Testing Rate Limits:

# Test script to hit rate limit
for i in {1..1001}; do
  curl -H "Authorization: Bearer $TOKEN" \
    https://api.example.com/v1/products
done

Expected Behavior:

Request 1-1000: 200 OK
Request 1001: 429 Too Many Requests

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit of 1000 requests per hour exceeded",
  "retry_after": 3600
}

6. Data Validation Rules

## Field Validation

### Create Product

| Field | Type | Required | Constraints | Invalid Examples |
|-------|------|----------|-------------|-----------------|
| name | string | Yes | 1-200 chars, alphanumeric + spaces | "", "a", (201 chars) |
| price | number | Yes | > 0, max 2 decimals | 0, -10, 99.999 |
| category | string | Yes | Enum: [electronics, clothing, books] | "invalid", null |
| stock | integer | Yes | >= 0 | -1, 3.5, "ten" |
| description | string | No | Max 5000 chars | (5001 chars) |
| tags | array | No | Max 10 items, each 1-50 chars | [51 chars], [11 items] |

**Test Cases to Create**:
- Empty name (expect 400)
- Name with 201 characters (expect 400)
- Price = 0 (expect 400)
- Negative price (expect 400)
- Invalid category value (expect 400)
- All valid fields (expect 201)

7. Idempotency and Concurrency

## Idempotency

**Idempotent Operations** (safe to retry):
- GET, PUT, DELETE

**Non-Idempotent** (require idempotency keys):
- POST /api/v1/orders

**Using Idempotency Keys**:
```http
POST /api/v1/orders
Idempotency-Key: unique-key-123

Testing Idempotency:

Send POST request with idempotency key
Repeat identical request with same key
Expected: Second request returns same result, no duplicate resource

Concurrency Testing:

# Test concurrent updates to same resource
curl -X PUT /api/v1/products/101 -d '{"stock": 10}' &
curl -X PUT /api/v1/products/101 -d '{"stock": 20}' &
wait

# Verify: Last write wins or optimistic locking error

8. Mock Server Setup

// mock-server.js using json-server
const jsonServer = require('json-server');
const server = jsonServer.create();
const router = jsonServer.router('db.json');
const middlewares = jsonServer.defaults();

// Custom middleware for authentication
server.use((req, res, next) => {
  if (req.headers.authorization === 'Bearer valid_token') {
    next();
  } else if (req.path === '/api/v1/auth/login') {
    next();
  } else {
    res.status(401).json({ error: 'unauthorized' });
  }
});

// Custom route for login
server.post('/api/v1/auth/login', (req, res) => {
  const { email, password } = req.body;
  if (email === 'test@test.com' && password === 'Test123!') {
    res.json({ token: 'valid_token', expires_in: 3600 });
  } else {
    res.status(401).json({ error: 'invalid_credentials' });
  }
});

server.use(middlewares);
server.use('/api/v1', router);
server.listen(3000);

Best Practices

1. Document Edge Cases Explicitly

Don’t just show happy paths. Include:

Boundary values
Invalid data types
Missing required fields
Conflicting states

2. Provide cURL Examples

# Easy to copy-paste for quick testing
curl -X POST https://api.example.com/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"product_id": 101, "quantity": 2}]}'

3. Include Environment Variables

BASE_URL=https://staging.api.example.com
TEST_EMAIL=test@example.com
TEST_PASSWORD=Test123!
ADMIN_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

4. Document Asynchronous Operations

## Asynchronous Processing

**Create Bulk Import**:
```http
POST /api/v1/imports

Response: 202 Accepted:

{
  "id": "import_xyz",
  "status": "processing",
  "status_url": "/api/v1/imports/import_xyz/status"
}

Check Status:

GET /api/v1/imports/import_xyz/status

Possible Statuses: processing, completed, failed

Testing Strategy:

Submit async job
Poll status endpoint
Verify completion or error handling


## Conclusion

Effective API documentation for QA goes beyond describing endpoints—it provides complete testing scenarios, error cases, authentication flows, and validation rules. By including Postman collections, mock servers, edge case examples, and clear error documentation, teams enable testers to quickly create comprehensive test suites and validate API behavior thoroughly.