Writing Endpoint Descriptions — Complete Guide

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

Endpoint descriptions tell developers what an API endpoint does in plain language, explaining the purpose, behavior, authentication requirements, size limits, async behavior, and any important caveats without simply restating what the URL and HTTP method already communicate.

What You'll Learn

How to write endpoint descriptions that are clear and informative, what information every description needs, how to avoid common pitfalls like restating the URL, how to document endpoint behavior including async processing, and how to describe error conditions.

Why It Matters

The endpoint description is the first thing developers read. A clear description tells them immediately whether this endpoint solves their problem. A vague or misleading description wastes their time and erodes trust in the documentation.

Real-World Use

The DodaTech API documentation team reviews every endpoint description for three things: does it explain what the endpoint does, does it mention any caveats, and does it include authentication requirements. Descriptions that pass this review are ready for publication.

Endpoint Description Anatomy

flowchart TD
  A[Endpoint Description] --> B[Action Verb]
  A --> C[What It Does]
  A --> D[Key Details]
  A --> E[Caveats]
  B --> F[Creates, Lists, Updates]
  C --> G[What data or operation]
  D --> H[Authentication, limits, async]
  E --> I[Size limits, rate limits, warnings]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

The Description Formula

Every endpoint description should follow this formula:

1. Start with an action verb
2. Explain what the endpoint does
3. Add key details (auth, limits, behavior)
4. Note any caveats or warnings

### List Files

`GET /v2/files`

Returns a paginated list of files in your organization, sorted by
creation date (newest first). Requires `files:read` scope.

**Details:**
- Pagination: 20 items per page (max 100)
- Sorting: `created_at` (default), `name`, `size`
- Filtering: Filter by status using the `status` parameter

**Caveats:**
- Files deleted within the last 30 days appear with status: deleted
- Rate limit: 1000 requests per hour

Good vs Bad Descriptions

Compare these endpoint descriptions for the same endpoint.

<!-- BAD: restates the URL -->
### Compress File

`POST /v2/files/compress`

Compresses a file.

<!-- GOOD: explains everything -->
### Compress a File

`POST /v2/files/compress`

Uploads or references a file and creates a compressed archive in your
chosen format. Returns a job ID for progress tracking.

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

**Important notes:**
- Files under 100 MB process synchronously (200 response)
- Files over 100 MB process asynchronously (202 response)
- Maximum file size: 1 GB
- Supported formats: zip, gzip, sevenz
- Optional AES-256 encryption via the password parameter

Describing Different Operations

Each HTTP method needs a slightly different description approach.

### Create a File

`POST /v2/files`

Uploads a new file to your file library. Returns the created file object
with a unique ID. Requires `files:write` scope.

### Get a File

`GET /v2/files/{fileId}`

Retrieves a file's metadata by its unique ID. Does not download the file
contents. Use the download endpoint for binary access.

### Update a File

`PATCH /v2/files/{fileId}`

Updates the metadata of an existing file, such as its name or status.
This is a partial update. Only the fields you send are modified.

### Delete a File

`DELETE /v2/files/{fileId}`

Permanently deletes a file and its associated archives. This action
cannot be undone. Requires `files:write` scope. The file is removed
immediately from list endpoints.

## Documenting Edge Cases

A good description also documents edge cases and unusual behavior.

```markdown
### Compress a File

`POST /v2/files/compress`

Creates a compressed archive from a file.

**Behavior by file size:**

| File Size | Processing | Response |
|-----------|-----------|----------|
| 0-100 MB | Synchronous | 200 with result |
| 100 MB - 1 GB | Async (job polling) | 202 with job_id |
| Over 1 GB | Rejected | 413 File Too Large |

**Edge cases:**
- Empty files: Returns 400 Bad Request
- Corrupted files: Job completes with status: failed
- Duplicate requests: Use Idempotency-Key header
- Rate limits: 10 compression requests per minute

## Common Mistakes

### 1. Restating the URL

Writing Compresses a file for POST /v2/files/compress adds no value. The URL already communicates this. Explain what compression means, what formats are supported, and how long it takes.

### 2. Passive Voice

Using The file is compressed instead of The API compresses the file. Active voice is clearer and more direct.

### 3. No Authentication Information

Not listing required scopes or authentication methods. Developers need to know what permissions to request.

### 4. Forgetting Size and Rate Limits

Not mentioning file size limits, rate limits, or other constraints causes developers to discover them through errors.

### 5. Vague Behavior Descriptions

Writing Processes the file without explaining whether it is synchronous or async, how long it takes, or how to get the result.

### 6. No Error Conditions

Not documenting what happens when things go wrong: invalid parameters, missing files, server errors.

### 7. Overly Technical Language

Using jargon like idempotent idempotency keys are supported without explaining what idempotency means and when to use it.

## Practice Questions

**1. What is the formula for a good endpoint description?**

Action verb + what it does + key details (auth, limits, behavior) + caveats or warnings. Start strong, provide context, and note important constraints.

**2. Why should descriptions avoid restating the URL?**

Restating the URL wastes space that could explain the endpoint's behavior, caveats, and use cases. Developers can read the URL themselves.

**3. What key details should every endpoint description include?**

Authentication requirements, rate limits or size limits, sync vs async behavior, response format, and when to use this endpoint versus similar ones.

**4. How do you describe endpoints with different behavior for different inputs?**

Document the behavior by input. Use a table showing size ranges and their corresponding processing modes and response types.

**5. Challenge:** Rewrite the descriptions for three endpoints from a public API that has poor documentation. Apply the description formula and include authentication, limits, and edge case information.

## FAQ

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">How long should an endpoint description be?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>2-5 sentences plus any additional details in a bullet list. Long enough to be clear, short enough to scan in 5 seconds. Use expandable sections for detailed notes.</p>
</div></details>

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">Should every endpoint description start with the same verb?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>No. Vary the verb to match the operation: Creates, Lists, Retrieves, Updates, Deletes, Compresses, Downloads. Starting with a verb makes the description action-oriented.</p>
</div></details>

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">Where do I document rate limits for a specific endpoint?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Include endpoint-specific rate limits in the endpoint description with a note: Rate limit: 10 requests per minute. Link to the general rate limiting page for details.</p>
</div></details>

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">How do I document endpoints that behave differently based on parameters?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Describe the default behavior first, then document parameter-specific behavior in the parameter section. Use a table if the behavior varies significantly by parameter values.</p>
</div></details>

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">Should endpoint descriptions include code examples?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>No. Code examples belong in a separate section below the description. The description itself should be prose explaining what the endpoint does.</p>
</div></details>

## Mini Project: Rewrite Endpoint Descriptions

Pick a public API with poorly written endpoint descriptions (generic, vague, or missing). Rewrite the descriptions for 5 endpoints using the formula from this lesson. Include authentication requirements, size limits, sync/async behavior, and edge case notes for each endpoint.

## What's Next

Good endpoint descriptions set the stage. Now learn to document the inputs with Writing Parameter Descriptions. Then explore Request Body Examples.