В публичное api внесено обратно несовместимое изменение какая версия

Руководство по Публикация нескольких версий API

Иногда нецелесообразно предоставлять всем вызывающим сторонам одну версию API. Если вызывающим сторонам требуется выполнить обновление до более поздней версии, они хотят, чтобы сделать это было просто. Как показано в этом учебнике, в Управлении API Azure можно использовать несколько версий.

Дополнительные сведения см. в разделе «Версии и редакции».

В этом руководстве описано следующее:

• добавление новой версии в существующий интерфейс API;
• выбор схемы версии;
• Добавление версии в продукт
• Обзор портала разработчика для просмотра версии

Необходимые компоненты

• Ознакомьтесь с терминологией службы управления API в Azure.
• Выполните задачи в кратком руководстве по созданию экземпляра службы управления API Azure.
• Также выполните задачи из руководства по импорту и публикации первого API.

Добавление новой версии

1. Перейдите к экземпляру Управления API на портале Azure.
2. Выберите Интерфейсы API.
3. В списке API выберите Demo Conference API.
4. Выберите контекстное меню (. ) рядом с элементом Demo Conference API.
5. Выберите Добавить версию.

Версии также могут быть включены при создании API. На экране Добавление API выберите элемент Управлять версией этого API?.

Выбор схемы управления версиями

В службе «Управление API Azure» укажите способ определения версии API вызывающими сторонами, выбрав схему управления версиями. Эта схема может быть путем, заголовком или строкой запроса. В приведенном ниже примере для выбора схемы управления версиями используется путь.

Введите значения из следующей таблицы. Затем выберите Создать, чтобы создать версию.

Параметр	значение	Описание
Имя	demo-conference-api-v1	Уникальное имя в экземпляре Управления API.

Если выбран параметр Заголовок или Строка запроса, введите дополнительное значение: имя заголовка или параметр строки запроса.

После создания версия отображается под элементом Demo Conference API в списке API. Теперь вы увидите два API: Original и v1.

Если добавить версию для API без управления версиями, будет автоматически создаваться версия Original в соответствии с URL-адресом по умолчанию. Создание версии Original гарантирует, что работа вызывающих сторон не будет нарушена в процессе добавления версии. Если вы сразу создадите API с управлением версиями, то версия Original не будет создаваться.

Изменение версии

После добавления версии ее можно изменить и настроить как API, который отделен от исходного. Изменение одной версии не влияет на другую. Например, добавьте или удалите операции API или измените спецификацию OpenAPI. Дополнительные сведения см. в статье Изменение API.

Добавление версии в продукт

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

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

1. Перейдите к экземпляру Управления API на портале Azure.
2. Выберите Продукты>Без ограничений>API>+ Добавить.
3. Выберите Demo Conference API, версия v1.
4. Щелкните Выбрать.

Использование наборов версий

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

Вы можете напрямую взаимодействовать с набором версий с помощью Azure CLI:

• Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure Cloud Shell.
• Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.
  • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью Azure CLI.
  • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.
  • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

Чтобы просмотреть все наборы версий, выполните команду az apim api versionset list:

az apim api versionset list --resource-group apim-hello-world-resource-group \ --service-name apim-hello-world --output table 

Когда портал Azure создает набор версий, ему присваивается буквенно-цифровое имя, которое отображается в столбце Имя списка. Это имя можно использовать в других командах Azure CLI.

Чтобы просмотреть сведения о наборе версий, выполните команду az apim api versionset show:

az apim api versionset show --resource-group apim-hello-world-resource-group \ --service-name apim-hello-world --version-set-id 00000000000000000000000 

Дополнительные сведения о наборах версий см. в разделе Версии в Управлении API Azure.

Обзор портала разработчика для просмотра версии

Если вы использовали портал разработчика, вы можете просмотреть версии API.

1. Выберите Портал разработчика в верхнем меню.
2. Выберите API, а затем — Demo Conference API.
3. Появится раскрывающийся список с несколькими версиями рядом с именем API.
4. Выберите v1.
5. Обратите внимание на URL-адрес запроса первой операции в списке. В нем видно, что путь URL-адреса API содержит v1.

