Как описывать api

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

С чего начать описание

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

• HTTP-метод и путь;
• Назначение запроса;
• Обязательные и необязательные параметры;
• Формат тела, если оно есть;
• Формат ответа и коды статуса;
• Типичные ошибки и условия их появления.

Если описываете REST-интерфейс, следите за единообразием: одинаково называйте ресурсы, не смешивайте глаголы и существительные в путях, заранее определите, где используются path-параметры, а где query-параметры. Так документ легче читать и поддерживать.

Как писать параметры и ответы

Вопрос «как описывать api» часто упирается в детали полей. Для каждого поля пишите не только название, но и смысл, тип, обязательность, допустимые значения и ограничения. Если поле может быть пустым, объясните, чем «пусто» отличается от отсутствия поля. Если есть перечисления, приведите все варианты и значение каждого.

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

• Код статуса;
• Структуру тела ошибки;
• Человекочитаемое сообщение;
• Поле, с которым связана проблема, если это уместно.

Не забывайте о формате дат, времени, валюты и чисел. Эти вещи кажутся очевидными только внутри команды, а для внешнего потребителя они часто становятся источником сбоев.

Как сделать описание пригодным для интеграции

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

Для сложных сценариев полезно разнести описание по шагам. Например, отдельно описать получение токена, затем создание сущности, затем проверку статуса. Это особенно важно, когда один вызов зависит от результата другого.

Хорошая практика — держать рядом разделы:

• Аутентификация и авторизация;
• Форматы данных;
• Правила валидации;
• Лимиты и ограничения;
• Версии и совместимость.

Так читателю не приходится искать критичную информацию по всему документу.

Как проверить, что описание работает

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

Практичная проверка выглядит так:

1. Соберите запрос строго по документации;
2. Отправьте его в тестовую среду;
3. Сравните фактический ответ с описанным;
4. Проверьте ошибки на неверных данных;
5. Убедитесь, что примеры повторяются в актуальном виде.

Если документация меняется вместе с кодом, заведите правило: сначала меняется контракт, затем реализация, затем примеры. Иначе описание быстро устаревает. В итоге задача «как описывать api» сводится к одному принципу: писать так, чтобы у читателя оставалось минимум догадок и максимум проверяемых шагов.