API Reference Template for Product Managers

What This Template Is For

API documentation is the first thing developers evaluate when deciding whether to integrate with your product. If the docs are incomplete, poorly organized, or out of date, developers leave and pick a competitor with better documentation. The cost is invisible because you never see the signups that did not happen.

This template provides a structured format for documenting REST APIs. It covers authentication, endpoint descriptions, request and response schemas, error codes, rate limits, pagination, and versioning. The structure works for internal APIs consumed by your own frontend teams and for public APIs consumed by third-party developers. If you are building a developer platform, pair this with a getting started guide to walk developers through their first successful API call. For broader documentation strategy, see the Knowledge Base Template and the Technical PM Handbook for guidance on managing technical products.

The goal is a reference that developers can scan in under 60 seconds to find the endpoint they need, understand the request format, and handle errors correctly.

When to Use This Template

• Launching a new API. Document endpoints before the first external developer sees them.
• Onboarding internal teams. Frontend developers and mobile teams need the same clarity as external consumers.
• Preparing for a developer program. Public APIs require polished docs on day one. You do not get a second chance to make a first impression with developers.
• Migrating or versioning an API. Breaking changes need clear migration guides. This template includes a versioning section for that purpose.
• Auditing existing docs. If your current API docs are scattered across wikis, READMEs, and Slack threads, use this template to consolidate them into a single source of truth.

How to Use This Template

1. Copy the blank template into your documentation platform (GitBook, ReadMe, Notion, or a docs-as-code repo).
2. Start with the authentication section. Every developer needs this before they can call a single endpoint.
3. Document each endpoint group. Use one section per resource (users, projects, invoices).
4. Include real request and response examples. Developers copy and paste from docs. Make it easy.
5. Define your error code table. Consistent error responses reduce support tickets by 30-40%.
6. Document rate limits upfront. Developers build retry logic based on what you tell them here.
7. Review with an engineer who did not build the API. If they can follow the docs, external developers can too.

The Template

API Overview

• Base URL: https://api.yourproduct.com/v1
• Protocol: HTTPS only
• Format: JSON (request and response bodies)
• Character Encoding: UTF-8
• API Version: v1

Authentication

• ☐ Document the authentication method (API key, OAuth 2.0, JWT, or bearer token)
• ☐ Explain where to find or generate credentials
• ☐ Show the header format for authenticated requests
• ☐ List the available scopes or permissions (if using OAuth)
• ☐ Note token expiration and refresh procedures

Authentication Header Format:

Authorization: Bearer YOUR_API_KEY

Endpoints

For each endpoint, document the following:

[Resource Name] (e.g., Users, Projects, Invoices)

[METHOD] /resource

Request Headers:

Request Parameters:

Request Body (POST/PUT):

{
  "field_name": "value",
  "nested_object": {
    "sub_field": "value"
  }
}

Response (200 OK):

{
  "id": "abc123",
  "field_name": "value",
  "created_at": "2026-03-05T12:00:00Z",
  "updated_at": "2026-03-05T12:00:00Z"
}

Error Responses:

Error Codes

• ☐ Define a consistent error response format across all endpoints
• ☐ Include a machine-readable error code and a human-readable message
• ☐ Document every possible error code with resolution steps

Standard Error Response Format:

{
  "error": {
    "code": "invalid_request",
    "message": "The 'email' field is required.",
    "status": 400,
    "request_id": "req_abc123"
  }
}

Rate Limits

• ☐ Document the rate limit per authentication level (free, standard, enterprise)
• ☐ Explain the response headers that communicate limit status
• ☐ Describe the retry strategy developers should implement

Rate Limit Response Headers:

Pagination

• ☐ Choose a pagination strategy (offset, cursor, or keyset)
• ☐ Document the pagination parameters and response metadata
• ☐ Explain default and maximum page sizes

Pagination Response Metadata:

{
  "data": [...],
  "meta": {
    "total": 342,
    "page": 1,
    "per_page": 25,
    "total_pages": 14,
    "next_cursor": "eyJpZCI6MTAwfQ=="
  }
}

Versioning

• ☐ Document the current API version and how it is specified
• ☐ Explain the deprecation policy and timeline for old versions
• ☐ Describe what constitutes a breaking change

Versioning method: URL path (/v1/resource). The API version is part of the base URL. When a new major version is released, the previous version remains available for at least 12 months.

Filled Example: TaskManager API v1

API Overview

• Base URL: https://api.taskmanager.io/v1
• Protocol: HTTPS only
• Format: JSON
• Authentication: Bearer token (API key)

Authentication

All requests require an API key passed in the Authorization header:

Authorization: Bearer tm_live_abc123def456

API keys are generated in Settings > Developer > API Keys. Each key is scoped to a workspace. Never share keys in client-side code. Use environment variables on the server.

GET /tasks

Retrieve a paginated list of tasks for the authenticated workspace.

Parameters:

Response (200 OK):

{
  "data": [
    {
      "id": "task_001",
      "title": "Implement OAuth 2.0 login",
      "status": "in_progress",
      "assignee": {
        "id": "user_042",
        "name": "Sarah Chen"
      },
      "priority": "high",
      "created_at": "2026-03-01T09:00:00Z",
      "updated_at": "2026-03-04T14:30:00Z"
    }
  ],
  "meta": {
    "total": 187,
    "per_page": 25,
    "next_cursor": "eyJpZCI6InRhc2tfMDI2In0="
  }
}

POST /tasks

Create a new task.

Request Body:

{
  "title": "Add bulk export to CSV",
  "description": "Users need to export task lists to CSV for reporting.",
  "status": "open",
  "priority": "medium",
  "assignee_id": "user_042",
  "due_date": "2026-03-15"
}

Response (201 Created):

{
  "id": "task_188",
  "title": "Add bulk export to CSV",
  "status": "open",
  "priority": "medium",
  "created_at": "2026-03-05T10:00:00Z"
}

Error (422 Validation):

{
  "error": {
    "code": "validation_error",
    "message": "The 'title' field is required and must be between 1 and 255 characters.",
    "status": 422,
    "request_id": "req_789xyz"
  }
}

This example follows the same patterns described in the Technical PM Handbook, where API design decisions are treated as product decisions. The error response format aligns with the documentation standards that most developer-facing products adopt.

Key Takeaways

• Start with authentication. Developers cannot call anything until they understand how to authenticate.
• Show real request and response examples for every endpoint. Developers copy and paste from docs. If your examples are wrong or missing, integration takes 3x longer.
• Define a consistent error format. Machine-readable error codes reduce debugging time and support tickets.
• Document rate limits before developers hit them. Surprises cause frustration and poorly built retry logic.
• Use a versioning strategy from day one. Retrofitting versioning onto an unversioned API is painful for everyone.
• Review docs with an engineer who did not build the API. Fresh eyes catch assumptions that insiders overlook.

About This Template

Created by: Tim Adair

Last Updated: 3/5/2026

Version: 1.0.0

License: Free for personal and commercial use