Следующие шаги

Из этого руководства вы узнали, как:

• добавление новой версии в существующий интерфейс API;
• выбор схемы версии;
• Добавление версии в продукт
• Обзор портала разработчика для просмотра версии

Перейдите к следующему руководству:

Семантическое Версионирование 2.0.0

Учитывая номер версии МАЖОРНАЯ.МИНОРНАЯ.ПАТЧ, следует увеличивать:

1. МАЖОРНУЮ версию, когда сделаны обратно несовместимые изменения API.
2. МИНОРНУЮ версию, когда вы добавляете новую функциональность, не нарушая обратной совместимости.
3. ПАТЧ-версию, когда вы делаете обратно совместимые исправления.

Дополнительные обозначения для предрелизных и билд-метаданных возможны как дополнения к МАЖОРНАЯ.МИНОРНАЯ.ПАТЧ формату.

Вступление

В мире управления процессом разработки есть понятие «ад зависимостей» (dependency hell). Чем больше растёт ваша система и чем больше библиотек вы интегрируете в ваш проект, тем больше вероятность оказаться в этой ситуации.

В системе с множественными зависимостями выпуск новой версии может быстро превратиться в кошмар. Если спецификации зависимости слишком жесткие, вы находитесь в опасности блокирования выпуска новой версии (невозможность обновить пакет без необходимости выпуска новой версии каждой зависимой библиотеки). Если спецификация зависимостей слишком свободна, вас неизбежно настигнет версионное несоответствие (необоснованное предположение совместимости с будущими версиями).

В качестве решения данной проблемы я предлагаю простой набор правил и требований, которые определяют, как назначаются и увеличиваются номера версий. Для того чтобы эта система работала, вам необходимо определить публичный API. Он может быть описан в документации или определяться самим кодом. Главное, чтобы этот API был ясным и точным. Однажды определив публичный API, вы сообщаете об изменениях в нём особым увеличением номера версий. Рассмотрим формат версий X.Y.Z (мажорная, минорная, патч). Баг-фиксы, не влияющие на API, увеличивают патч-версию, обратно совместимые добавления/изменения API увеличивают минорную версию и обратно несовместимые изменения API увеличивают мажорную версию.

Я называю эту систему «Семантическое Версионирование» (Semantic Versioning). По этой схеме номера версий и то, как они изменяются, передают смысл содержания исходного кода и что было модифицировано от одной версии к другой.

Спецификация Семантического Версионирования (SemVer)

Слова «ДОЛЖЕН» (MUST), «НЕ ДОЛЖЕН» (MUST NOT), «ОБЯЗАТЕЛЬНО» (REQUIRED), «СЛЕДУЕТ» (SHOULD), «НЕ СЛЕДУЕТ» (SHOULD NOT), «РЕКОМЕНДОВАННЫЙ» (RECOMMENDED), «МОЖЕТ» (MAY) и «НЕОБЯЗАТЕЛЬНЫЙ» (OPTIONAL) в этом документе должны быть интерпретированы в соответствии с RFC 2119.

