Skip to content

Response Documentation — Complete Guide

DodaTech Updated 2026-06-28 6 min read

In this tutorial, you will learn about Response Documentation. We cover key concepts, practical examples, and best practices to help you master this topic.

Response documentation describes what an API endpoint returns including HTTP status codes, headers, body schema with field types and formats, nested objects, arrays, pagination metadata, and realistic JSON examples for both success responses and every possible error case.

What You'll Learn

How to structure response documentation, how to document response fields with types and descriptions, how to show nested objects and arrays, how to document pagination and cursor-based responses, and how to include error response examples alongside success responses.

Why It Matters

Developers build their integration around your response format. Incomplete or inaccurate response documentation causes Parsing errors, null pointer exceptions, and data loss. Every field needs its type, description, and constraints documented.

Real-World Use

The Stripe API returns expandable objects where developers can request nested data. Their response documentation shows both the default response and the expanded response. DodaTech's compression API response documentation shows all fields with types and the complete JSON response example.

Response Structure

flowchart TD
  A[Response Documentation] --> B[Status Codes]
  A --> C[Response Headers]
  A --> D[Body Schema]
  A --> E[Response Example]
  A --> F[Error Responses]
  D --> G[Primitive Fields]
  D --> H[Nested Objects]
  D --> I[Arrays]
  D --> J[Pagination]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Documenting Status Codes

Every endpoint has one or more success codes and several error codes.

#### Response Status Codes

| Status | Description |
|--------|-------------|
| 200 | Request succeeded synchronously. Response body contains the result. |
| 201 | Resource created successfully. Location header contains the resource URL. |
| 202 | Request accepted for async processing. Response body contains a job ID. |
| 400 | Bad request. Check parameters and request body format. |
| 401 | Unauthorized. Check API key or authentication token. |
| 403 | Forbidden. API key lacks required scope. |
| 404 | Resource not found. The specified ID does not exist. |
| 413 | Request entity too large. File exceeds size limit. |
| 429 | Too many requests. Rate limit exceeded. |
| 500 | Internal server error. Retry with exponential backoff. |

Response Body Schema

Document every field in the response body with type and description.

#### Response Body Schema

| Field | Type | Description |
|-------|------|-------------|
| `job_id` | string (uuid) | Unique job identifier for progress polling |
| `status` | string | Current status: `pending`, `processing`, `completed`, `failed` |
| `input_size` | integer | Original file size in bytes |
| `output_size` | integer | Compressed file size in bytes (null until completed) |
| `ratio` | number | Compression ratio (null until completed). Example: 0.246 |
| `download_url` | string (uri) | Pre-signed download URL. Expires 24 hours after completion |
| `error` | object | Error details if status is failed. Null otherwise |

**Error object fields:**

| Field | Type | Description |
|-------|------|-------------|
| `error.code` | string | Machine-readable error code |
| `error.message` | string | Human-readable error message |
| `error.docs_url` | string (uri) | Link to error documentation |

Pagination Response

For list endpoints, document the pagination structure.

#### Paginated Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `data` | array | Array of result objects |
| `pagination.page` | integer | Current page number |
| `pagination.per_page` | integer | Items per page |
| `pagination.total` | integer | Total items across all pages |
| `pagination.total_pages` | integer | Total number of pages |

**Example:**

```json
{
  "data": [
    {
      "id": "file_a1b2c3d4e5f6g7h8",
      "name": "report.pdf",
      "size_bytes": 1048576,
      "format": "zip",
      "created_at": "2026-06-28T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 142,
    "total_pages": 8
  }
}


## Response Headers

Document non-standard response headers that carry important information.

```markdown
#### Response Headers

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum requests per hour |
| `X-RateLimit-Remaining` | Requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when limit resets |
| `X-Request-ID` | Echo of the request ID for tracing |
| `Location` | URL of the created resource (for 201 responses) |
| `Retry-After` | Seconds to wait before retrying (for 429 responses) |

Complete Response Example

Show a complete, realistic response example for each status code.

// 200 Success
{
  "job_id": "c7f3a2b1-8d4e-4f5a-9b6c-1d2e3f4a5b6c",
  "status": "completed",
  "input_size": 1048576,
  "output_size": 258432,
  "ratio": 0.246,
  "download_url": "https://api.dodatech.com/v2/download/c7f3a2b1",
  "error": null
}

// 202 Accepted (Async)
{
  "job_id": "d8e4f5a6-9b6c-4f5a-8d4e-1d2e3f4a5b6c",
  "status": "pending",
  "input_size": 524288000,
  "output_size": null,
  "ratio": null,
  "download_url": null,
  "error": null
}

Common Mistakes

1. Documenting Only Success Responses

Showing only the happy path without error response examples leaves developers unprepared for failures. Every status code needs a documented example.

2. Incomplete Field Documentation

Omitting fields from the schema table causes developers to miss important response data. Document every field including null and optional ones.

3. No Type Information

Response fields without types force developers to guess whether a value is a string, number, or object.

4. Placeholder Examples

Examples with placeholder text like string or 123 are useless. Show realistic values that developers can recognize.

5. Missing Pagination in List Responses

Documenting list endpoints without pagination fields causes developers to assume all data comes in one response.

6. No Nullable Field Documentation

Not marking which fields can be null causes null pointer exceptions in production code.

7. Unrealistic Example Data

Examples with made-up data that does not match actual API responses erode trust. Use real API output with anonymized data.

Practice Questions

1. What information should every response field include?

Field name, data type, description, whether it can be null, format if applicable, and an example value.

2. Why include multiple status code examples?

Different status codes have different response bodies. 200 returns the result, 202 returns a job ID, 4xx returns error details. Each needs its own documented example.

3. How do you document paginated responses?

Show the pagination structure with page, per_page, total, and total_pages fields. The data array contains the actual results. Link to pagination documentation for cursor-based alternatives.

4. What are response headers used for?

Response headers carry metadata like rate limit information, request IDs for tracing, location of created resources, and retry timing for rate-limited requests.

5. Challenge: Document the complete response for an API endpoint including all status codes, response headers, body schema with 8+ fields, pagination if applicable, and realistic JSON examples for each status code.

FAQ

What is the difference between response schema and response example?

The schema defines the structure, types, and constraints. The example shows a concrete value. Good documentation includes both: a schema for developers writing parsers and an example for developers who learn by reading.

How do I document responses with dynamic fields?

Use additionalProperties: true in the schema to indicate dynamic keys. Document known fields explicitly and note that additional fields may appear.

Should I document null fields in responses?

Yes. Mark which fields can be null and under what conditions. Nullable fields cause null pointer exceptions if developers do not check for null before accessing them.

How do I document binary responses like file downloads?

Document the Content-Type header (application/octet-stream), Content-Length header, Content-Disposition header with filename, and the streaming nature of the response.

What is the difference between synchronous and asynchronous response patterns?

Synchronous responses return the result immediately in the response body. Async responses return HTTP 202 with a job ID, and the developer polls a separate endpoint for the result.

Mini Project: Write Complete Response Documentation

Pick an API endpoint that returns a complex response with nested objects, arrays, and multiple status codes. Write complete response documentation including status codes table, response headers, body schema with all fields, pagination structure, and realistic JSON examples for success, error, and async responses.

What's Next

Responses show what the API returns. Now learn to show examples in different languages with Multi-Language Code Examples. Then explore SDKs and Client Libraries for documenting official client SDKs.

← Previous Parameter Documentation — Complete Guide Next → Multi-Language Code Examples — Complete Guide

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Api Documentation