Системный Аналитик

Версионирование 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