1. ПО, использующее Семантическое Версионирование, должно объявить публичный API. Этот API может быть объявлен самим кодом или существовать строго в документации. Как бы ни было это сделано, он должен быть точным и исчерпывающим.
2. Обычный номер версии ДОЛЖЕН иметь формат X.Y.Z, где X, Y и Z — неотрицательные целые числа и НЕ ДОЛЖНЫ начинаться с нуля. X — мажорная версия, Y — минорная версия и Z — патч-версия. Каждый элемент ДОЛЖЕН увеличиваться численно. Например: 1.9.0 ->1.10.0 -> 1.11.0.
3. После релиза новой версии пакета содержание этой версии НЕ ДОЛЖНО быть модифицировано. Любые изменения ДОЛЖНЫ быть выпущены как новая версия.
4. Мажорная версия ноль (0.y.z) предназначена для начальной разработки. Всё может измениться в любой момент. Публичный API не должен рассматриваться как стабильный.
5. Версия 1.0.0 определяет публичный API. После этого релиза номера версий увеличиваются в зависимости от того, как изменяется публичный API.
6. Патч-версия Z (x.y.Z | x > 0) ДОЛЖНА быть увеличена только если содержит обратно совместимые баг-фиксы. Определение баг-фикс означает внутренние изменения, которые исправляют некорректное поведение.
7. Минорная версия (x.Y.z | x > 0) ДОЛЖНА быть увеличена, если в публичном API представлена новая обратно совместимая функциональность. Версия ДОЛЖНА быть увеличена, если какая-либо функциональность публичного API помечена как устаревшая (deprecated). Версия МОЖЕТ быть увеличена в случае реализации новой функциональности или существенного усовершенствования в приватном коде. Версия МОЖЕТ включать в себя изменения, характерные для патчей. Патч-версия ДОЛЖНА быть обнулена, когда увеличивается минорная версия.
8. Мажорная версия X (X.y.z | X > 0) ДОЛЖНА быть увеличена, если в публичном API представлены какие-либо обратно несовместимые изменения. Она МОЖЕТ включать в себя изменения, характерные для уровня минорных версий и патчей. Когда увеличивается мажорная версия, минорная и патч-версия ДОЛЖНЫ быть обнулены.
9. Предрелизная версия МОЖЕТ быть обозначена добавлением дефиса и серией разделённых точкой идентификаторов, следующих сразу за патч-версией. Идентификаторы ДОЛЖНЫ содержать только ASCII буквенно-цифровые символы и дефис [0-9A-Za-z-]. Идентификаторы НЕ ДОЛЖНЫ быть пустыми. Числовые идентификаторы НЕ ДОЛЖНЫ начинаться с нуля. Предрелизные версии имеют более низкий приоритет, чем соответствующая релизная версия. Предрелизная версия указывает на то, что эта версия не стабильна и может не удовлетворять требованиям совместимости, обозначенными соответствующей нормальной версией. Примеры: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.
10. Сборочные метаданные МОГУТ быть обозначены добавлением знака плюс и ряда разделённых точкой идентификаторов, следующих сразу за патчем или предрелизной версией. Идентификаторы ДОЛЖНЫ содержать только ASCII буквенно-цифровые символы и дефис [0-9A-Za-z-]. Идентификаторы НЕ ДОЛЖНЫ быть пустыми. Сборочные метаданные СЛЕДУЕТ игнорировать, когда определяется старшинство версий. Поэтому два пакета с одинаковой версией, но разными сборочными метаданными, рассматриваются как одна и та же версия. Примеры: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.
11. Приоритет определяет, как версии соотносятся друг с другом, когда упорядочиваются. Приоритет версий ДОЛЖЕН рассчитываться путём разделения номеров версий на мажорную, минорную, патч и предрелизные идентификаторы. Именно в такой последовательности (сборочные метаданные не фигурируют в расчёте). Приоритет определяется по первому отличию при сравнении каждого из этих идентификаторов слева направо: Мажорная, минорная и патч-версия всегда сравниваются численно. Пример: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. Когда мажорная, минорная и патч-версия равны, предрелизная версия имеет более низкий приоритет, чем нормальная версия. Пример: 1.0.0-alpha < 1.0.0. Приоритет двух предрелизных версий с одинаковыми мажорной, минорной и патч-версией ДОЛЖНЫ быть определены сравнением каждого разделённого точкой идентификатора слева направо до тех пор, пока различие не будет найдено следующим образом: идентификаторы, состоящие только из цифр, сравниваются численно; буквенные идентификаторы или дефисы сравниваются лексически в ASCII-порядке. Численные идентификаторы всегда имеют низший приоритет, чем символьные. Больший набор предрелизных символов имеет больший приоритет, чем меньший набор, если сравниваемые идентификаторы равны. Пример: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

Зачем использовать семантическое версионирование?

Это не новая или революционная идея. Вероятно, вы уже используете что-то подобное. Проблема в том, что «подобное» — не достаточно хорошо. Без соответствия формальной спецификации, номера версий практически бесполезны для управления зависимостями. Ясно определив и сформулировав идею версионирования, становится легче сообщать о намерениях пользователям вашего ПО. Когда эти намерения ясны, гибки (но не слишком), спецификации зависимостей наконец могут быть созданы.

