REST API для интеграции: что обязано быть в документации

За два года интеграций я перечитал десятки разделов документации к REST API - от банковских эквайрингов до складских систем и CRM. Разница между хорошей и плохой документацией REST API для интеграции чувствуется в первые 15 минут работы: либо я подключаю партнёрский сервис за один рабочий день, либо неделю переписываюсь с поддержкой, чтобы понять, почему ответ сервера не совпадает с примером в доках. Ниже - чек-лист того, что обязано быть в документации, если хотите, чтобы сторонние разработчики подключались к вашему API без созвонов и тикетов.

Что обязано быть в документации REST API для интеграции с первого экрана

Открываю документацию впервые - и первым делом ищу три вещи: базовый URL, список окружений и способ авторизации. Если этого нет на первом экране, я трачу минут двадцать на поиск по разделам, а клиент в это время платит за мои часы.

Минимальный набор для стартовой страницы:

• Базовый URL для продакшена и отдельно для песочницы (у T‑Bank и СДЭК, например, это разные домены, а не параметр в запросе)
• Версия API прямо в пути, например /v2/orders
• Схема аутентификации в одном абзаце, без отсылок к другим разделам
• Ссылка на готовую коллекцию Postman или спецификацию OpenAPI/Swagger, которую можно импортировать за одну минуту
• Changelog с датами и списком breaking changes
• Контакт поддержки для разработчиков, отдельный от общей формы обратной связи

Когда я подключал приём платежей через T‑Bank к магазину на WooCommerce, весь процесс занял часа три именно потому, что на стартовой странице документации сразу были ссылки на тестовые реквизиты и рабочий пример запроса создания платежа. Не пришлось листать десять разделов, чтобы собрать один рабочий curl.

Аутентификация и авторизация: что описывать разработчику партнёра

Тут разработчики документации регулярно экономят на объяснениях, а зря - именно на этом этапе интеграция чаще всего стопорится. Нужно явно писать не только «передайте токен в заголовке», а куда конкретно, в каком формате и что будет, если токен просрочен.

Отдельно указываю: для интеграций с CRM и хранением контактов клиентов данные обязаны лежать на серверах в РФ - это требование 152-ФЗ по локализации персональных данных, а не рекомендация для удобства. Если проектирую API или интеграцию с нуля, обычно закладываю это на этапе технического задания, а не после запуска. Такие задачи я обычно веду как разработку и документирование REST API для интеграции с внешними сервисами отдельным этапом проекта, потому что архитектура авторизации потом сложно переделывается без обратной несовместимости.

Эндпоинты, методы и параметры запросов

Список методов - это ядро документации, но именно тут чаще всего экономят на примерах. Для каждого эндпоинта должно быть:

• HTTP-метод и полный путь с указанием обязательных и опциональных параметров
• Тип каждого параметра (строка, число, ISO-дата) и ограничения по длине или диапазону
• Пример запроса с реальными, а не выдуманными значениями полей
• Пример успешного ответа целиком, а не фрагментом
• Пометка, идемпотентен ли метод, и если да - как передавать ключ идемпотентности

Идемпотентность отдельно проговариваю всегда, когда речь про платежи или заказы: в эквайринге T‑Bank повторный запрос с тем же idempotency-key не создаёт второй платёж, а просто возвращает результат первого. Без этой строчки в документации разработчик на стороне партнёра рано или поздно продублирует списание при повторной отправке формы.

Пример из практики - подключение бота на aiogram к внутреннему API склада для проверки остатков:

import aiohttp

async def get_stock(sku: str) -> dict:
    headers = {"Authorization": "Bearer " + API_TOKEN}
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.example.com/v1/stock/" + sku,
            headers=headers,
            timeout=aiohttp.ClientTimeout(total=5),
        ) as resp:
            resp.raise_for_status()
            return await resp.json()

Этот код я написал за 10 минут только потому, что в документации был готовый пример ответа с полями available, reserved и warehouse_id - не пришлось гадать структуру JSON методом проб и ошибок. Та же логика работает в n8n: если в доках есть точный пример тела ответа, HTTP Request node настраивается за один проход, без пяти тестовых вызовов подряд.

Форматы ответов, коды состояния и обработка ошибок

Больше всего времени я теряю не на списке эндпоинтов, а на неописанных ошибках. Хорошая документация REST API объясняет не только «что вернёт сервер, если всё хорошо», а что будет при неверном токене, лишнем поле или превышении лимита.

Обязательный минимум по ошибкам:

