На этапе проектирования 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 используется.