Простой пример демонстрирует, как Семантическое Версионирование может сделать «ад зависимостей» вещью из прошлого. Представим библиотеку, названную «Firetruck». Она требует Семантически Версионированный пакет под названием «Ladder». Когда Firetruck был создан, Ladder был 3.1.0 версии. Так как Firetruck использует функциональность версии 3.1.0, вы спокойно можете объявить зависимость от Ladder версии 3.1.0, но менее чем 4.0.0. Теперь, когда доступен Ladder 3.1.1 и 3.2.0 версии, вы можете интегрировать его в вашу систему и знать, что он будет совместим с текущей функциональностью.

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

Если это звучит соблазнительно, всё что вам нужно — это начать использовать Семантическое Версионирование, объявить, что вы его используете, и следовать правилам. Добавьте ссылку на этот сайт в вашем README, тогда пользователи будут знать правила и извлекать из этого пользу.

FAQ

Что я должен делать с ревизиями в 0.y.z на начальной стадии разработки?

Самое простое — начать разработку с 0.1.0 и затем увеличивать минорную версию для каждого последующего релиза.

Как я узнаю, когда пора делать релиз 1.0.0?

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

Не препятствует ли это быстрой разработке и коротким итерациям?

Мажорная версия 0 как раз и означает быструю разработку. Если вы изменяете API каждый день, вы должны быть на версии 0.y.z или на отдельной ветке разработки работать над следующей главной версией.

Даже если малейшие обратно несовместимые изменения в публичном API требуют выпуска новой главной версии, не закончится ли это тем, что очень скоро версия станет 42.0.0?

Это вопрос ответственной разработки и предвидения. Несовместимые изменения не должны быть представлены как незначительные в ПО, имеющем много зависимого кода. Стоимость обновления может быть велика. Практика увеличения главных версий релизов с обратно несовместимыми изменениями означает, что вам придётся думать о последствиях ваших изменений и учитывать соотношение цена/качество.

Документирование всего API — слишком много работы!

Это ваша ответственность, как профессионального разработчика, правильно документировать ПО, предназначенное для широкого использования. Управление сложностью ПО очень важная часть поддержки высокой эффективности проекта. Это тяжело сделать, если никто не знает, как использовать ваше ПО или какой метод можно вызывать безопасно. В долгосрочной перспективе Семантическое Версионирование и настойчивость в качественном документировании публичного API поможет всем и всему работать слаженно.

Что мне делать, если я случайно зарелизил обратно несовместимые изменения как минорную версию?

Как только вы поняли, что нарушили спецификации Семантического Версионирования, исправьте проблему и выпустите новую минорную версию, которая исправляет проблему и восстанавливает обратную совместимость. Даже в таких обстоятельствах неприемлемо модифицировать уже выпущенные релизы. Если это необходимо, укажите в документации о нарушении обратной совместимости, версионирования и проинформируйте ваших пользователей, чтобы они знали о нарушении порядка версий.

Что я должен делать, если я обновляю свои собственные зависимости без изменения публичного API?

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

Что если я нечаянно изменил публичный API в несоответствии с изменением номера версии (т.е. код содержит обратно несовместимые изменения в патч-релизе)?

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

Что делать с устаревшей функциональностью?

Объявление функциональности устаревшей — это обычное дело в ходе разработки и часто необходимо для продвижения вперёд. Когда вы объявляете устаревшим часть публичного API, вы должны сделать две вещи: (1) обновить вашу документацию, чтобы дать пользователям узнать об этом изменении; (2) выпустить новый релиз с увеличением минорной версии. Прежде чем вы полностью удалите устаревшую функциональность в релизе с увеличением главной версии, должен быть как минимум один минорный релиз, содержащий объявление функциональности устаревшей, чтобы пользователи могли плавно перейти на новый API.

Есть ли в SemVer лимиты на длину строки версии?

