Endpoint Documentation — Complete Guide

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

Endpoint documentation describes a single API operation with its HTTP method, full URL path, plain-language description of what it does, parameters table, request body schema, response schema and example, and error codes for every possible failure mode.

What You'll Learn

How to structure a single endpoint documentation page, what to include in the description, how to organize parameters by location, how to present request body schemas, how to show response examples with realistic data, and how to document error codes per endpoint.

Why It Matters

Endpoint documentation is what developers use most. They visit a specific endpoint page to look up parameter formats, response structures, and error codes. Clear, well-organized endpoint docs reduce lookup time from minutes to seconds and prevent integration mistakes.

Real-World Use

The Stripe API reference documents each endpoint with method, path, description, parameters in a compact table, request example as a code block, response with schema and example, and error codes. The DodaTech API reference follows the same pattern for all compression and file management endpoints.

Endpoint Documentation Structure

flowchart TD
  A[Endpoint Doc] --> B[Method + Path]
  A --> C[Description]
  A --> D[Path Parameters]
  A --> E[Query Parameters]
  A --> F[Request Body]
  A --> G[Response]
  A --> H[Error Codes]
  A --> I[Code Examples]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Writing the Endpoint Description

The description should tell developers what the endpoint does in plain language, not just restate the URL.

### Compress a File

`POST /v2/files/compress`

Uploads or references a file and compresses it using the specified
format. Returns a job ID that you can poll for completion. For files
under 100 MB, compression completes synchronously. Larger files are
processed asynchronously.

**Authentication:** Requires `files:write` scope.

**Idempotency:** Use the `Idempotency-Key` header to prevent duplicate
compression jobs. The key must be unique per request.

Organizing Parameters by Location

Group parameters by where they appear in the request: path, query, header.

#### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fileId` | string | Yes | The unique ID of the file to compress. Format: `file_` followed by 16 alphanumeric characters. Example: `file_a1b2c3d4e5f6g7h8` |

#### Query Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `async` | boolean | No | false | Set to `true` to force async processing for files under 100 MB |
| `priority` | string | No | normal | Queue priority: `low`, `normal`, `high` |

#### Header Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `Idempotency-Key` | string | No | UUID that prevents duplicate processing |
| `X-Request-ID` | string | No | UUID for request tracing and support |

Request Body Documentation

Show the schema with required fields, types, and descriptions.

#### Request Body

The request body must be JSON with the following fields:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `format` | string | No | Compression format: `zip`, `gzip`, or `sevenz` (default: `zip`) |
| `level` | integer | No | Compression level 1-9 (default: 6). Higher levels produce smaller files but take longer |
| `password` | string | No | AES-256 encryption password (8-64 characters) |

**Example:**

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

## Response Documentation

Show both the schema and a realistic example.

```markdown
#### Response

| Field | Type | Description |
|-------|------|-------------|
| `job_id` | string (uuid) | Unique job identifier for 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 |
| `ratio` | number | Compression ratio (output / input) |
| `download_url` | string (uri) | URL to download the result. Expires in 24 hours |

**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"
}

## Code Examples

Include at least three language examples per endpoint.

```bash
# cURL
curl -X POST https://api.dodatech.com/v2/files/compress \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/report.pdf",
    "format": "zip",
    "level": 9
  }'

# Python
from dodatech import Client

client = Client(api_key="YOUR_KEY")
job = client.files.compress(
    file_url="https://example.com/report.pdf",
    format="zip",
    level=9
)
print(f"Job ID: {job.job_id}")

// JavaScript
const client = new DodaTech.Client({apiKey: "YOUR_KEY"});
const job = await client.files.compress({
  fileUrl: "https://example.com/report.pdf",
  format: "zip"
});
console.log(`Job ID: ${job.jobId}`);

Common Mistakes

1. Description Repeats the URL

Writing Compresses a file as the description for POST /v2/files/compress is redundant. The description should add context: Uploads a file and compresses it using the specified format.

2. Missing Example Values

Parameters without examples force developers to guess the format. Every field should show a realistic example value.

3. No Idempotency Documentation

Not documenting idempotency support causes duplicate processing when developers retry requests.

4. Incomplete Error Codes

Listing only success responses without error codes leaves developers unprepared for failures.

5. No Authentication Requirements

Endpoint documentation without authentication scopes forces developers to search other pages for permission information.

6. Unorganized Parameters

Mixing path, query, and header parameters in one table confuses developers about where to put each value.

7. No Asynchronous Processing Notes

Not documenting which requests are async and how to poll for results causes developers to expect immediate responses for long-running operations.

Practice Questions

1. What are the four parameter locations in endpoint documentation?

Path parameters (in the URL), query parameters (after ?), header parameters (in HTTP headers), and request body (in JSON or form data).

2. Why organize parameters by location?

Grouping by location helps developers quickly find where to place each parameter. Path and query parameters go in the URL, headers go in the header section, body goes in the request payload.

3. What should an endpoint description include beyond method and path?

What the endpoint does, authentication requirements, idempotency information, synchronous vs asynchronous behavior, file size limits, and any endpoint-specific notes.

4. Why include response schemas and examples?

Schemas show the structure and types. Examples show realistic values. Developers use schemas for validation and examples for understanding what the data looks like.

5. Challenge: Write complete documentation for one API endpoint including method, path, description, parameters by location, request body schema with example, response schema with example, error codes table, and code examples in three languages.

FAQ

Mini Project: Write Endpoint Documentation

Pick three related endpoints from a public API or your own project. Write complete documentation for each endpoint including method, path, description, parameters, request body, response schema, response example, error codes, and code examples in three languages.

What's Next

Endpoints define the API surface. Now dive deeper into Parameter Documentation for writing clear parameter descriptions. Then explore Response Documentation for documenting API responses.