What are some best practices for writing sample requests and responses in API documentation?

Question

ICSM Computer · Answer

Writing sample requests and responses well is crucial for making your API documentation developer-friendly and easy to adopt. Here are
best practices to follow when creating them:
1. Use Realistic and Complete Examples
Show actual field values, not placeholders like string,
123, or true.Include all required fields, and optionally include extras to show flexibility.
Bad:
{
  "name": "string",
  "age": 123
}
Good:
{
  "name": "Alice Johnson",
  "age": 29
}
2. Include Full HTTP Requests and Responses
Show the full request: method, URL, headers, body.Likewise, show the full response: status code, headers, body.
Example:
POST /api/v1/users HTTP/1.1
Host: api.example.com
Authorization: Bearer {your_token}
Content-Type: application/json
{
  "name": "Alice",
  "email": "alice@example.com"
}
HTTP/1.1 201 Created
Content-Type: application/json
{
  "id": "abc123",
  "name": "Alice",
  "email": "alice@example.com",
  "createdAt": "2025-06-05T10:15:30Z"
}
3. Provide Multiple Examples
Success responses (200, 201)Error responses (400, 401, 404, 500)Edge cases (empty result sets, optional fields)
4. Language-Specific Code Snippets
Provide ready-to-run examples in curl, JavaScript (fetch/axios),
Python (requests), etc.Help users see how to call your API from different environments.
Example in curl:
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'
5. Label and Format Clearly
Label each section: Request, Response, 
Status, ExampleUse syntax highlighting (json, http, bash)Keep consistent formatting across all examples
6. Explain the Example
Briefly describe what the example does (especially if it’s complex).Highlight which parameters are optional, required, or defaults.
Example:
"This request creates a new user with the name and email. The email must be unique."
7. Avoid Redundancy, But Show Variety
Don’t repeat identical examples across endpoints.Use different user names, timestamps, or scenarios for realism.
8. Show Pagination and Filtering
Include examples that use query parameters like ?page=2andlimit=10Show how pagination works with meta fields or next URLs in the response.
9. Keep Examples in Sync with the API
Auto-generate them from OpenAPI/Swagger where possible.Use tools like Stoplight, 
Swagger UI, or [Postman examples].
10. Keep Responses Simple and Focused
Avoid overly large JSON blobs—trim to the most relevant fields.Use ... or // other fields if necessary.
Bonus: Sample Template
### 📤 Request
**POST** `/api/v1/users`
```http
POST /api/v1/users HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
  "name": "Alice Johnson",
  "email": "alice@example.com"
}
Response: 201 Created
{
  "id": "user_abc123",
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "createdAt": "2025-06-05T10:00:00Z"
}
Response: 400 Bad Request
{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "The email address format is invalid."
  }
}

interview

What are some best practices for writing sample requests and responses in API documentation?

ICSM Computer

Can you answer this question?

1 Answers

1. Use Realistic and Complete Examples

2. Include Full HTTP Requests and Responses

3. Provide Multiple Examples

4. Language-Specific Code Snippets

5. Label and Format Clearly

6. Explain the Example

7. Avoid Redundancy, But Show Variety

8. Show Pagination and Filtering

9. Keep Examples in Sync with the API

10. Keep Responses Simple and Focused

Bonus: Sample Template

Response: `201 Created`

Response: `400 Bad Request`

Liked By