Как сделать API понятным: единый стиль и предсказуемая структура

Хорошо спроектированный API работает по понятным и повторяемым правилам. Разработчик, изучив один эндпоинт, должен примерно представлять, как устроены остальные.

1. Единый стиль

Важно заранее выбрать единый стиль наименований: camelCase, snake_case или kebab-case. Конкретный вариант не так важен, как последовательность его использования. Если один эндпоинт называется /appleSignIn, другой — /google/sign-in, а поля в ответах оформлены в snake_case, интерфейс становится сложнее воспринимать и поддерживать.

То же самое касается форматов данных. Например, даты лучше всегда передавать в ISO 8601: 2026-07-15T14:30:00Z

Локальные форматы вроде «ДД.ММ.ГГ» могут интерпретироваться по-разному и создавать проблемы при работе с часовыми поясами.

Единообразной должна быть и структура ответов. Успешные запросы и ошибки одного типа желательно оформлять одинаково во всех эндпоинтах. Тогда клиентскому приложению не придется создавать отдельный обработчик для каждого метода.

2. Правильная структура

API удобнее строить вокруг ресурсов: пользователей, заказов, товаров, платежей и других сущностей системы:

• GET /getAllUsers
• GET /users
• POST /updatePrice
• POST /prices
• POST /products/{id}/prices

Связи между сущностями можно показывать через иерархию: GET /users/42/orders. Из такого адреса понятно, что запрос возвращает заказы пользователя с идентификатором 42. Названия ресурсов при этом лучше использовать во множественном числе: /users, /orders, /products. Это делает структуру единообразной и соответствует распространенной практике проектирования REST API.

3. Семантика HTTP-кодов

Используйте методы по назначению. GET используется для получения данных, POST — для создания нового ресурса, PUT — для его полной замены, PATCH — для частичного обновления, а DELETE — для удаления.

4. Коды ответов

Не стоит возвращать 200 OK, если внутри ответа фактически находится сообщение об ошибке. Клиентское приложение должно понимать результат запроса не только из текста, но и из стандартного HTTP-кода.

Успешное выполнение обычно обозначается кодами 200 OK или 201 Created. Ошибки на стороне клиента передаются через диапазон 4xx: например, 400 Bad Request, 401 Unauthorized, 403 Forbidden или 404 Not Found. Проблемы на стороне сервера относятся к диапазону 5xx.

Особенно важно одинаково трактовать коды авторизации. Например, 401 во всем API может означать, что пользователю необходимо войти в систему или обновить токен, а 403 — что пользователь авторизован, но у него недостаточно прав для конкретного действия. Благодаря этому фронтенд сможет использовать единый обработчик ошибок.

5. Пагинация, фильтрация, сортировка

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

Для пагинации можно использовать параметры page и per_page, для фильтрации — обычные query-параметры: GET /cars?color=red&brand=bwm

Формат сортировки также стоит унифицировать. Например: GET /users?sort=-created_at

В таком варианте знак минуса означает сортировку по убыванию. Главное, чтобы одинаковый принцип использовался для всех ресурсов.

6. Безопасность

Способ авторизации нельзя рассматривать как отдельную техническую деталь. Это такая же часть контракта, как структура запросов и ответов.

Шаг 1. Определите формат сразу. Выберите стандарт и способ передачи.

Шаг 2. Согласуйте общий флоу. Как клиент получает токен, как его обновляет и как понимает, что сессия истекла.

Шаг 3. Единые статус-коды. Договоритесь, что 401 — это всегда «нужен логин», а 403 — «нет прав конкретно на это действие». Это позволит фронтенду написать один глобальный обработчик ошибок для всей системы.

Предлагаю разобрать на примерах, как лучше с работать с API:

Пример № 1. Работа с профилем пользователя

В приложении имеются API-запросы для работы с профилем пользователя

• GET /users/profile — получить профиль пользователя
• PUT /users/profile — обновить профиль пользователя
• DELETE /users/profile/delete — удалить профиль пользователя

Из данного списка сразу же бросается в глаза DELETE /users/profile/delete — в частности то, что эндпоинт заканчивается на «/delete», хотя HTTP-метод «DELETE» уже явно указывает, что будет операция удаления.

В этом случае лучшим решением было бы использовать следующий список API-запросов:

• GET /users/profile
• PUT /users/profile
• DELETE /users/profile

Кратко, ясно, понятно, единообразно.

Пример № 2. Разный регистр имен в эндпоинтах

В приложении имеются API-запросы для авторизации через сторонние сервисы:

• POST /appleSignIn — авторизация через Apple
• POST /google/sign-in — авторизация через Google

Очевидно единый стиль через kebab-style был бы следующий:

