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, Example
Use 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=2&limit=10
Show 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?

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

Response: `201 Created`

Response: `400 Bad Request`