Версионирование REST API
Версионирование API — это поддержка в рабочем состоянии нескольких версий одного и того же метода. Версионирование API позволяет соблюдать требование обратной совместимости, вносить изменения без нарушения работы потребителей.
Как это работает
- Под номером версии фиксируется существующий контракт API, который используется потребителями.
- Если возникает необходимость внести изменения в существующий контракт, создаётся отдельная ветка под дорабатываемый метод.
- Изменения публикуются в новой версии метода API, при этом старая версия остаётся рабочей до тех пор, пока у неё есть потребители.
- Потребители сами решают, в какой момент они будут готовы перейти на новую версию метода.
Пример
Допустим, есть метод, который позволяет опубликовать статью в блоге:
POST /v1/articles
Метод принимает на вход в теле запроса следующие параметры, которые являются обязательными:
{
"text": "string",
"author": "string",
"title": "string"
}
Если мы добавим новый обязательный параметр category, не применяя версионирование API и не оповестив потребителей, то получим ситуацию, когда у потребителей будут возникать ошибки. Поэтому создаём новую версию метода:
POST /v2/articles
Изменённый запрос будет выглядеть так:
{
"text": "string",
"author": "string",
"title": "string",
"category": "string"
}
При этом старая версия метода (POST /v1/articles) продолжает работать.
Способы версионирования API
Префикс URI
Пример: GET /v1/users
✔️ Простой в проектировании, реализации и документировании
✖️ Создает большое количество дубликатов URL и может снизить производительность приложения
Параметр запроса
Пример: GET /users?version=v1
✔️ Рекомендуется, если важно HTTP-кеширование для повышения пропускной способности
✖️ Приводит к загрязнению URI, так как префиксы и суффиксы добавляются к основным строкам URI
HTTP заголовок запроса
Пример: GET /users, а версию передаём в headers: version=v1
✔️ Не приводит к загрязнению URI, легко реализовать
✖️ Приводит к неправильному использованию заголовков, т.к они нужны для метаинформации
Feature-версионирование
У клиента API есть набор фич. При отправке запроса сервер проверяет его набор фич и на этой основе сам определяет нужную версию для каждого клиента.
✔️ Можно использовать в качестве внутреннего API
✖️ Со временем фичи могут вступить в конфликт, если отвечают за одну и ту же часть бизнес-логики
Подборка материалов
- Делаем новую версию API. Быстро и легко
- Версионирование API или единая кодовая база для всех версий
- Как мы столкнулись с версионированием и осознали, что вариант «просто проставить цифры» не работает
- Карточки по версионированию API