Markdown API Documentation Examples

Most API documentation answers the same questions:

• What does this endpoint do?
• How do I authenticate?
• Which parameters are required?
• What does a successful response look like?
• What errors might occur?
• Are there usage limits or special requirements?

The examples below follow this structure so they're easy to adapt for your own API.

Every endpoint should start with a clear summary before introducing technical details.

# Get User Profile

Returns the profile information for the authenticated user.

## Endpoint

GET /api/users/me

## Authentication

Bearer Token

## Response

Returns the user's profile information.

Why this works

A developer can immediately understand the endpoint's purpose, HTTP method, and authentication requirements before reading the request or response examples.

Document every parameter that affects the request.

# Search Products

Search products using a keyword.

## Endpoint

GET /api/products

## Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| q | string | Yes | Search keyword |
| category | string | No | Filter by category |
| limit | integer | No | Maximum number of results |

Best for

• Search endpoints
• Filtering resources
• Public APIs

Authentication deserves its own section instead of being hidden inside a paragraph.

# Authentication

Include your API key in the request header.

```http
Authorization: Bearer YOUR_API_KEY
```

Requests without a valid API key will return a `401 Unauthorized` response.

Why this works

Developers usually look for authentication before anything else. Keeping it separate makes it easier to find.

Show a complete request that developers can adapt.

GET /api/products?category=laptops&limit=5 HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY
Accept: application/json

A realistic request helps developers verify that they're using the correct headers, method, and endpoint.

Examples should reflect actual API responses whenever possible.

{
  "id": 421,
  "name": "Mechanical Keyboard",
  "price": 89.99,
  "currency": "USD",
  "available": true
}

Why this works

Developers can immediately see the response structure without searching through multiple sections.

Good documentation prepares developers for failure as well as success.

Status: 404 Not Found

{
  "error": "Product not found"
}

Include the status code alongside the response body so developers know what to expect.

Large responses become easier to understand when each field is explained.

This approach works well for APIs with nested JSON responses or many returned properties.

Bringing everything together creates a page that developers can work from without switching between multiple documents.

# Create Product

Creates a new product.

## Endpoint

POST /api/products

## Authentication

Bearer Token

## Request Body

| Field | Type | Required |
|--------|------|:--------:|
| name | string | Yes |
| price | number | Yes |
| category | string | Yes |

## Success Response

201 Created

## Error Responses

- 400 Bad Request
- 401 Unauthorized
- 422 Validation Failed

Why this structure works

Every piece of information follows the same order—from overview to authentication, request, and response—making the documentation predictable and easy to navigate.

Most developers don't read API documentation from top to bottom. They usually arrive with a specific goal, such as creating a resource, authenticating a request, or fixing an error.

Well-organised documentation makes those answers easy to find.

A practical order for most API documentation is:

1. Endpoint overview
2. Authentication requirements
3. Request example
4. Parameters or request body
5. Successful response
6. Error responses
7. Notes and limitations

Keeping this order consistent across every endpoint reduces the learning curve and helps developers navigate your documentation more efficiently.

Regardless of the API, every endpoint should answer a few essential questions.

What Does This Endpoint Do?#

Start with a short summary.

Good

Creates a new customer account.

Less helpful

Customer Endpoint

A clear summary tells developers immediately whether they're in the right place.

---

Which HTTP Method Should I Use?#

Always display the method alongside the endpoint.

POST /api/customers

Avoid mentioning the endpoint only inside paragraphs, where it's harder to spot.

---

How Do I Authenticate?#

Authentication should never be hidden halfway through the page.

Include it near the top using a dedicated section.

## Authentication

Bearer Token required.

If different endpoints use different authentication methods, document each one separately rather than expecting readers to infer the difference.

---

What Should I Send?#

If an endpoint accepts input, document every field.

Developers shouldn't have to inspect example code to discover required fields.

---

What Will I Get Back?#

Include a realistic response example.

{
  "id": 42,
  "email": "alex@example.com",
  "status": "active"
}

Whenever possible, explain important fields below the example.

---

Which Errors Can Occur?#

Don't only document successful requests.

List common errors developers are likely to encounter.

Understanding possible failures helps developers troubleshoot integrations more quickly.

As APIs grow, consistency becomes more important than individual page design.

These patterns work well for both small and large documentation projects.

Keep Every Endpoint Consistent#

If one endpoint documents:

• Summary
• Authentication
• Parameters
• Request
• Response
• Errors

then every endpoint should follow the same structure.

Readers quickly learn where to look for information.

---

Separate Tutorials from Reference Documentation#

A tutorial teaches developers how to complete a task.

Reference documentation explains how an endpoint works.

For example:

Tutorial

Upload your first file.

Reference

POST /api/files

Keeping these separate helps readers find either guided learning or technical details without mixing the two.

---

Show Complete Requests#

Avoid partial examples that omit important information.

Instead of:

POST /users

Prefer:

POST /api/users HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Complete examples are easier to test and adapt.

---

Explain Limits and Requirements#

If an endpoint has restrictions, document them clearly.

Examples include:

• Maximum file size
• Supported formats
• Required permissions
• Rate limits
• Pagination limits
• Timeouts

Developers appreciate knowing these constraints before they encounter them.

Documenting Only Successful Requests#

Real-world integrations encounter validation errors, authentication failures, and missing resources.

Showing both successful and failed responses prepares developers for real usage.

---

Hiding Important Information Inside Paragraphs#

Authentication, endpoints, and required parameters should stand out visually.

Developers often scan documentation before reading it in detail.

---

Using Placeholder Responses That Never Occur#

Examples should resemble actual API responses.

Unrealistic examples make documentation less trustworthy and harder to apply.

---

Leaving Response Fields Unexplained#

Large JSON responses become difficult to understand without field descriptions.

A small response table often saves readers from guessing what each property represents.

---

Forgetting to Update Documentation#

Documentation should be reviewed whenever an endpoint changes.

Before publishing a new version, verify:

• Endpoints still exist.
• Parameters are accurate.
• Response examples match the latest API.
• Deprecated fields are removed or clearly marked.
• Code samples still work.

Accurate documentation builds confidence and reduces support requests.