rest-api

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

На этапе проектирования API не стоит забывать об версионировании, это очень важная часть, которую нужно учесть.

Если Вы не позаботитесь о версионировании в момент проектирвоания, это может обратится «болью» в будущем.

Когда нужно увеличивать версию?

Зачастую версию API необходимо обновлять после внесения критических изменений. К критическим относятся:

  • Изменение конрактов/формата ответа
  • Изменение типов данных
  • Удаление любой части API

Версионировние

Можно выделить несколько подходов версионирования

  • Управление версией с помощью Url пути (route versioning)

Данный способ является наиболее простым.

https://api.<host>.net/token/v1.0/

https://api.<host>.net/v1.0/

  • Версионирование на уровне под-доменов

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

https://v1.api.<host>

  • Управление версией с помощью пользовательского заголовка (custom header)

GET https://<host>/tokens/get HTTP/1.1
Accept: application/json
Version: 1

GET https://<host>/tokens/get HTTP/1.1
Accept: application/json; version=2

Следующий код позволит также указать тип данных

GET https://<host>/tokens/get HTTP/1.1
Accept: application/vhd.<host>.tokens.v3+json

  • Параметр в строке запроса (query string parameter). Это плохая практика версионирования, поскольку вносит путаницу и добавляет сложность в вызовы.

https://<host>/tokens?version=v2

Рекомендации

Управление версией с помощью Url пути (route versioning), самый простой, надежный и более используемый метод.

Если поддерживается данный тип версионирования, намного проще поделится такой ссылкой и быть уверенной что все будет работать.

Если даже возникнут проблемы, из ссылки легко понять какая версия REST API используется.

0

Добавить комментарий