Документация API: что должно быть, чтобы интеграция прошла быстро

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

Введение

Короткое описание: что умеет API, для кого он, какие основные сценарии. Адреса тестовой и рабочей среды. Формат данных. Контакты для вопросов. Разработчик должен за несколько минут понять, подходит ли API для его задачи.

Авторизация

Как получить ключ или токен, как передавать его в запросах, сколько он действует, как обновлять. Пример запроса с авторизацией. Без этого раздела разработчик застревает на первом шаге.

Методы

Для каждого метода:

• Назначение: что делает
• Адрес и HTTP-метод
• Параметры: название, тип, обязательность, допустимые значения, пример
• Тело запроса с примером
• Ответ с примером и описанием полей
• Возможные ошибки

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

Ошибки

Общий список кодов ошибок с объяснением причин и того, что делать. Формат сообщения об ошибке. Сообщение об ошибке должно говорить, что именно не так: какое поле и почему, а не просто «неверный запрос». Различие между ошибками клиента, которые нужно исправить в запросе, и временными ошибками сервера, после которых стоит повторить запрос.

Лимиты

Сколько запросов в секунду или минуту разрешено, что происходит при превышении, как узнать оставшийся лимит. Максимальный размер запроса, количество записей на страницу, правила постраничной выдачи.

Вебхуки

Если API отправляет уведомления о событиях: список событий, формат сообщений, как проверить подлинность уведомления, что происходит при недоступности получателя и сколько раз повторяется отправка.

Песочница и примеры

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

История изменений

Что изменилось в каждой версии, какие методы устарели и когда будут отключены. Партнёры должны узнавать об изменениях заранее, а не по ошибкам в рабочей системе.

Спецификация OpenAPI

Стандартный формат описания REST API в машиночитаемом виде. Из спецификации автоматически генерируется интерактивная документация, где можно отправлять запросы прямо со страницы, а также клиентские библиотеки и тесты. Если спецификация генерируется из кода, документация не отстаёт от реального поведения API.

Как поддерживать

Обновлять документацию в той же задаче, где меняется API, а не «потом». Проверять примеры автоматически. Собирать вопросы партнёров: повторяющийся вопрос означает, что в документации чего-то не хватает. Документация, которая расходится с реальным поведением, хуже её отсутствия, потому что вводит в заблуждение.

Если вы заказываете интеграцию

Попросите у поставщика внешней системы документацию до подписания договора и покажите её разработчику. Слабая или устаревшая документация — повод заложить больше времени на интеграцию. Хорошо, если у поставщика есть техническая поддержка для разработчиков с понятным каналом связи: вопросы по интеграции неизбежны даже при отличной документации.