Как написать API-документацию, которой реально будут пользоваться партнеры?

API-документация, которой реально пользуются партнёры, — это не «описание эндпоинтов», а короткий путь от «получил доступ» до «первый успешный запрос» плюс понятные правила игры: авторизация, тестовая среда, лимиты, ошибки и изменения. Обязательный минимум: Quick Start, аутентификация, базовые сценарии, справочник ошибок, лимиты/квоты и версия/изменения. Всё остальное — вторично и должно поддерживать эти ключевые вопросы.

Технологическая логика: что партнёры пытаются сделать и где ломается интеграция

Партнёр обычно проходит один и тот же путь: получить ключи → понять, куда стучаться (prod/sandbox) → авторизоваться → отправить первый запрос → обработать ошибки → выдержать лимиты → поддерживать совместимость при изменениях. Поэтому документация должна отвечать не «что у нас есть», а «как это безопасно и стабильно интегрировать».

• Авторизация: без чётких шагов, примеров и частых ошибок интеграция не стартует.
• Тестовая среда: без sandbox партнёры тестируют на проде или просят вас «проверить руками».
• Лимиты и ретраи: без правил партнёр легко положит ваш API или получит нестабильность из‑за неправильной повторной отправки.
• Ошибки: без стандарта ошибок партнёр не сможет корректно отличать «попробуй позже» от «почини запрос».
• Изменения: без версионирования и changelog партнёры ломаются неожиданно и начинают избегать обновлений.

Что обязательно включить (структура, которой обычно хватает)

1) Быстрый старт (Quick Start) — 1 страница

• Цель: сделать 1–2 рабочих запроса за 10–15 минут.
• Шаги: как получить доступ (ключ/клиент), куда отправлять запросы (base URL), пример запроса и пример ответа.
• Минимальные требования: заголовки, формат даты/таймзоны, кодировка, JSON.
• Готовые команды: cURL/HTTP-пример (минимум) + один пример на популярном стеке (например, Node/Python) — если можете поддерживать актуальность.

2) Среды и доступы: production vs sandbox

• Base URLs для prod и sandbox.
• Как устроены тестовые данные: генерируете вы или партнёр, что можно удалять/сбрасывать, как часто происходит очистка.
• Отличия от продакшена: лимиты, заглушки, недоступные методы (лучше — никаких отличий, но если есть, фиксируйте).

3) Авторизация и безопасность

• Тип: API key, OAuth2, JWT, mTLS — и почему так (коротко).
• Пошагово: как получить токен/ключ, куда его класть (header), срок жизни, refresh.
• Примеры: корректный запрос + примеры типовых ошибок (не тот заголовок, просроченный токен).
• Ротация ключей, отзыв, IP allowlist (если применимо).
• Скоупы/права: какие операции чем ограничены.

4) Справочник API (reference) по эндпоинтам

• Единый стиль для каждого метода: назначение, URL, метод, параметры, обязательность, ограничения, примеры request/response.
• Модель данных: описание полей, типы, форматы, max length, допустимые значения, nullable.
• Пагинация, фильтры, сортировка — одним стандартом, а не «в каждом методе по-разному».
• Идемпотентность для операций создания/оплаты/заказов: ключ идемпотентности, срок хранения, поведение при повторах.

5) Ошибки и статусы ответов (самый используемый раздел после авторизации)

• Таблица HTTP-статусов, которые реально используются (200/201/204/400/401/403/404/409/422/429/5xx) и смысл каждого в вашем API.
• Единый формат ошибки: code, message, details, request_id, timestamp.
• Политика ретраев: какие ошибки можно повторять, с какой задержкой (особенно для 429/5xx), поддержка Retry-After.
• Корреляция: request_id для поиска в логах вашей поддержки.

6) Лимиты, квоты и политика нагрузки

• Rate limit: единицы измерения (RPS/RPM), per token/per IP/per client, окна (fixed/sliding).
• Что происходит при превышении: 429, заголовки лимитов, как корректно замедляться.
• Тяжёлые операции: отдельные лимиты или асинхронный режим.
• Рекомендации по батчингу и размеру пачки (если поддерживаете).

7) Типовые сценарии интеграции (playbooks)

• Сценарий 1: «Создать/обновить сущность» (клиент/заказ/лид) + дедупликация и upsert.
• Сценарий 2: «Получить изменения» — polling по updated_at или webhook’и.
• Сценарий 3: «Сверка/репликация» — как выгружать полный список и как устранять расхождения.
• Сценарий 4: «Обработка событий» — подпись webhook, повторная доставка, порядок событий, дедупликация.

Сценарии ценнее длинного справочника, потому что показывают правильную последовательность вызовов и нюансы (идемпотентность, дедупликация, ретраи).

8) Версионирование и changelog

• Правила версий: где живёт версия (URL /v1, заголовок, параметр) и что считается breaking change.
• Политика деприкации: срок поддержки старой версии, как заранее уведомляете.
• Changelog: только изменения, влияющие на интеграцию (поля, поведение, ошибки, лимиты), с датой и уровнем критичности.

9) Операционные вещи: поддержка и диагностика

• Статус API: хотя бы описание, как понять, что проблема на вашей стороне (5xx, повышенная задержка).
• Что присылать в поддержку: request_id, время, endpoint, пример запроса без секретов.
• SLA/время реакции (если есть) и каналы обращения (без лишней бюрократии).

Практическая рекомендация: как сделать, чтобы документацией пользовались

1. Начните с Quick Start и 3–5 ключевых сценариев, а справочник эндпоинтов дополняйте параллельно. Это быстрее приводит к успешным интеграциям.
2. Стандартизируйте ошибки (единый JSON-формат + request_id) и пропишите ретраи/429 — это сразу снижает нагрузку на поддержку.
3. Сделайте sandbox обязательным и описывайте отличия от prod. Если нет sandbox — хотя бы тестовые ключи и тестовые сущности с понятным жизненным циклом.
4. Дайте «копипастные» примеры: cURL, заголовки, полный URL, тело запроса и пример ответа. Партнёры читают примеры раньше текста.
5. Встройте changelog в процесс релизов: изменение API без записи в changelog — это гарантированные инциденты у партнёров.
6. Соберите 10 самых частых вопросов поддержки (авторизация, 401/403, 429, подпись webhook, пагинация) и вынесите их в FAQ прямо в доке.

Типичные ошибки

• Документация начинается с референса эндпоинтов, а не с Quick Start и сценариев — партнёр не понимает «как собрать интеграцию целиком».
• Нет чёткой спецификации ошибок: много текста, но непонятно, что делать программе (ретраить или фиксить запрос).
• Sandbox не соответствует продакшену или вообще отсутствует — интеграции тестируются на живых данных.
• Непрозрачные лимиты и отсутствие рекомендаций по backoff — партнёр получает нестабильность и винит API.
• Breaking changes без версий и деприкации — партнёры «замораживают» интеграцию и перестают обновляться.