REST and GraphQL API consumers can't integrate correctly without knowing exactly what to send and what to expect back. Documentation that describes an endpoint without showing an example request and response forces developers to guess at header formats, body structure, and response shapes — every guess is a potential bug. OpenAPI specs with 'string' placeholders for every field value are no better than no docs at all: they show structure but not semantics, valid values, or what realistic data looks like. iso-25010:2011 analysability requires that a system be understandable without probing it experimentally.
High because API consumers who cannot see example request and response payloads must probe the API experimentally, introducing integration bugs and making the first-use experience unreliable.
For each endpoint, show a complete curl request and the matching response with realistic (not placeholder) field values:
### POST /api/users
**Request:**
```bash
curl -X POST https://api.example.com/api/users \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{"name": "Jane Smith", "email": "jane@example.com"}'
Response (201):
{
"id": "usr_abc123",
"name": "Jane Smith",
"email": "jane@example.com",
"created_at": "2026-03-29T12:00:00Z"
}
Never use 'string' or 'value' as example field values — use realistic data that shows the actual format consumers will receive.
ID: developer-documentation.api-reference.request-response-examples
Severity: high
What to look for: For REST or GraphQL APIs, check that documentation shows example HTTP requests (with headers, body, query parameters) AND example responses (with status codes, response body). This applies to both hand-written docs and generated docs (OpenAPI/Swagger). Check that examples use realistic data, not just "string" or "value" placeholders. Count every API endpoint and enumerate which have documented request/response examples vs. which are missing them.
Pass criteria: Each API endpoint shows at least one example request (method, URL, headers, body) and the corresponding response (status code, response body). Examples use realistic data values. At least 1 implementation must be confirmed.
Fail criteria: API docs describe endpoints but show no request/response examples, or examples show only the request without the response, or examples use placeholder values like "string" for every field.
Skip (N/A) when: The project is not an API or SDK -- it is a library consumed via function calls, a CLI tool, or a standalone application with no HTTP endpoints for external consumers.
Detail on fail: Example: "API docs list 6 endpoints but none show example requests or responses" or "OpenAPI spec exists but examples use 'string' placeholder for every field value"
Remediation: Add request/response examples to each endpoint:
### POST /api/users
Creates a new user account.
**Request:**
```bash
curl -X POST https://api.example.com/api/users \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{"name": "Jane Smith", "email": "jane@example.com"}'
Response (201):
{
"id": "usr_abc123",
"name": "Jane Smith",
"email": "jane@example.com",
"created_at": "2026-03-29T12:00:00Z"
}