api-reference-guide

Создатель справочников по API

Эксперт по созданию комплексной документации по API, которой разработчики любят пользоваться.

Основные принципы

• Подход «разработчик прежде всего»：Пишите с точки зрения того, кто внедряет API
• Ясность важнее краткости：Предоставляйте достаточно подробностей
• Последовательность：Используйте единообразные шаблоны
• Полнота：Описывайте все конечные точки, параметры, ответы и крайние случаи
• Тестируемость：Включайте рабочие примеры

Структура справочника

1. Обзор — Назначение API, базовый URL, стратегия версионирования
2. Аутентификация — Методы, токены, заголовки, примеры
3. Конечные точки — Сгруппированные по ресурсам
4. Обработка ошибок — Стандартные коды ошибок и ответы
5. Ограничение частоты запросов — Лимиты, заголовки
6. SDK и библиотеки — Доступные клиентские библиотеки
7. Журнал изменений — История версий

Документация по аутентификации

# 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'
});

Формат документации конечных точек

GET /users/{id}

Получить конкретного пользователя по ID.

Параметры：

Параметр	Тип	Место	Обязательный	Описание
id	string	path	да	Уникальный ID пользователя
include	string	query	нет	Связанные ресурсы через запятую

Пример запроса：

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

Ответ（200 OK）：

{
  "id": "12345",
  "email": "[email protected]",
  "created_at": "2023-01-15T10:30:00Z",
  "profile": {
    "first_name": "John",
    "last_name": "Doe"
  }
}

POST /users

Создать новую учётную запись пользователя.

Тело запроса：

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

Ответ（201 Created）：

{
  "id": "12346",
  "email": "[email protected]",
  "created_at": "2024-01-15T14:30:00Z"
}

Документация по ошибкам

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

Коды состояния HTTP：

Код	Статус	Описание
200	OK	Запрос выполнен успешно
201	Created	Ресурс создан
400	Bad Request	Ошибки проверки данных
401	Unauthorized	Неверный или отсутствующий токен
403	Forbidden	Недостаточно прав
404	Not Found	Ресурс не найден
429	Too Many Requests	Превышен лимит запросов
500	Internal Server Error	Ошибка сервера

Примеры на разных языках

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()

Типы данных и схемы

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

Расширенные возможности

Фильтрация

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

Пагинация

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"

Сортировка

GET /users?sort=-created_at,email

Знак минус указывает на сортировку по убыванию.

Выбор полей

GET /users?fields=id,email,created_at

Идемпотентность

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}'

Заголовки ограничения частоты запросов

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

Рекомендации

1. Используйте последовательное именование（snake_case или camelCase）
2. Включайте реалистичные примеры данных
3. Приводите примеры как успешных ответов, так и ответов с ошибками
4. Документируйте необязательные и обязательные параметры
5. Включайте информацию об ограничениях частоты запросов
6. Используйте спецификации OpenAPI/Swagger
7. Добавляйте уведомления об устаревании
8. Проверяйте все примеры кода перед публикацией