Нет, но руководствуйтесь здравым смыслом. 255 символов в строке версии, пожалуй, перебор. Кроме того, определенные системы могут предъявлять свои собственные ограничения на размер строки.

Об авторе

Авторство спецификаций Семантического Версионирования принадлежит Тому Престон-Вернеру, основателю Gravatars и соучредителю GitHub.

Если вы хотите оставить отзыв, пожалуйста, создайте запрос на GitHub.

Управление версиями REST API

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

2. Что в договоре?​

Прежде всего, нам нужно ответить на один простой вопрос: что такое контракт между API и клиентом?

2.1. URI являются частью контракта?​

Давайте сначала рассмотрим структуру URI REST API — это часть контракта? Должны ли клиенты делать закладки, жестко кодировать и вообще полагаться на URI API?

Если это так, то взаимодействие Клиента со службой REST больше не будет управляться самой службой, а будет зависеть от того, что Рой Филдинг называет внеполосной информацией:

REST API следует вводить без каких-либо предварительных знаний, кроме исходного URI (закладки) и набора стандартизированных типов мультимедиа, подходящих для целевой аудитории… Неудача здесь означает, что внеполосная информация управляет взаимодействием, а не гипертекстом.

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

2.2. Типы носителей являются частью контракта?​

Как насчет информации о Типе носителя, используемой для представления Ресурсов, — это часть договора между Клиентом и Сервисом?

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

Следовательно, именно здесь служба REST должна сосредоточиться больше всего:

API REST должен тратить почти все свои описательные усилия на определение типа (типов) мультимедиа, используемых для представления ресурсов и управления состоянием приложения, или на определение расширенных имен отношений и/или разметки с поддержкой гипертекста для существующих стандартных типов мультимедиа.

Таким образом, определения типа носителя являются частью контракта и должны быть заранее известны клиенту, использующему API. Здесь на помощь приходит стандартизация.

Теперь у нас есть хорошее представление о том, что такое контракт, давайте перейдем к тому, как на самом деле решить проблему управления версиями.

3. Опции высокого уровня​

Давайте теперь обсудим высокоуровневые подходы к управлению версиями REST API:

• Управление версиями URI — версия пространства URI с использованием индикаторов версии.
• Media Type Versioning — версия представления ресурса

Когда мы вводим версию в пространстве URI, представления ресурсов считаются неизменяемыми. Поэтому, когда необходимо внести изменения в API, необходимо создать новое пространство URI.

Например, предположим, что API публикует следующие ресурсы — пользователей и привилегии:

 http://host/v1/users http://host/v1/privileges 

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

 http://host/v2/users http://host/v2/privileges 

Когда мы верифицируем Media Type и расширяем язык, мы проходим Content Negotiation на основе этого заголовка. REST API будет использовать типы носителей MIME пользовательских поставщиков вместо общих типов носителей, таких как application/json . Мы собираемся версионировать эти типы носителей вместо URI.

 ===>  GET /users/3 HTTP/1.1 Accept: application/vnd.myname.v1+json  ==  HTTP/1.1 200 OK Content-Type: application/vnd.myname.v1+json     "user":    "name": "John Smith"   >   > 

Мы можем ознакомиться с этой статьей «Пользовательские типы мультимедиа для Rest API» для получения дополнительной информации и примеров по этому вопросу.

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

Вот почему общие типы носителей не идеальны. Они не предоставляют достаточно семантической информации и вынуждают клиента использовать дополнительные подсказки для обработки фактического представления ресурса.

Исключением является использование какого-либо другого способа уникальной идентификации семантики содержимого, например схемы XML.

4. Преимущества и недостатки​

Теперь, когда у нас есть четкое представление о том, что является частью Контракта между Клиентом и Сервисом, а также общий обзор вариантов версии API, давайте обсудим преимущества и недостатки каждого подхода.

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

Идентификаторы версий в URI также строго негибкие . Невозможно просто развить API отдельного ресурса или небольшого подмножества общего API.

Как мы упоминали ранее, это подход «все или ничего». Если часть API переходит на новую версию, то вместе с ней должен перейти и весь API. Это также делает обновление клиентов с версии 1 до версии 2 серьезной задачей, что приводит к более медленным обновлениям и гораздо более длительным периодам прекращения действия старых версий.

