DEV Community

Cover image for A Practical Guide to Writing Clear API Documentation
Terry W
Terry W

Posted on • Edited on

A Practical Guide to Writing Clear API Documentation

#api #tutorial #documentation #productivity

A Practical Guide to Writing Clear API Documentation

  1. Introduction
  2. What Is an API?
  3. Why Good Documentation Matters
  4. Essential Parts of API Documentation
  5. Advanced Documentation Tips
  6. Best Practices I’ve Learned
  7. Conclusion

Introduction

APIs connect applications, services, and data sources. However, even a well-designed API can be difficult to use when its behaviour is not clearly documented.

This article covers the approach I use to document HTTP APIs, based on what I learned while building my NC News API.

By the end, you should have a practical structure for documenting a small API clearly and consistently.

What Is an API?

An API, or Application Programming Interface, defines how different pieces of software communicate.

For an HTTP API, this usually means documenting:

  • Which URLs are available
  • Which HTTP methods they accept
  • What data clients can send
  • What data the server returns
  • How authentication works
  • Which errors may occur

An API acts as a contract between the service providing the data and the application consuming it.

In my NC News API, clients can retrieve and modify users, articles, comments, and topics without needing to understand the underlying database structure.

Why Good Documentation Matters

Good documentation reduces the amount of guesswork required to use an API.

For API consumers

  • Faster onboarding: Developers can understand the API more quickly.
  • Fewer integration issues: Clear schemas and examples show what data is expected.
  • Less trial and error: Parameters, responses, and errors are defined upfront.
  • Better developer experience: Users can focus on building rather than reverse-engineering behaviour.

For API maintainers

  • Fewer support questions: Common issues can be answered directly in the documentation.
  • Greater consistency: The team has a shared reference for expected behaviour.
  • Improved API design: Documenting an endpoint often exposes unclear naming or inconsistent responses.
  • Safer changes: Versioning and deprecation notes help prevent unexpected breakages.

Essential Parts of API Documentation

1. Introduction and Overview

Begin with a concise explanation of what the API does and who it is intended for.

The NC News API provides access to users, topics, articles, and comments for a news discussion platform.
Enter fullscreen mode Exit fullscreen mode

You should also include any important prerequisites, such as authentication requirements or account setup.

2. Server and Base URLs

Provide complete URLs for the available environments.

Production: https://api.example.com/v1
Development: http://localhost:3000/api
Enter fullscreen mode Exit fullscreen mode

A relative path such as /api may be useful inside a project, but public consumers also need to know the host.

3. Authentication

Explain how protected endpoints are accessed.

For example:

Authorization: Bearer <access-token>
Enter fullscreen mode Exit fullscreen mode

Document:

  • How users obtain credentials
  • Where the token or key should be supplied
  • Whether particular roles or permissions are required
  • The difference between 401 Unauthorized and 403 Forbidden

Never place real tokens or credentials in published examples.

4. Endpoint Groups

Organise endpoints by resource so they are easier to scan.

For the NC News API, the groups might be:

  • API information
  • Users
  • Topics
  • Articles
  • Comments

Each endpoint should follow the same structure.

5. Method and Path

Clearly show the HTTP method and complete route.

GET /api/users
Enter fullscreen mode Exit fullscreen mode

The method matters because the same route may behave differently for GET, POST, PATCH, or DELETE.

6. Description

Explain what the endpoint does in one or two sentences.

Returns an array containing the public profile information for all users.
Enter fullscreen mode Exit fullscreen mode

Avoid repeating the path without explaining the result or purpose.

7. Parameters

Separate parameters by where they appear in the request.

Path parameters 

GET /api/users/:username
Enter fullscreen mode Exit fullscreen mode
Name Type Required Description
username string Yes Username of the requested user

Query parameters 

GET /api/articles?topic=coding&sort_by=created_at&order=desc
Enter fullscreen mode Exit fullscreen mode
Name Type Required Default Description
topic string No — Filter articles by topic
sort_by string No created_at Field used for sorting
order asc or desc No desc Sort direction

Also document allowed values, limits, and validation rules.

8. Request Bodies

For endpoints that accept a body, document the expected content type and fields separately from URL parameters.

POST /api/articles
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "title": "Writing Better API Documentation",
  "body": "Clear documentation reduces integration time.",
  "topic": "coding",
  "author": "butter_bridge"
}
Enter fullscreen mode Exit fullscreen mode

Include:

  • Required fields
  • Optional fields
  • Data types
  • Validation constraints
  • Whether unknown fields are accepted

9. Response Schemas

Examples are useful, but they should be supported by a description of the response structure.

Status: 200 OK
Content-Type: application/json
Body: Array<User>
Enter fullscreen mode Exit fullscreen mode

A User response might contain:

Field Type Nullable Description
username string No Unique username
name string No User’s display name
avatar_url string Yes URL of the user’s avatar

