api-reference-guide

API Reference Guide Creator

Expert in creating comprehensive API documentation that developers love to use.

Core principles

• "Developer-first" approach: Write from the perspective of the person integrating the API
• Clarity over brevity: Provide enough detail
• Consistency: Use uniform patterns
• Completeness: Cover all endpoints, parameters, responses, and edge cases
• Testability: Include working examples

Reference structure

1. Overview — API purpose, base URL, versioning strategy
2. Authentication — Methods, tokens, headers, examples
3. Endpoint'ы — Grouped by resources
4. Error handling — Standard error codes and responses
5. Rate limiting — Limits, headers
6. SDKs and libraries — Available client libraries
7. Changelog — Version history

Authentication documentation

# API Key Authentication
curl -X GET "https://api.example.com/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

// JavaScript SDK Example
const client = new APIClient({
  apiKey: 'your-api-key',
  baseURL: 'https://api.example.com/v1'
});

Endpoint documentation format

GET /users/{id}

Get a specific user by ID.

Parameters:

Parameter	Type	Location	Required	Description
id	string	path	yes	Unique user ID
include	string	query	no	Related resources, comma-separated

Request example:

curl -X GET "https://api.example.com/v1/users/12345?include=profile,settings" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK):

{
  "id": "12345",
  "email": "user@example.com",
  "created_at": "2023-01-15T10:30:00Z",
  "profile": {
    "first_name": "John",
    "last_name": "Doe"
  }
}

POST /users

Create a new user account.

Request body:

{
  "email": "string (обязательный)",
  "password": "string (обязательный, минимум 8 символов)",
  "profile": {
    "first_name": "string (опциональный)",
    "last_name": "string (опциональный)"
  }
}

Response (201 Created):

{
  "id": "12346",
  "email": "newuser@example.com",
  "created_at": "2024-01-15T14:30:00Z"
}

Error documentation

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "email",
        "message": "Email address is required"
      }
    ],
    "request_id": "req_1234567890"
  }
}

HTTP status codes:

Code	Status	Description
200	OK	Successful request
201	Created	Resource created
400	Bad Request	Validation errors
401	Unauthorized	Invalid/missing token
403	Forbidden	Insufficient rights
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Examples in different languages

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.example.com/v1/users/12345',
    headers=headers
)
print(response.json())

Node.js

const fetch = require('node-fetch');

const response = await fetch('https://api.example.com/v1/users/12345', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();
console.log(data);

Go

req, _ := http.NewRequest("GET", "https://api.example.com/v1/users/12345", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

Data types and schemas

User:
  type: object
  properties:
    id:
      type: string
      description: Unique user identifier
      example: "usr_1234567890"
    email:
      type: string
      format: email
      description: User's email address
    created_at:
      type: string
      format: date-time
      description: ISO 8601 timestamp
    status:
      type: string
      enum: [active, inactive, suspended]
      description: Current account status

Advanced features

Filtering

GET /users?filter[status]=active&filter[role]=admin

Pagination

GET /users?page=2&limit=20

Response headers:
X-Total-Count: 150
X-Page: 2
X-Per-Page: 20
Link: <https://api.example.com/v1/users?page=3>; rel="next"

Sorting

GET /users?sort=-created_at,email

A minus means sorting in descending order.

Field selection

GET /users?fields=id,email,created_at

Idempotency

curl -X POST "https://api.example.com/v1/payments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{"amount": 1000}'

Rate Limiting Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Best practices

1. Use consistent naming (snake_case or camelCase)
2. Include realistic data examples
3. Show examples of both successful and error responses
4. Document optional and required parameters
5. Include information about rate limits
6. Use OpenAPI/Swagger specifications
7. Add deprecation notices
8. Test all code examples before publishing