Кэширование HTTP также является серьезной проблемой, когда речь идет об управлении версиями.

С точки зрения прокси-кешей посередине каждый подход имеет свои преимущества и недостатки. Если URI версионный, то кеш должен хранить несколько копий каждого ресурса — по одной для каждой версии API. Это увеличивает нагрузку на кеш и снижает частоту попаданий в кеш, поскольку разные клиенты будут использовать разные версии.

Кроме того, некоторые механизмы аннулирования кеша больше не будут работать. Если тип носителя является версионным, то и клиент, и служба должны поддерживать HTTP-заголовок Vary, чтобы указать, что кэшируется несколько версий.

Однако с точки зрения клиентского кэширования решение, в котором версии типа носителя требуют немного больше работы, чем решение, в котором URI содержат идентификатор версии. Это связано с тем, что проще кэшировать что-то, когда его ключ является URL-адресом, чем типом мультимедиа.

Давайте закончим этот раздел определением некоторых целей (прямо из API Evolution ):

• не допускайте совместимых изменений в именах
• избегать новых основных версий
• делает изменения обратно совместимыми
• подумайте о совместимости вперед

5. Возможные изменения в API​

Далее рассмотрим типы изменений REST API — они представлены здесь:

• изменения формата представления
• изменения ресурсов

5.1. Добавление к представлению ресурса​

Документация по формату типа носителя должна быть разработана с учетом прямой совместимости. В частности, клиент должен игнорировать информацию, которую он не понимает (что JSON делает лучше, чем XML).

Теперь добавление информации в представление ресурса не нарушит работу существующих клиентов, если они правильно реализованы.

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

    "user":    "name": "John Smith",   "amount": "300"   >   > 

5.2. Удаление или изменение существующего представления​

Удаление, переименование или общая реструктуризация информации в дизайне существующих представлений является критическим изменением для клиентов. Это потому, что они уже понимают и полагаются на старый формат.

Вот где вступает в действие согласование контента. Для таких изменений мы можем добавить новый тип носителя MIME поставщика.

Продолжим предыдущий пример. Скажем , мы хотим разбить имя пользователя на имя и фамилию :

 ===>  GET /users/3 HTTP/1.1 Accept: application/vnd.myname.v2+json  ==  HTTP/1.1 200 OK Content-Type: application/vnd.myname.v2+json     "user":    "firstname": "John",   "lastname": "Smith",   "amount": "300"   >   > 

Таким образом, это представляет собой несовместимое изменение для Клиента, которому придется запросить новое Представление и понять новую семантику. Однако пространство URI останется стабильным и не будет затронуто.

5.3. Основные семантические изменения​

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

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

REST API должен соответствовать ограничению HATEOAS. В соответствии с этим большинство URI должны быть ОБНАРУЖЕНЫ клиентами, а не жестко запрограммированы. Изменение такого URI не следует рассматривать как несовместимое изменение. Новый URI может заменить старый, и клиенты смогут повторно обнаружить URI и продолжать функционировать.

Однако стоит отметить, что, хотя использование идентификаторов версий в URI проблематично по всем этим причинам, оно никоим образом не является несовместимым с REST.

6. Заключение​

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

Статья завершается аргументами в пользу второго решения — управления версиями типов мультимедиа при изучении возможных изменений в RESTful API.

Полную реализацию этого туториала можно найти в проекте GitHub .

7. Дополнительная литература​

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

• REST API должны управляться гипертекстом
• Эволюция API
• Связывание с HTTP API
• Стратегии совместимости

Как повышать версию 0.y.z при обратно несовместимых изменениях API?

Использую семантическое версионирование. Как правильно повышать версию 0.y.z при обратно несовместимых изменениях API?

Мажорная версия ноль (0.y.z) предназначена для начальной разработки. Всё может измениться в любой момент. Публичный API не должен рассматриваться как стабильный.

Допустимо ли в таком случае, в ветке 0 просто менять API с изменением минорной версии?

• Вопрос задан более трёх лет назад
• 127 просмотров