Definition
API documentation is the complete reference guide that teaches developers how to use an API. It includes endpoint descriptions, authentication methods, request/response schemas, code examples in multiple languages, error codes, rate limits, versioning policy, and getting-started tutorials. Good documentation is accurate, up-to-date, searchable, and includes interactive “try it out” functionality.
Unlike internal code documentation, API documentation is external-facing - it’s often the first and only interaction developers have with your API. If documentation is unclear, incomplete, or wrong, developers abandon the API for competitors. Great documentation reduces support tickets, accelerates integration time, and increases API adoption.
Modern API documentation is typically auto-generated from OpenAPI specifications using tools like Swagger UI, Redoc, or Stoplight. This ensures documentation stays synchronized with the actual API implementation. Interactive documentation lets developers make live API calls directly from the browser, dramatically reducing time-to-first-successful-call.
Example
Stripe Documentation: Stripe is famous for best-in-class API docs. They combine auto-generated reference docs from OpenAPI specs with hand-written guides, tutorials, and recipes. Every endpoint has code examples in 8+ languages, interactive “try it out” with test API keys, and detailed explanations of use cases.
Twilio SendGrid: SendGrid’s docs include a full API reference, getting-started guides for different languages, webhook event catalogs, and troubleshooting sections. Developers can test email sending directly in the docs without writing code first.
GitHub REST API: GitHub publishes comprehensive OpenAPI specs that power their interactive API documentation. Each endpoint includes descriptions, parameters, response schemas, and examples. They also version docs - you can view documentation for previous API versions.
Internal Microservices: A company with 50+ microservices maintains a central API portal using Backstage or similar tools. Each service publishes OpenAPI specs to the portal, auto-generating searchable documentation. Engineers discover APIs, understand schemas, and integrate services faster.
Postman Collections: Many companies publish Postman collections alongside traditional docs. Developers import the collection into Postman and immediately have working examples for every endpoint with pre-filled parameters and authentication.
Analogy
The Owner’s Manual: Just as a car comes with an owner’s manual explaining how to operate features, perform maintenance, and troubleshoot problems, API documentation explains how to use the API’s features, handle errors, and optimize usage. No one would buy a car with a missing or cryptic manual.
The Restaurant Menu: A good menu doesn’t just list dish names - it describes ingredients, shows photos, notes allergens, and suggests pairings. API documentation is the same - don’t just list endpoints, show examples, explain parameters, note rate limits, and suggest best practices.
IKEA Assembly Instructions: IKEA instructions are famous for clear, visual, step-by-step guidance that works across languages. API documentation should be equally clear - visual diagrams, sequential tutorials, and minimal jargon help developers regardless of expertise level.
Code Example
OpenAPI Spec with Rich Documentation
openapi: 3.1.0
info:
title: Payment Processing API
version: 2.0.0
description: |
Process payments, manage refunds, and handle subscriptions.
## Getting Started
1. Sign up for an API key at https://example.com/signup
2. Test in sandbox mode first: https://sandbox.example.com
3. Use `Bearer YOUR_API_KEY` in the Authorization header
## Rate Limits
- Standard plan: 1000 requests/hour
- Enterprise plan: 10000 requests/hour
## Support
- Email: [email protected]
- Slack: https://slack.example.com
contact:
name: API Support
email: [email protected]
url: https://example.com/support
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://api.example.com/v2
description: Production server
- url: https://sandbox.example.com/v2
description: Sandbox for testing
tags:
- name: Payments
description: Create and manage payment transactions
- name: Refunds
description: Process refunds for completed payments
paths:
/payments:
post:
tags: [Payments]
summary: Create a payment
description: |
Creates a new payment transaction. The payment is processed asynchronously.
Use webhooks to receive status updates.
**Common use cases:**
- One-time purchases
- Subscription initial payments
- Invoice payments
**Important notes:**
- Payments under $1 USD are rejected
- Idempotent - retry with same idempotency key if network fails
- Returns immediately with status "pending"
operationId: createPayment
parameters:
- name: [Idempotency](https://reference.apios.info/terms/idempotency/)-Key
in: header
description: |
Optional unique key to prevent duplicate charges.
Use the same key when retrying failed requests.
required: false
schema:
type: string
format: uuid
example: "550e8400-e29b-41d4-a716-446655440000"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentRequest'
examples:
creditCard:
summary: Credit card payment
description: Standard credit card charge
value:
amount: 99.99
currency: USD
paymentMethod:
type: credit_card
cardNumber: "4242424242424242"
expiryMonth: 12
expiryYear: 2025
cvv: "123"
description: "Order #12345"
savedCard:
summary: Using saved payment method
description: Charge a previously saved card
value:
amount: 49.99
currency: EUR
paymentMethod:
type: saved
paymentMethodId: "pm_1234567890"
description: "Subscription renewal"
responses:
'201':
description: |
Payment created successfully. Status is initially "pending".
Subscribe to webhooks to receive completion notifications.
headers:
X-Request-ID:
schema:
type: string
description: Unique ID for tracking this request
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
example:
id: "pay_1234567890"
status: "pending"
amount: 99.99
currency: "USD"
description: "Order #12345"
createdAt: "2024-01-15T10:30:00Z"
'400':
description: Invalid request data
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalidAmount:
summary: Amount too low
value:
code: "INVALID_AMOUNT"
message: "Amount must be at least $1.00 USD"
invalidCard:
summary: Invalid card number
value:
code: "INVALID_CARD"
message: "Card number failed validation"
'429':
description: Rate limit exceeded
headers:
X-RateLimit-Limit:
schema:
type: integer
description: Requests allowed per hour
X-RateLimit-Remaining:
schema:
type: integer
description: Requests remaining in current window
X-RateLimit-Reset:
schema:
type: integer
description: Unix timestamp when rate limit resets
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: "RATE_LIMIT_EXCEEDED"
message: "You have exceeded the rate limit of 1000 requests/hour"
components:
schemas:
CreatePaymentRequest:
type: object
required: [amount, currency, paymentMethod]
properties:
amount:
type: number
minimum: 1.00
description: Payment amount in the specified currency
example: 99.99
currency:
type: string
pattern: "^[A-Z]{3}$"
description: ISO 4217 currency code
example: "USD"
paymentMethod:
type: object
description: Payment method details
oneOf:
- $ref: '#/components/schemas/CreditCardPayment'
- $ref: '#/components/schemas/SavedPaymentMethod'
description:
type: string
maxLength: 500
description: Optional description for your reference
example: "Order #12345"
CreditCardPayment:
type: object
required: [type, cardNumber, expiryMonth, expiryYear, cvv]
properties:
type:
type: string
const: credit_card
cardNumber:
type: string
pattern: "^[0-9]{13,19}$"
description: Credit card number without spaces
example: "4242424242424242"
expiryMonth:
type: integer
minimum: 1
maximum: 12
example: 12
expiryYear:
type: integer
minimum: 2024
example: 2025
cvv:
type: string
pattern: "^[0-9]{3,4}$"
example: "123"
SavedPaymentMethod:
type: object
required: [type, paymentMethodId]
properties:
type:
type: string
const: saved
paymentMethodId:
type: string
description: ID of previously saved payment method
example: "pm_1234567890"
Payment:
type: object
properties:
id:
type: string
description: Unique payment identifier
example: "pay_1234567890"
status:
type: string
enum: [pending, completed, failed, refunded]
description: |
Current payment status:
- `pending` - Payment is being processed
- `completed` - Payment succeeded
- `failed` - Payment failed (see failureReason)
- `refunded` - Payment was refunded
amount:
type: number
example: 99.99
currency:
type: string
example: "USD"
description:
type: string
createdAt:
type: string
format: date-time
completedAt:
type: string
format: date-time
nullable: true
failureReason:
type: string
nullable: true
description: Human-readable reason if status is "failed"
Error:
type: object
required: [code, message]
properties:
code:
type: string
description: Machine-readable error code
example: "INVALID_AMOUNT"
message:
type: string
description: Human-readable error message
example: "Amount must be at least $1.00 USD"
details:
type: object
description: Additional error context
additionalProperties: true
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: |
Use your API key as a Bearer token:
```
Authorization: Bearer YOUR_API_KEY
```
Get your API key from https://example.com/dashboard/api-keys
security:
- BearerAuth: []
Diagram
graph TB
subgraph "API Documentation Components"
SPEC[OpenAPI Spec
Single Source of Truth]
SPEC --> REF[Reference Docs
Swagger UI, Redoc]
SPEC --> SDK[SDK Docs
Language-Specific]
GUIDES[Hand-Written Guides]
GUIDES --> QUICKSTART[Quick Start
First Call in 5min]
GUIDES --> TUTORIALS[Tutorials
Common Use Cases]
GUIDES --> RECIPES[Recipes
Code Examples]
EXTRA[Additional Resources]
EXTRA --> ERRORS[Error Catalog
All Codes Explained]
EXTRA --> CHANGELOG[Changelog
Version History]
EXTRA --> MIGRATION[Migration Guides
Upgrading Versions]
end
REF --> PORTAL[Developer Portal]
SDK --> PORTAL
QUICKSTART --> PORTAL
TUTORIALS --> PORTAL
ERRORS --> PORTAL
CHANGELOG --> PORTAL
PORTAL --> SEARCH[Searchable
Full-Text Search]
PORTAL --> INTERACTIVE[Interactive
Try It Out]
PORTAL --> FEEDBACK[Feedback System
Improve Docs]
style SPEC fill:#90EE90
style PORTAL fill:#87CEEB
style INTERACTIVE fill:#FFD700
Best Practices
- Start with getting started guide - Help developers make their first successful API call in <5 minutes
- Provide code examples - Show real, working code in multiple languages for every endpoint
- Make it interactive - Enable “try it out” functionality with test credentials
- Document errors thoroughly - Every error code with explanation, cause, and solution
- Keep in sync with implementation - Auto-generate from OpenAPI specs to prevent drift
- Version the documentation - Let developers view docs for older API versions
- Include real-world use cases - Show common scenarios and recommended patterns
- Make it searchable - Full-text search across all docs, examples, and guides
Common Mistakes
Outdated documentation: Docs describing API behavior that no longer exists. Auto-generate from specs to stay synchronized.
Missing error documentation: Only documenting success cases, ignoring error responses. Developers need to know how to handle failures.
No code examples: Abstract descriptions without concrete, working code. Show examples in popular languages.
Assuming knowledge: Using jargon or assuming familiarity with concepts. Explain clearly for newcomers.
No getting started guide: Jumping straight to API reference without a quick-start tutorial. Developers get lost.
Static documentation only: No interactive “try it out” capability. Developers have to set up local environments before testing.
Broken examples: Code examples that don’t actually work when copied. Test all example code.
No search functionality: Long documentation pages without search. Developers can’t find what they need quickly.