Example:

[
  {
    "username": "butter_bridge",
    "name": "jonny",
    "avatar_url": "https://example.com/avatar.jpg"
  }
]
Enter fullscreen mode Exit fullscreen mode

The schema explains what is guaranteed. The example shows what a real response may look like.

10. Error Responses

Document the important success and failure outcomes for each endpoint.

200 — Request succeeded
400 — Invalid request data
401 — Authentication required
403 — Insufficient permission
404 — Resource not found
409 — Request conflicts with existing data
500 — Unexpected server error
Enter fullscreen mode Exit fullscreen mode

Include an example error body:

{
  "status": 404,
  "msg": "User does not exist"
}
Enter fullscreen mode Exit fullscreen mode

Keep the error format consistent across endpoints where possible.

11. Pagination, Filtering, and Sorting

Collection endpoints often need more detail than a basic response example.

For an endpoint such as:

GET /api/articles
Enter fullscreen mode Exit fullscreen mode

document:

  • Default page size
  • Maximum page size
  • Pagination parameters
  • Available filters
  • Sortable fields
  • Default ordering
  • Response metadata
  • Behaviour when no results are found

Example:

{
  "articles": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 0,
    "total_pages": 0
  }
}
Enter fullscreen mode Exit fullscreen mode

Advanced Documentation Tips

Use OpenAPI for Larger APIs

Markdown and manually maintained JSON can work for smaller projects.

For larger APIs, consider using an OpenAPI document as the source of truth. It can describe:

  • Servers
  • Endpoints
  • Parameters
  • Request bodies
  • Response schemas
  • Authentication
  • Examples
  • Deprecated operations

OpenAPI documents can also be used by documentation generators, API clients, testing tools, and development environments.

Define a Versioning Policy

API versioning and software release versioning are related, but they are not the same thing.

An API may expose versions through its URL:

https://api.example.com/v1
Enter fullscreen mode Exit fullscreen mode

Your project releases may separately follow Semantic Versioning:

2.4.1
Enter fullscreen mode Exit fullscreen mode

Document:

  • What counts as a breaking change
  • How long older versions are supported
  • How consumers will be notified
  • How users should migrate

Document Deprecations

When an endpoint or field is being replaced, clearly state:

  • What is deprecated
  • Why it is being deprecated
  • What should be used instead
  • When it will be removed
  • How to migrate

Example:

Deprecated: GET /api/posts

Use GET /api/articles instead.

Planned removal: 1 December 2026
Enter fullscreen mode Exit fullscreen mode

Keep Documentation in Version Control

Documentation should change alongside the code.

Store it in the repository so changes can be:

  • Reviewed
  • Tracked
  • Updated in the same pull request as the implementation
  • Reverted when necessary

This reduces the chance of the documentation drifting away from the actual API behaviour.

Best Practices I’ve Learned

Balance Completeness with Clarity

Documentation should contain enough information for developers to use the API without making every endpoint difficult to scan.

A consistent template helps:

  1. Method and path
  2. Description
  3. Authentication requirements
  4. Parameters
  5. Request body
  6. Response schema
  7. Example request
  8. Example response
  9. Possible errors

Show, Don’t Just Tell

For an endpoint such as GET /api/articles, include:

  • A complete request URL
  • The available filters
  • A response schema
  • A realistic response example
  • Common error cases

Examples help developers quickly understand how the documented pieces fit together.

Use Consistent Terminology

Choose one name for each resource and use it throughout the API and documentation.

For example, avoid switching between:

  • Articles
  • Posts
  • Stories

unless those terms represent genuinely different resources.

Keep Examples Safe

When copying requests from a browser or API client, remove:

  • Authorization headers
  • Cookies
  • API keys
  • Session identifiers
  • Personal data

Published examples should use obvious placeholder values.

Quickly Copy cURL Requests

Browser developer tools can help generate example requests.

Open the Network panel, right-click a request, and choose the relevant copy option, such as Copy as cURL.

Copying cURL Requests From Network Tab

Review the command before publishing it, as copied requests may contain tokens, cookies, or other sensitive headers.

Maintain a Changelog

Keep a CHANGELOG.md file that records:

  • Release version
  • Release date
  • Added features
  • Behaviour changes
  • Bug fixes
  • Deprecations
  • Breaking changes

Semantic Versioning can communicate whether a release contains breaking, additive, or corrective changes, provided your public API and compatibility policy are clearly defined.

Conclusion

Good API documentation is part of the product rather than an afterthought.

It should explain not only which endpoints exist, but also how to authenticate, what data to send, what responses to expect, how errors are represented, and how the API will change over time.

Clear schemas, realistic examples, consistent terminology, and an accurate changelog make an API easier to adopt and safer to maintain.

Great documentation does more than explain how an API works. It gives developers enough confidence to build against it without relying on guesswork.

Top comments (0)