Проектирование REST API: принципы, версионирование, документация

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

28 августа 2026 Технологии 16 мин чтения

---

Что такое REST API и что это значит для бизнеса

API (application programming interface, программный интерфейс) — набор правил, по которым одна программа обращается к другой. REST (representational state transfer) — самый распространённый стиль таких интерфейсов: обмен идёт по протоколу HTTP, данные адресуются как ресурсы, состояние между запросами сервер не хранит. Формат обмена почти всегда JSON, который одинаково читают и человек, и программа.

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

Через этот договор проходит почти всё: приложение забирает каталог и оформляет заказ, сайт показывает те же товары, учётная система отдаёт остатки и цены, платёжный сервис подтверждает оплату. У нас приложение и сайт интернет-магазина работают на единой Flutter-кодовой базе, поэтому один набор методов обслуживает оба канала продаж — расхождения «в приложении цена одна, на сайте другая» исключены устройством системы.

REST — не единственный вариант. Стиль обмена выбирают под задачу, и у соседних подходов есть области, где они объективно удобнее.

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

Что бизнес теряет на плохо спроектированном API

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

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

Принципы: ресурсы, методы, коды ответов

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

Ресурс — существительное, действие — метод

Адрес описывает объект, а не операцию: /orders, /orders/1024, /orders/1024/items. Действие задаётся методом протокола, а не словом в адресе. Адреса вида /getOrderById работают, но каждый новый разработчик читает их как отдельный словарь.

Коды ответов — не украшение

Код состояния — первое, на что смотрит клиентское приложение и любая система мониторинга. Ответ «200 OK» с текстом ошибки внутри — распространённая и дорогая привычка: снаружи всё выглядит исправным, поэтому сбой не попадает ни в один отчёт и обнаруживается по жалобам покупателей.

Разделение принципиальное: 4xx — клиент прислал что-то не то, повтор без изменений не поможет; 5xx — проблема на нашей стороне, повторить стоит. Из этого различия вырастает логика повторов в приложении.

Договор об обмене: формат ответа, ошибки, постраничный вывод

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

Единый вид ошибки

Ошибка — такая же часть договора, как успешный ответ. Клиентскому приложению нужно понять: что случилось, можно ли это исправить действием покупателя и что показать на экране. Достаточно машиночитаемого кода ошибки, короткого описания для разработчика и, при разборе форм, перечня полей с проблемами. Готовый формат описан в спецификации RFC 9457 — брать его целиком не обязательно, иметь один общий вид ошибки на весь интерфейс обязательно.

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

Постраничный вывод

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

Для бесконечной ленты товаров берут второй способ, для административной панели — первый. Ненормально их отсутствие.

Мелочи, которые экономят недели

• Даты — в одном формате и часовом поясе: ISO 8601 и время в UTC. Для сети магазинов в двадцати городах это условие, при котором отчёт по заказам сходится.
• Деньги — в наименьших единицах и целыми числами. Копейки вместо дробных рублей снимают целый класс расхождений при округлении.
• Фильтры и сортировка — из закрытого перечня. Свободная строка, попадающая прямо в запрос к базе, — уязвимость и источник медленных запросов.

Повторные запросы: идемпотентность и обмен событиями

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

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

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

Отдельная тема — обмен с учётной системой. Заказ, ушедший в 1С, и заказ, оставшийся только в базе магазина, — разные состояния, и различаться они должны в данных, а не в голове менеджера. Как выстраивается такой обмен — в описании услуги ERP-интеграции для интернет-магазина; передача заявок в систему продаж — в статье о CRM для интернет-магазина и на странице интеграции приложения с CRM.

Версионирование: как менять API и не ломать установленные приложения

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

Что считается ломающим изменением

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

Где ставить номер версии

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

Политика поддержки версий

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

1. Одновременно поддерживаются текущая версия и предыдущая. Три версии подряд означают тройную стоимость проверки каждого изменения.
2. Вывод старой версии объявляется заранее и подтверждается фактами. Дату называют в описании интерфейса и в письме потребителям, а перед отключением смотрят на реальную долю трафика: если на старой версии остаётся заметная часть покупателей, срок переносят.
3. Приложение умеет узнать, что пора обновиться. Отдельный метод с минимально поддерживаемой версией клиента снимает половину проблем с выводом старых версий.
4. Изменения фиксируются в журнале версий — с датой, описанием и пометкой, ломающее оно или нет.

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