• POST /apple/sign-in
• POST /google/sign-in

Оба примера объединены одной проблемой — отсутствие коммуникации и спешка на стороне клиента. Мобильное приложение выкатывала сборки раньше, чем это делал бэкенд.

Почему документация важна в проектировании API?

Документация — это единственный надежный способ общения между разработчиками. Без актуальной документации даже самое идеальное API превращается в «черный ящик», который все боятся трогать.

Почему документация критически важна:

1. Экономия времени. Хорошая документация избавляет бэкенд-разработчика от роли «говорящего справочника».
2. Снижение порога входа. Новый разработчик в команде или внешний партнер может начать работу с API за короткий срок.
3. Минимизация ошибок: Когда типы данных и обязательные поля описаны, клиент не гадает, может ли прийти null, а строит логику на основе контракта.

Писать документацию в Google-доке или Wiki — плохая идея. Она устареет через час после деплоя.

• OpenAPI (Swagger): позволяет генерировать интерактивную песочницу, где эндпоинты можно протестировать прямо в браузере.
• Один источник правды: документация должна генерироваться автоматически из кода или быть частью репозитория. Изменили код — обновилась схема API.

Признаки «здоровой» документации:

• Актуальность: Описание на 100% совпадает с реальностью.
• Наличие примеров: JSON-запросы и ответы для каждого успешного (200) и ошибочного (400, 401, 404) сценария.
• Описание ошибок: Не просто 400 Bad Request, а расшифровка: что именно пошло не так и как это исправить.
• Версионирование в документации: Если у вас есть v1 и v2, у них должны быть раздельные страницы или четкие пометки.

Как не сломать клиентское приложение: обратная совместимость, версионирование, зона ответственности

1. Обратная совместимость

Обратная совместимость — это «контракт» между сервером и клиентом. Главное правило: старый клиент должен продолжать работать с новым кодом сервера без ошибок.

К ломающим изменениям относятся удаление поля или эндпоинта, переименование ключей в JSON, изменение типа данных и новая трактовка статус-кодов. Например, если поле раньше содержало число, а затем начало возвращаться строкой, клиент может завершиться с ошибкой даже при успешном ответе сервера.

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

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

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

Пример № 3. Мобильное приложение отправляет статистику по действиям пользователя в приложении

Изначально приложение отправляло информацию по действию пользователя с успешным результатом. Бизнес захотел видеть внутренние уведомления если действие пользователя приводит к результату с ошибкой. API-запрос на бэкенде, который принимает действия пользователя был расширен таким образом, что новая версия приложения теперь помимо основных данных начала отправлять nullable-поле error_type — перечисление, где 0 — нет ошибки, 1 — ошибка№ 1, 2 — ошибка № 3 и тд. Бэкенд в свою очередь считает, если error_type не пришел, значит ошибки не было и error_type=0.

Было:
{
«data_id»: ‘string’, // required string
«ts»: «integer» // required integer
}

Стало:
{
«data_id»: ‘string’, // required string
«ts»: «integer», // required integer
«error_type»: «integer», // nullable integer
}

2. Версионирование

Версионирование — это способ управления изменениями, когда вы не можете сохранить 100% обратную совместимость. Это создание «параллельных миров», где старый и новый код живут одновременно.

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

Недостаток версирования — дорогой процесс (нужно поддерживать два кода), поэтому его используют, когда требуется масштабный рефакторинг, изменение логики, публичный контракт, критические изменения контракта API.

Как это реализовать технически — префиксы в URL:

• /api/v1/profile
• /api/v2/profile

Важное замечание: обычно так делают только мажорные версии.

3. Зона ответственности

Зона ответственности API — это одновременно и проблема и ее решение. В частности проблема возникает при росте продукта и кол-ва клиентов. Когда один API пытается угодить всем клиентам.

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

Лучшее решение в такой ситуации — паттерн Backend for Frontend. Вместо одного универсального API необходимо создавать тонкие адаптеры под каждый тип клиента.

Это важно по нескольким причинам:

• Разная производительность: Мобильному приложению нужно 3 поля, чтобы не тратить мобильный трафик, а десктоп-админке — 30 полей для таблиц.
• Разные жизненные циклы: Фронтенд-1 может обновляться ежедневно, а Фронтенд-2 — раз в месяц. Раздельные эндпоинты позволяют менять API для одного, не боясь сломать другого.
• Специфическая логика: Одному фронтенду нужны данные в формате копеек (целые числа), другому — в рублях (с запятой). API-адаптер берет эту «грязную» работу на себя.

Как это реализовать технически — префиксы в URL:

• /api/mobile/v1/profile
• /api/web/v1/profile

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

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