[Перевод] Как управлять версиями веб-API?

внешний интерфейс программист web.py
[Перевод] Как управлять версиями веб-API?

Краткий комментарий:Этоfly.ioВ статье рассказывается о том, как они контролируют версии своего собственного REST API. Есть еще многоДругие технические статьи, я лично чувствую себя довольно хорошо, и заинтересованные студенты могут взглянуть.

Проектирование API — недооцененная тема, и существует так много замечательных статей о управлении версиями веб-API. Например:

Но сегодня я все же хочу поделиться статьей, надеюсь смогу что-то почерпнуть после ее прочтения. :)

Версии API

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

  1. Для обеспечения согласованности и стабильности;
  2. обратная совместимость версий;
  3. ОТДЫХ.

Для наилучшей реализации этих концепций в настоящее время существует три основных подхода к реализации различных версий API:

Версия тега в URI

curl https://example.com/api/v2/lists/

Анализируя номер версии в URI, клиент может получить доступ/v1/или/v2/и другие разные версии API.

Отметить версию в шапке

curl https://example.com/api/lists/3 \ 
-H 'Accept: application/vnd.example.v2+json'

Не отмечайте версию напрямую

curl https://example.com/api/lists/3

Что ж, у нас есть только последняя версия, так что давайте совместимо.

Отсутствие управления версиями может привести к загромождению API, поэтому мало кто в наши дни не занимается управлением версиями API. И здесь мы решили пометить версию как в URI, так и в заголовке HTTP. Давайте посмотрим на пример:

Допустим, мы создаем API для нашего приложения MightyList, через которое мы можем запросить набор данных:

curl https://mightyapp.com/api/v1/lists/3
...

{
  "listId": "3",
  "shopping": "Shoes, tie, umbrella, snorkel",
  "leisure": "Skiing, surfing, snorkeling ",
  "food": "bananas, peanut butter, spinach",
  "cost": "One hundred dollars"
}

Давайте сначала посмотрим на небольшое изменение в требованиях в приведенном выше примере.cost

Поле возвращает строку. И теперь наша команда разработчиков хочет сделать его числовым типом.

curl https://mightyapp.com/api/v1/lists/3
...

{
  "listId": "3",
  "shopping": "Shoes, tie, umbrella, snorkel",
  "leisure": "Skiing, surfing, snorkeling ",
  "food": "bananas, peanut butter, spinach",
  "cost": 100
}

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

Также есть серьезное изменение, такое как: списки становятся суперсписками, и необходимо добавить много новых полей и т. д. Такие серьезные обновления в основном уничтожат совместимость. В настоящее время обычной практикой является размещение URI в/v1/стали/v2/.

Поэтому теоретически любые изменения, влияющие на обратную совместимость, должны отражаться в номере версии, а пользователям будет предоставляться журнал изменений. Но если номер версии в URI обновляется независимо от размера изменения, снова создается слишком много версий.

  • Чтобы сохранить ясность состояния нашего приложения, мы хотим иметь номер версии в URI, представляющий версию продукта. Когда в продукт вносятся серьезные или фундаментальные изменения, версия URI изменится. Например, MightyList V1 использует/api/v1/, MightyList V2 использует/api/v2/.

  • Для незначительных изменений в текущей версии мы используем собственный HTTP-заголовок для его представления. Пользовательский заголовок, используемый автором, называется API-Version, а значением является дата в формате день-месяц-год.

Таким образом, мы можем предоставить журнал изменений для API, и пользователи также могут получить доступ к нужной им версии API, настроив дату версии, например:

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

Знать столбец:Аврора Ежедневно

Оригинальная ссылка:How to Version a Web API

Aurora Daily, побочный проект разработчиков Aurora, предлагает вам ежедневно читать три зарубежные технические статьи, добро пожаловать на внимание.

Категории