Проектирование API: как выбрать стиль, договориться о контракте и не переделывать через год

Кажется, что API появляется сам: написали серверную часть, открыли несколько адресов — готово. Проблемы начинаются на втором потребителе.

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

Каждое неудачное решение умножается. Странное имя поля, невнятный код ответа, отсутствие идентификатора запроса в ошибке — всё это придётся объяснять каждому новому потребителю, и объяснять будут ваши разработчики вместо работы.

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

Практический пример из наших проектов: у PetShop мобильное приложение вышло за две недели именно потому, что серверная часть была спроектирована как API-платформа, а не как приложение с прикрученными адресами. Как устроена серверная часть в целом, разобрано в материале про бэкенд.

Универсального ответа нет, но есть работающее правило выбора по типу потребителя.

Скучная часть, на которой экономят время, а потом платят поддержкой.

Ресурсы — существительные, действия — методы. `/orders`, `/orders/{id}`, `/orders/{id}/items`, а не `/getOrderList` и `/createNewOrder2`. Это не эстетика: предсказуемая схема позволяет партнёру угадывать адреса, не открывая документацию.

Коды ответов по назначению. 200 — успех, 201 — создано, 400 — ошибка в запросе, 401 — не аутентифицирован, 403 — нет прав, 404 — нет объекта, 409 — конфликт состояния, 422 — не прошла валидация, 429 — превышен лимит, 5xx — проблема на вашей стороне. Ответ «200 OK» с телом `{"error": "not found"}` ломает любую типовую обработку на клиенте.

Единый стиль имён. Один регистр, одинаковые названия для одних и тех же сущностей во всех методах, единый формат даты — ISO 8601 с часовым поясом. Смешанные `user_id` и `userId` в одном API стоят каждому интегратору по часу на выяснение.

Явные единицы измерения. `amount` в копейках или в рублях, `weight` в граммах или килограммах — пишется в документации и, желательно, в имени поля.

Самое дорогое, что можно пропустить. Сеть ненадёжна: клиент отправил запрос на создание заказа, ответ не дошёл из-за таймаута, клиент повторил. Без защиты у вас два заказа и два платежа.

Рабочее решение — ключ идемпотентности: клиент генерирует уникальный идентификатор операции (обычно UUID) и передаёт его в заголовке. Сервер запоминает результат по этому ключу и на повтор отдаёт тот же ответ, а не создаёт новую сущность. Именно так работает Stripe, и это фактический стандарт для платежных и заказных API.

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

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

Ошибка — это тоже часть контракта, и её формат проектируют так же, как успешный ответ. Минимальный набор в теле ответа:

• Машинный тип ошибки. Строковый код вроде `insufficient_stock`, по которому клиент строит логику. Не текст сообщения — тексты меняются.
• Человеческое сообщение. Что случилось, на языке пользователя, если ошибку планируют показывать.
• Детали по полям. Для валидации: какое поле не прошло и почему.
• Идентификатор запроса. Одна строка, по которой ваша поддержка находит запрос в логах. Экономит часы на каждом обращении.

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

Версия нужна не потому, что так принято, а потому что вы не можете обновить чужие клиенты по своему желанию.

Место, где API начинает падать на реальных объёмах.

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

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

Лимиты. Максимальный размер страницы задаётся на сервере, а не доверяется клиенту. Иначе первый же запрос с лимитом в сто тысяч записей станет инцидентом.

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

Три разные задачи, которые часто путают.

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

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

Лимиты. Ограничение частоты запросов защищает вас от чужой ошибки в цикле. Лимит должен возвращать код 429 и заголовок с временем, через которое можно повторить, — тогда нормальный клиент подстроится сам.

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

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

Контракт в формате OpenAPI — это машиночитаемое описание методов, параметров, схем данных и ошибок. Версия 3.1 полностью выровнена с JSON Schema, а обновление 3.2 добавило структурированную навигацию по тегам и стриминговые типы данных.

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

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

Три уровня, каждый закрывает свой класс проблем.

Контрактные тесты. Проверяют, что реализация соответствует OpenAPI: те же поля, типы, коды ответов. Ловят самый частый класс поломок — «поле переименовали, забыли предупредить».

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

Наблюдаемость в бою. Метрики по методам: частота, время ответа по перцентилям, доля ошибок 4xx и 5xx. Логи с идентификатором запроса. Алерт на рост доли ошибок у конкретного потребителя — часто это единственный способ узнать, что партнёр обновился и что-то сломал.

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

Требования отличаются радикально, и это стоит решить до проектирования.

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

Что отправлять. Событие с типом, идентификатором объекта и временем. Полное состояние объекта в теле — удобно, но означает, что вы отдаёте данные наружу без запроса; иногда правильнее отдать только идентификатор, а детали потребитель забирает сам.

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

Повторы и порядок. Получатель будет недоступен — это норма. Нужны повторы с растущими интервалами, ограничение числа попыток и журнал доставки. Порядок событий не гарантируется, поэтому у каждого события должны быть номер и время, а обработчик на стороне партнёра должен быть готов к дублям.

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

Чем это лучше опроса. Меньше пустых запросов, меньше задержка, ниже нагрузка на обе стороны. Но появляется новая обязанность: следить за доставкой и давать партнёру страницу с историей отправок, иначе разбор «мы не получили событие» превращается в переписку.

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

Ориентиры по нашим работам: отдельная интеграция или проектирование и разработка API под конкретный обмен — от 150 тыс. до 1,5 млн ₽, продукт с API-платформой под процесс — от 1,7 млн ₽, аудит существующего API и архитектуры — от 200 до 600 тыс. ₽. Точная сумма считается по числу методов и потребителей: оценка проекта бесплатная — опишите задачу.

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

Проектировать API под текущий экран. Через год интерфейс меняется, и сервер приходится переписывать вместе с ним.

Отдавать 200 на ошибку. Клиент не может отличить успех от неудачи стандартными средствами, и каждый интегратор пишет свою обработку.

Пропустить идемпотентность. Двойные заказы и платежи всплывают на первом же сетевом сбое, а добавлять защиту потом дороже.

Не заложить пагинацию. Метод «отдать всё» работает до первого крупного клиента.

Оставить документацию на потом. Она не появляется никогда, и её роль начинает исполнять ваш разработчик в переписке.

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

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

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

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