Доступ: аутентификация, права и ограничение частоты запросов

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

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

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

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

Документация: OpenAPI и что даёт связка с Django и FastAPI

Документация API — не текстовый документ в облачном диске, а машиночитаемое описание интерфейса. Стандарт здесь один: OpenAPI Specification. Это файл, в котором перечислены все методы, параметры, форматы ответов и коды ошибок. Из него автоматически строится наглядная страница с описанием, генерируются заготовки клиентского кода и коллекции для проверки запросов.

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

На нашем стеке серверной части оба подхода закрываются штатными средствами. В разработке на FastAPI схема OpenAPI собирается из аннотаций типов и моделей данных — отдельного описания писать не нужно, а страница для проверки запросов доступна сразу; подробности — в документации фреймворка. В разработке на Django интерфейс строится на Django REST Framework, схема собирается по описаниям сериализаторов и представлений. Когда какой фреймворк уместнее, разобрано в статье о разработке на Django.

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

Типичные ошибки проектирования

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

1. Ошибка с кодом 200. Сбой не виден ни в мониторинге, ни в отчётах по доступности. Проблему находят по обращениям покупателей.
2. Ответ, повторяющий структуру таблиц в базе данных. Интерфейс намертво привязывается к текущему устройству хранения: любая перестройка базы становится ломающим изменением для приложения.
3. Деловая логика в клиентском приложении. Расчёт скидки или условий доставки на устройстве означает, что смена правил требует нового выпуска приложения и ожидания проверки в магазине.
4. Один метод «получить всё для экрана». Удобно на старте, но такой метод меняется при каждой правке вёрстки и постепенно превращается в самый дорогой в поддержке участок сервера.
5. Нет владельца интерфейса. Когда за договор между системами не отвечает конкретный человек, он расползается — быстро и незаметно.

Метрики: как понять, что API работает нормально

Проектирование не заканчивается первым выпуском. О состоянии интерфейса судят по нескольким показателям — все они снимаются штатными средствами мониторинга.

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

Чек-лист перед публикацией API

Короткий перечень, по которому проходят до того, как интерфейсом начнут пользоваться приложение, сайт и внешние подрядчики.

1. Все адреса построены вокруг ресурсов, действие задаётся методом протокола.
2. Коды ответов расставлены осмысленно: 4xx — ошибка запроса, 5xx — сбой на сервере.
3. У ошибок единый формат с машиночитаемым кодом; тексты для покупателя формирует клиентское приложение.
4. У каждого списка есть размер по умолчанию и верхняя граница; даты — в одном формате и часовом поясе, суммы — целыми числами в наименьших единицах.
5. Операции, задвоение которых видно в деньгах, защищены ключом операции; обработчики внешних событий переживают повторную доставку и проверяют подпись.
6. Версия зафиксирована в адресе, есть журнал изменений и объявленный порядок вывода старых версий.
7. Права проверяются на сервере при каждом обращении, настроено ограничение частоты запросов.
8. Персональные данные и токены не попадают в журналы и в ответы, где они не нужны.
9. Есть описание по стандарту OpenAPI и тестовое окружение с порядком получения доступа.
10. Снимаются метрики времени ответа, доли ошибок и распределения трафика по версиям.
11. У интерфейса есть ответственный, к которому идут вопросы по изменениям.

Сколько стоит работа над API и от чего зависит смета

Серверная часть с интерфейсом — кастомная разработка, поэтому и модель оплаты здесь другая, чем у продуктов на нашей модульной Flutter-платформе. Работаем в двух форматах: фиксированная цена по утверждённому техническому заданию, когда объём понятен заранее, и оплата по фактически затраченным часам (Time & Materials) — для развития и нетиповых задач. Разница между моделями разобрана в статье Fixed Price или Time & Materials, а из чего складывается смета — в материале о стоимости разработки ПО.

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

