API Documentation: REST, GraphQL & SDK Docs Guide

API documentation is the reference manual that developers use to integrate with your service. Great API docs reduce support tickets, speed up integration, and improve developer experience. Whether you document a REST API, GraphQL endpoint, or an SDK, the principles remain the same: clarity, completeness, and accuracy.

In this tutorial, you’ll learn how to document REST APIs, GraphQL APIs, and SDKs with practical examples, common patterns, and tools that automate the process.

API Documentation Types

    flowchart TD
  A[API Documentation] --> B[REST API]
  A --> C[GraphQL API]
  A --> D[SDK/Library]
  B --> E[Endpoints & Methods]
  B --> F[Parameters & Headers]
  B --> G[Request/Response Examples]
  B --> H[Error Codes]
  C --> I[Schema & Types]
  C --> J[Queries & Mutations]
  C --> K[GraphiQL Explorer]
  D --> L[Installation]
  D --> M[Quickstart]
  D --> N[API Reference]
  D --> O[Code Examples]
  A:::current

  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px
  

REST API Documentation

REST APIs are the most common type of web API. Good REST docs include:

Endpoint Reference

Every endpoint needs: HTTP method, URL path, description, authentication requirements, parameters, request body, response format, and error codes.

## List Users

`GET /api/v1/users`

Returns a paginated list of users. Requires `users:read` scope.

### Parameters

| Parameter | Type   | Required | Description                        |
|-----------|--------|----------|------------------------------------|
| page      | number | No       | Page number (default: 1)           |
| per_page  | number | No       | Items per page (default: 20, max: 100) |
| sort      | string | No       | Sort field: `created_at` or `name` |

### Response

```json
{
  "data": [
    {
      "id": "usr_abc123",
      "email": "alice@example.com",
      "name": "Alice Johnson",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 142,
    "total_pages": 8
  }
}

Error Codes

### Code Examples in Multiple Languages

Show the same request in different languages:

```bash
# cURL
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.example.com/v1/users?page=1&per_page=20"

# Python
import requests

response = requests.get(
    "https://api.example.com/v1/users",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    params={"page": 1, "per_page": 20}
)
data = response.json()
print(data["data"])

// JavaScript
const response = await fetch(
  "https://api.example.com/v1/users?page=1&per_page=20",
  { headers: { Authorization: "Bearer YOUR_TOKEN" } }
);
const data = await response.json();
console.log(data.data);

OpenAPI / Swagger

OpenAPI is the industry standard for describing REST APIs. Write a spec, then generate docs from it:

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
  description: API for managing users
paths:
  /api/v1/users:
    get:
      summary: List all users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        "200":
          description: Paginated list of users
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserList"

Spec-first development keeps your docs in sync. Change the spec, regenerate the docs, and you never forget to document a field.

GraphQL Documentation

GraphQL APIs need different documentation. Instead of endpoints, you document types, queries, mutations, and subscriptions.

Schema Documentation

"""
A user in the system. Users can create posts and comment on existing posts.
"""
type User {
  "Unique identifier for the user"
  id: ID!
  "User's email address"
  email: String!
  "Display name"
  name: String!
  "When the user was created"
  createdAt: DateTime!
  "User's posts (paginated)"
  posts(first: Int, after: String): PostConnection!
}

Using GraphiQL

GraphiQL is an interactive in-browser IDE for GraphQL queries. It provides autocomplete, documentation explorer, and query execution. Embedding GraphiQL in your docs lets users experiment with real queries:

<iframe src="https://api.example.com/graphiql"
  width="100%" height="600" title="GraphQL Explorer">
</iframe>

Query Examples

# Get a user and their recent posts
query GetUserWithPosts($userId: ID!) {
  user(id: $userId) {
    name
    email
    posts(first: 5) {
      edges {
        node {
          title
          createdAt
        }
      }
    }
  }
}

SDK Documentation

SDK documentation focuses on getting started quickly:

Installation — One-command install:

