---
title: "What are some best practices for writing sample requests and responses in API documentation?"  
description: "What are some best practices for writing sample requests and responses in API documentation?"  
author: "ICSM Computer"  
published: 2025-06-04  
updated: 2025-06-04  
canonical: https://www.mindstick.com/interview/34209/what-are-some-best-practices-for-writing-sample-requests-and-responses-in-api-documentation  
category: "api(s)"  
tags: ["api(s)", "api documentation"]  
reading_time: 5 minutes  

---

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

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:

```plaintext
{
  "name": "string",
  "age": 123
}
```

## Good:

```plaintext
{
  "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:

```plaintext
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"
}
```

```plaintext
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:

```plaintext
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

```plaintext
### 📤 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`

```plaintext
{
  "id": "user_abc123",
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "createdAt": "2025-06-05T10:00:00Z"
}
```

### Response: `400 Bad Request`

```plaintext
{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "The email address format is invalid."
  }
}
```

## Answers

### Answer by ICSM Computer

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:

```plaintext
{
  "name": "string",
  "age": 123
}
```

## Good:

```plaintext
{
  "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:

```plaintext
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"
}
```

```plaintext
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:

```plaintext
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

```plaintext
### 📤 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`

```plaintext
{
  "id": "user_abc123",
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "createdAt": "2025-06-05T10:00:00Z"
}
```

### Response: `400 Bad Request`

```plaintext
{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "The email address format is invalid."
  }
}
```


---

Original Source: https://www.mindstick.com/interview/34209/what-are-some-best-practices-for-writing-sample-requests-and-responses-in-api-documentation

Copyright © MindStick Software Pvt. Ltd. This Markdown version is provided for developers, AI systems, and offline reading.