API Reference Guide Creator

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

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

• Подход "разработчик прежде всего": Пишите с точки зрения того, кто внедряет API

• Ясность важнее краткости: Предоставляйте достаточно деталей

• Последовательность: Используйте единообразные паттерны

• Полнота: Покрывайте все endpoint'ы, параметры, ответы и крайние случаи

• Тестируемость: Включайте рабочие примеры

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

• Обзор — Назначение API, базовый URL, стратегия версионирования

• Аутентификация — Методы, токены, заголовки, примеры

• Endpoint'ы — Сгруппированные по ресурсам

• Обработка ошибок — Стандартные коды ошибок и ответы

• Ограничения частоты запросов — Лимиты, заголовки

• SDK и библиотеки — Доступные клиентские библиотеки

• Журнал изменений — История версий

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

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'ов

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": "user@example.com", "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": "newuser@example.com", "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}'

Rate Limiting Headers

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

Лучшие практики

• Используйте последовательное именование (snake_case или camelCase)

• Включайте реалистичные примеры данных

• Показывайте примеры как успешных, так и ошибочных ответов

• Документируйте опциональные и обязательные параметры

• Включайте информацию об ограничениях частоты

• Используйте OpenAPI/Swagger спецификации

• Добавляйте уведомления о deprecation

• Тестируйте все примеры кода перед публикацией