npm install @example/api-client
# or
pip install example-api-client

Quickstart — Minimal code that does something useful:

from example_api import Client

client = Client(api_key="YOUR_API_KEY")
users = client.users.list()
print(f"Found {len(users)} users")

Reference — Auto-generated from docstrings:

class Client:
    def list_users(self, page: int = 1, per_page: int = 20) -> list[User]:
        """Fetch a paginated list of users.

        Args:
            page: Page number (default: 1)
            per_page: Items per page, max 100 (default: 20)

        Returns:
            List of User objects

        Raises:
            AuthenticationError: Invalid API key
            RateLimitError: Too many requests
        """

Authentication Documentation

Every API needs clear authentication docs. Show how to get credentials, how to use them, and what errors occur:

## Authentication

All API requests require an API key. Pass it in the `Authorization` header:

Authorization: Bearer YOUR_API_KEY

### Getting an API Key

1. Go to the [Dashboard](https://example.com/dashboard)
2. Navigate to Settings → API Keys
3. Click "Generate New Key"
4. Copy the key and store it securely

### Scopes

| Scope | Access |
|-------|--------|
| `users:read` | View users |
| `users:write` | Create, update, delete users |
| `analytics:read` | View analytics |
| `admin` | Full access |

**Security tip**: Store your API key in environment variables, never in code. At DodaTech, Durga Antivirus Pro scans all repos for accidentally committed keys.

Automated Documentation Tools

Keeping Docs in Sync

The biggest challenge is stale docs. Strategies to keep docs current:

Spec-first development: Write the OpenAPI spec before implementing the endpoint. Docs are always the source of truth.

CI validation: Add a CI step that validates the spec matches the implementation:

npm install -o @stoplight/spectral
spectral lint openapi.yaml

Automated diffs: Compare spec changes across versions in CI:

- name: Check API diff
  run: npm run api-diff openapi-v2.yaml openapi-v3.yaml

Common Mistakes

1. Missing Error Responses

Documenting only the happy path leaves developers guessing when things fail. Always include error response schemas and status codes.

2. No Code Examples

Endpoints without examples force developers to guess request formats. Show real JSON bodies and responses.

3. Outdated Samples

Code examples that use old endpoints or deprecated parameters erode trust. Automated testing of code examples catches this.

4. Single-Language Examples

Assuming all users work in one language excludes most of your audience. Provide at least cURL, Python, and JavaScript examples.

5. Ignoring Rate Limits

Every API has limits. Document them upfront — what’s the limit, what happens when you exceed it, and how to handle retries.

6. No Authentication Guidance

Missing auth docs is the number one support ticket generator. Show how to get keys, pass them, and what scopes are needed.

7. Manual Doc Generation

Copy-pasting endpoint docs into a CMS guarantees drift. Use spec-driven tools like Redoc or Stoplight that generate docs from OpenAPI specs.

Practice Questions

1. What information does every REST API endpoint reference need?

HTTP method, URL, description, auth requirements, parameters, request body, response format, and error codes with status codes.

2. How do OpenAPI specs help keep documentation in sync?

Spec-first development means the spec is written before the endpoint. Changes go through code review, and CI validates the spec matches the implementation.

3. Why should SDK docs include a quickstart section?

A quickstart gives users a working example in under a minute. This reduces activation time and gets developers to “it works!” faster.

4. What’s the best way to document GraphQL APIs?

Use GraphiQL for interactive exploration, document types with descriptions in the schema, and provide example queries and mutations.

5. Challenge: Pick a public API (GitHub, Stripe, or Twilio). Write complete documentation for one endpoint in OpenAPI 3.1 format, including parameters, request/response examples, error codes, and authentication. Generate a Redoc or Swagger UI page from it.

Real-World Task

Document an internal API at your organization or a side project. Write an OpenAPI spec, generate documentation with Redoc, add code examples in at least three languages, and set up a CI check that validates the spec.

FAQ

What’s Next