Skip to content

API Reference Documentation — Complete Guide

DodaTech Updated 2026-06-28 7 min read

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

API reference documentation is the structured, comprehensive listing of every endpoint, parameter, request body, response schema, and error code your API exposes, organized for rapid scanning and direct use by developers writing integration code.

What You'll Learn

How to structure API reference pages, what information every endpoint listing needs, how to organize parameters and schemas for scannability, how to present response examples, and how to generate reference docs from OpenAPI specs using tools like Redoc.

Why It Matters

Reference documentation is the most-visited section of any API portal. Developers go there to look up parameter names, response formats, and error codes. Clean, scannable reference docs reduce lookup time from minutes to seconds and minimize integration errors.

Real-World Use

The Stripe API reference lists every endpoint with method, path, parameters in a table, request example as a code block, response example with schema, and error codes. Developers on the DodaTech team use the same structure for the DodaZIP Compression API reference.

Reference Page Structure

flowchart TD
  A[API Reference Page] --> B[Endpoint List]
  B --> C[Endpoint Section]
  C --> D[Method + Path]
  C --> E[Description]
  C --> F[Parameters Table]
  C --> G[Request Example]
  C --> H[Response Schema]
  C --> I[Response Example]
  C --> J[Error Codes]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Endpoint Listing Format

Every endpoint reference entry needs the HTTP method, full URL path, and a clear description of what the endpoint does.

### List All Files

`GET /v2/files`

Returns a paginated list of files uploaded by your organization.
Files are sorted by creation date, newest first.
Requires `files:read` scope.

#### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| page | integer | No | 1 | Page number (minimum: 1) |
| per_page | integer | No | 20 | Items per page (maximum: 100) |
| sort | string | No | created_at | Sort field: created_at or name |
| status | string | No | all | Filter by status: active, archived, deleted |

Parameter Documentation

Each parameter needs name, location, type, required status, default value, constraints, and a plain-language description.

#### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fileId` | string | Yes | Unique file ID. Format: `file_` + 16 alphanumeric chars |

#### Query Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `page` | integer | No | 1 | Page number for pagination |
| `per_page` | integer | No | 20 | Results per page (max 100) |
| `status` | string | No | all | Filter: `active`, `archived`, `deleted` |

#### Header Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `X-Request-ID` | string | No | UUID for request correlation |
| `Idempotency-Key` | string | No | Prevents duplicate processing |

Request Body Documentation

Show the complete JSON schema with required fields, types, and descriptions. Provide at least one realistic example.

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file_url` | string (uri) | Yes | Public URL of the file to compress |
| `format` | string | No | zip, gzip, or sevenz (default: zip) |
| `password` | string | No | AES-256 encryption password (8-64 chars) |
| `level` | integer | No | Compression level 1-9 (default: 6) |

**Example:**

```json
{
  "file_url": "https://example.com/report.pdf",
  "format": "zip",
  "password": "secure-password-123",
  "level": 9
}


## Response Schema Documentation

Show the complete response structure with types and descriptions for every field. Provide a realistic example.

```markdown
#### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `job_id` | string (uuid) | Unique job identifier |
| `status` | string | Job status: pending, processing, completed, failed |
| `input_size` | integer | Original file size in bytes |
| `output_size` | integer | Compressed file size in bytes |
| `ratio` | number | Compression ratio (output_size / input_size) |
| `download_url` | string (uri) | URL to download the result |

**200 Response Example:**

```json
{
  "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 Code Documentation

Every endpoint should include a table of possible error responses.

```markdown
#### Error Codes

| Status | Code | Message | Cause |
|--------|------|---------|-------|
| 400 | INVALID_FORMAT | Compression format not recognized | Use one of: zip, gzip, sevenz |
| 401 | UNAUTHORIZED | Missing or invalid API key | Check Authorization header |
| 403 | RATE_LIMITED | Too many requests | Implement exponential backoff |
| 413 | FILE_TOO_LARGE | File exceeds 500MB limit | Split file into smaller parts |
| 500 | INTERNAL_ERROR | Unexpected server error | Retry with exponential backoff |

Auto-Generating Reference Docs

Tools like Redoc generate reference documentation directly from OpenAPI specs.

# Generate HTML reference with Redoc CLI
npx @redocly/cli build-docs openapi.yaml -o reference.html

# Or use Redoc with Docker
docker run -p 8080:80 redocly/redoc \
  -e SPEC_URL=https://example.com/openapi.yaml

Common Mistakes

1. No Description on Endpoints

Listing endpoints without descriptions leaves developers guessing what each endpoint does. Every endpoint needs a plain-language purpose statement.

2. Missing Default Values

Parameters without documented defaults force developers to guess what happens if they omit the field. Always document default values.

3. Realistic Example Data

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

4. Incomplete Error Tables

Listing only 200 responses without error codes leaves developers unprepared for failure cases. Document every possible error status code.

5. No Type Information

Parameters without type documentation cause type errors in strongly-typed languages. Every field needs its type documented.

6. Inconsistent Table Format

Some parameter tables with types, some without. Some with defaults, some without. Use a consistent format across all endpoint documentation.

7. No Code Examples Section

Reference sections that document schemas but never show working examples force developers to construct requests from scratch. Every endpoint needs at least one cURL example.

Practice Questions

1. What information should every endpoint reference include?

HTTP method, URL path, description, parameters table, request body schema, response schema, response example, and error codes table.

2. Why use tables for parameter documentation?

Tables allow developers to scan parameter names, types, required status, and descriptions quickly without reading prose paragraphs.

3. How do auto-generated reference docs stay accurate?

Tools like Redoc generate docs directly from the OpenAPI spec. When the spec changes, regeneration produces updated docs automatically with no manual copy-paste.

4. What makes a good response example?

Realistic data with representative values, not placeholder text. The example should show the complete response structure including nested objects and arrays.

5. Challenge: Take one endpoint from a public API and write its complete reference documentation including parameters table, request body schema, response schema, response example, and error codes table.

FAQ

Should reference docs be hand-written or generated?

Generated from OpenAPI specs for accuracy, but hand-edit the descriptions and examples for clarity. The spec provides structure; the writer provides readability.

How do I organize a large API reference?

Group endpoints by tag or resource (Users, Files, Jobs). Use a table of contents with anchors. Include a search bar for finding endpoints by name.

Should every parameter include an example value?

Yes. Examples help developers understand the expected format without reading the full description. Use realistic values, not placeholder text.

How do I document endpoints with many parameters?

Use progressive disclosure: show the most common parameters first, then group optional parameters by category. Long parameter lists overwhelm readers.

What if the API changes frequently?

Generate reference docs from the OpenAPI spec during CI. Every deployment produces updated docs. This is the only way to keep reference docs in sync.

Mini Project: Build a Reference Page

Pick any REST API and write a complete reference page for three related endpoints. Include method, path, description, parameters table, request body, response schema, response example, and error codes. Use the same format for all three endpoints for consistency.

What's Next

Reference docs give developers the details. Now learn how to write Conceptual Documentation that explains the big picture. Then study Getting Started Guides for onboarding new users.

← Previous OpenAPI Structure and Syntax — Complete Guide Next → Conceptual Documentation — Complete Guide

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Api Documentation