• Единый формат тела ошибки (обычно code, message, details) для всех эндпоинтов без исключений
• Таблица кодов состояния HTTP с расшифровкой именно для этого API, а не общая ссылка на спецификацию RFC
• Список бизнес-кодов ошибок помимо HTTP-статуса, например INSUFFICIENT_FUNDS или ADDRESS_NOT_FOUND для API расчёта доставки СДЭК
• Рекомендации по повторным запросам: какие ошибки временные и стоит ретраить, а какие - окончательные

Когда интегрировал расчёт стоимости доставки СДЭК в скрипт для Tilda, половина времени ушла не на сам запрос, а на разбор кодов ошибок вида «город не найден в справочнике» - в документации они были расписаны отдельной таблицей с примерами, что сильно ускорило отладку. Без такой таблицы пришлось бы перебирать варианты вручную по логам.

Версионирование API и политика обратной совместимости

Отдельный раздел про версии обязателен, если планируете вносить изменения после релиза, а планировать их придётся всегда. В документации должно быть явно написано:

• Как передаётся версия - в пути (/v1/, /v2/), в заголовке или через параметр запроса
• Срок поддержки предыдущей версии после выхода новой, с конкретной датой отключения, а не расплывчатым «в ближайшее время»
• Список изменений между версиями с пометкой breaking changes отдельно от некритичных доработок
• Канал уведомлений об изменениях - рассылка, вебхук на событие деприкейта, отдельная страница статуса

На практике видел разные подходы: банковские API обычно держат старую версию рабочей от 6 до 12 месяцев после релиза новой, а внутренние API среднего интернет-магазина иногда отключают старую версию через 2-3 недели, просто не предупредив партнёров. Второй вариант обходится дороже - я потом чиню сломанные интеграции в авральном режиме, и это всегда дороже, чем заранее прописанная миграция.

Песочница, тестовые данные и лимиты запросов

Без песочницы разработчик со стороны партнёра тестирует интеграцию на боевых данных, а это прямой путь к случайным платежам и заказам в проде. Документация обязана содержать:

• Отдельный URL и отдельные ключи доступа для тестового окружения
• Готовые тестовые данные: номера карт для эквайринга, тестовые адреса для расчёта доставки, тестовые номера заказов
• Значения лимитов запросов (rate limit) в цифрах: сколько запросов в секунду или в минуту, и что возвращает сервер при превышении
• Заголовки ответа с текущим остатком лимита, например X-RateLimit-Remaining
• Инструкцию по тестированию вебхуков, включая рекомендацию по туннелированию локального сервера на этапе разработки

У T‑Bank в песочнице для эквайринга есть готовый набор тестовых карт с разными сценариями - успешная оплата, отказ по недостатку средств, требование 3‑D Secure. Это экономит день разработки: не нужно гадать, какие данные подставить, чтобы проверить обработку отказа. Если в вашем API песочницы нет вообще, разработчики партнёра рано или поздно протестируют интеграцию боевым платежом, и это будет ваша проблема, а не их.

Частые вопросы

Нужна ли документация, если у API всего 3-4 эндпоинта?

Да, объём тут не главное. Даже на четыре метода уходит документация с авторизацией, форматом ошибок и примерами запросов - без этого разработчик партнёра потратит на подключение день вместо часа, просто читая исходный код или переписываясь с поддержкой.

Чем спецификация OpenAPI отличается от обычной документации в вики или Confluence

OpenAPI (Swagger) - это машиночитаемое описание, из которого можно сгенерировать клиентский код, коллекцию Postman и интерактивную площадку для тестов прямо в браузере. Текст в Confluence читают только люди, и он быстро расходится с реальным поведением API, если его не обновлять руками при каждом релизе. На практике удобнее держать оба формата: OpenAPI как источник правды для инструментов и обычный текст для объяснения бизнес-логики, которую в спецификацию не уложить.

Как часто нужно обновлять документацию после релиза

В идеале документация обновляется в том же пул-реквесте, что и код эндпоинта, до релиза, а не после жалоб от партнёров. Если так не получается, минимум - обновлять changelog в день выката изменений и отдельно предупреждать про breaking changes за 2-3 недели до отключения старой версии.

Что делать, если пример из документации не работает у партнёра

Сначала проверяю версию API и окружение - половина таких жалоб оказывается тестовым ключом, отправленным на продакшен-URL, или наоборот. Если пример действительно устарел, это сигнал, что документацию правили руками отдельно от кода, и стоит перейти на автогенерацию из OpenAPI-спецификации, чтобы такие расхождения не повторялись.