Кейс: серверная часть и API для сети «Сатурн»

Как перечисленное выглядит на реальном проекте — на примере федеральной сети строительных гипермаркетов. Данные приведены со страницы кейса.

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

Схожие задачи решались и в других проектах. В DAISYKNIT база и интеграции с 1С и Mindbox переносились со стороннего решения на собственный продукт — сохранность клиентской базы составила 100%. В Finn Flare перезапуск с серверной интеграцией Mindbox дал бюджет разработки в 2,5 раза меньше и скорость в 1,5 раза выше. В Gulliver Market персонализация витрины считается на сервере: приложение даёт 50% дохода бренда. Про события в системе автоматизации маркетинга — интеграция Mindbox с кастомными событиями.

Серверная часть в наших проектах строится на Python: интерфейс на Django REST Framework либо отдельные сервисы на FastAPI, PostgreSQL как основная база, очереди и фоновые задачи для рассылок и синхронизаций. Разворачивается в контейнерах с автоматической выкладкой и мониторингом — на инфраструктуре заказчика или в облаке; заказчик получает исходный код и документацию. Клиентские приложения при этом работают на модульной Flutter-платформе FITTIN — отечественном ПО в реестре российского ПО Минцифры (№ 2487103).

Итог: проектирование API на одной странице

REST API — это договор между системами, и относиться к нему стоит как к договору: заранее описать, зафиксировать порядок изменений и назначить ответственного. Короткий порядок действий:

1. Опишите методы до начала разработки. Список ресурсов, операций и интеграций — предмет договора и основа сметы.
2. Задайте общие правила один раз. Формат ошибки, постраничный вывод, даты, суммы, именование полей — одинаково во всех методах.
3. Защитите операции, задвоение которых видно в деньгах. Ключ операции при создании заказа и оплате, устойчивость обработчиков к повторам.
4. Договоритесь о версионировании до первого выпуска. Сколько версий живёт одновременно и как объявляется вывод старой.
5. Считайте документацию частью поставки. Описание OpenAPI, тестовое окружение и журнал версий передаются вместе с кодом.

Что делать дальше:

• Зафиксировать состав методов и интеграций документом — разработка технического задания.
• Посмотреть состав работ по серверной части — разработка на Django, разработка на FastAPI или разработка ПО на заказ.
• Проверить действующий интерфейс — аудит кода, комплексный аудит; посмотреть кейсы или описать задачу через контакты.

Вопросы и ответы

Что такое REST API простыми словами?

Это набор правил, по которым одна программа запрашивает данные у другой через интернет: приложение обращается к серверу за каталогом, сервер отвечает списком товаров в согласованном формате. Адрес описывает объект — заказ, товар, покупатель, — а действие над ним задаёт метод протокола HTTP. Для бизнеса это договор между системами: что можно запросить, что придёт в ответ и что произойдёт при ошибке.

Зачем нужно версионирование, если можно выпустить обновление приложения?

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

Какое изменение API считается ломающим?

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

Где ставить номер версии — в адресе или в заголовке?

Для продуктов с мобильным приложением обычно в адресе, вида /api/v1/orders: версия видна в журналах и в мониторинге, поэтому понятно, какая доля обращений идёт со старой версии и можно ли её выводить. Версия в заголовке оставляет адреса ресурсов постоянными и подходит для внутренних сервисов, которые обновляются вместе. Оба варианта рабочие; выбор фиксируется до первого выпуска.

Чем документировать API и кто это делает?

Стандарт описания — OpenAPI: машиночитаемый файл со всеми методами, параметрами, форматами ответов и кодами ошибок, из которого строится наглядная страница документации. На нашем стеке оно собирается из самого кода: в FastAPI — из аннотаций типов и моделей данных, в Django — по сериализаторам Django REST Framework. Ведёт его команда серверной части; к описанию прикладываются примеры вызовов, тестовое окружение и журнал версий.

Как защититься от задвоенных заказов при плохой связи?

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

Можно ли отдать наш API внешнему подрядчику или партнёру?

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

Сколько стоит разработка API и как считается срок?

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

Материал носит информационно-аналитический характер, отражает оценку команды FITTIN на дату публикации.