Версионирование REST API

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

⚙️ Как это работает

1️⃣ Под номером версии фиксируется существующий контракт API, который используется потребителями

2️⃣ Если возникла необходимость внести изменения в существующий контракт, заводится отдельная ветка под дорабатываемый метод

3️⃣ Изменения публикуются в новой версии метода API, при этом старая версия остаётся рабочей до тех пор, пока у неё есть потребители

4️⃣ Потребители сами решают, в какой момент они будут готовы перейти на новую версию того или иного метода


✍️ Пример

Допустим, есть метод который позволяет опубликовать статью в блоге: 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