Одна из наиболее распространенных проблем, с которыми я сталкивался при разработке API, – это то, как версировать API. Хотя не все API идентичны, я нахожу, что некоторые шаблоны и методы применимы к большинству команд в управлении версиями API . Я собрал все это и дам некоторые рекомендации по стратегиям управления версиями, которые помогут большинству поставщиков API, независимо от того, развертывают ли они API внутри или снаружи.
Действительно ли версия API так важна?
API-это связующее звено между вами и пользователями API. Как правило, узы между вами не будут легко разорваны. Связи включают шаблоны URI, структуры полезной нагрузки, имена полей и параметров, ожидаемое поведение и другое содержимое. Самое большое преимущество такого подхода очевидно: понимание пользователей API не изменится, а приложения смогут обеспечить непрерывность и эффективность.
Тем не менее, нереально оставаться неизменным вечно. Иногда из-за изменений в бизнесе вам может потребоваться внести существенные изменения в API. Когда это произойдет, лучший способ-убедиться, что вы не сделаете ничего, что заставит пользователей API исправить свой код.
Разрушение и непрерывные изменения
Неразрушающие изменения, как правило, похожи на “добавки”, обычно добавляющие новые поля или вложенные ресурсы в инструкции ресурсов или добавляющие новые конечные точки, такие как PUT или PATCH. Пользователи API должны создавать клиентский код, который с самого начала адаптируется к этим неразрушающим изменениям.
Прорывные изменения включают в себя:
1. Поля имен или пути к ресурсам, обычно для унификации спецификаций именования после публикации API.
2. Изменение структуры полезной нагрузки, как правило, адаптируется к следующему:
- A. Переименование или удаление полей
- B. Измените поле с одного значения на отношение “один ко многим” (например, переместитесь с адреса электронной почты учетной записи в список адресов электронной почты этой учетной записи).
- C. Изменил URL-адрес API, что привело к несогласованным возвратам.
Короче говоря, как только вы опубликуете API для широкой публики, вы должны сохранить его доступным и не влиять на пользователей. Если вы сталкиваетесь с несколькими проектами, требуется контроль версий API, чтобы предотвратить уничтожение существующих пользователей API.
Определите политику версий API
Любой развивающийся API требует стратегий управления версиями API. Ваша версия API может быть адаптирована для переключения различных версий в соответствии с ожиданиями пользователей API. Обычно я рекомендую следующие стратегии управления версиями API как часть общей системы управления API.
1. Если ваш API находится в ранней бета-версии, чтобы получить обратную связь от потребителей, установите правильные ожидания того, что ваш API может измениться. На этом этапе вы сохраните эту версию на некоторое время, потому что дизайн вашего API может измениться. Как потребители, API нестабильны, поэтому они должны предвидеть возможные изменения.
2. После выпуска ваш API должен рассматриваться как контракт и не может быть заменен без новой версии.
3. Непрерывные изменения могут вызвать проблемы с второстепенными версиями, и клиент автоматически перейдет на последнюю версию без каких-либо негативных побочных эффектов.
4. Прорывные изменения означают, что клиенты должны перейти на эту новую версию, поскольку она содержит одно или несколько существенных изменений. Вы должны установить соответствующее расписание и регулярно общаться с пользователями API, чтобы гарантировать, что они смогут легко перейти на новые версии. Но в некоторых случаях это может оказаться невозможным сразу, поэтому вашей команде будет предложено временно поддержать предыдущие версии API.
Когда необходимо реализовать контроль версий API
Как только вы решите, что вам нужна новая версия API, вам нужно знать, как с ней обращаться. Существует три распространенных способа реализации контроля версий API.
1. Контроль версий Ресурсов
Эта версия является частью заголовка Accept в HTTP-запросах, например, Accept: application/vnd. github. V3 + JSON отправляется для ПОЛУЧЕНИЯ/клиентов. При этом учитывается множество предпочтительных форм управления версиями, поскольку ресурсы должны быть версифицированы с сохранением одного и того же URI. Если это не указано в заголовке “Принять”, некоторые API выбирают последнюю версию в качестве версии по умолчанию.
2. Контроль версий URI
Эта версия является частью URI в виде префикса или суффикса, например,/V1/customers или/customers/v1. Хотя НАШ контроль версий не так точен, как контроль версий на основе содержимого, он часто является наиболее распространенным, поскольку применяется к инструментам, которые не поддерживают пользовательские заголовки. Недостатком является то, что URI ресурса изменяется с каждой новой версией, что, по мнению некоторых людей, противоречит намерению иметь неизменный URI.
3. Контроль версий имени хоста
Эта версия является частью имени хоста, а не URL-адреса, например, https://v2. api .myapp.com/cust…. Этот метод используется, когда технические ограничения не позволяют UTI или заголовкам Accept достичь правильной серверной версии API.
Примечания: Какой бы вариант вы ни выбрали, версия API должна содержать только основной номер. Не требуется никаких небольших чисел (т. е./V1/клиенты, а не/v1.1/клиенты).
Инструменты для контроля версий
Процесс управления версиями API может быть принципиально реализован с использованием инструментов и технологий. Использование превосходных редакторов API на рынке позволит командам разработчиков технологий создавать и переключать больше версий API за более короткое время, тем самым постоянно совершенствуя проектные решения.
Контроль версий с помощью инструментов является важной частью большинства процессов разработки. Существуют также инструменты управления версиями в области проектирования API. На самом деле, во всем мире существует несколько превосходных инструментов проектирования веб-API в области обслуживания API.
Теперь, такие как EOLINKER, RAML, Swagger, все они предоставляют отличные инструменты редактирования для поддержки своих языков. Компоновщик E O использует сравнение версий и типы ключевых аннотаций, которые можно переключать и четко сравнивать. RAML и Swagger используют переключение версий, что может быть немного менее удобным. И только первый поддерживает китайский, в то время как последние два поддерживают только английский. Эти редакторы API могут легко управлять версиями API, что облегчает переключение запущенных версий за более короткое время.
Прилагается официальный сайт EOLINKER: https://www.eolinker.com.
Прилагается официальный сайт Swagger: https://swagger.io./
Прилагается официальный адрес РАМИ: https://raml.org/
Последние мысли
Имейте в виду, что API-интерфейсы являются центром ссылок на ваших потребителей. Для разрыва старого соединения требуется новая версия. Конечная цель контроля версий-выбрать стратегию, составить план и сообщить о нем пользователям API.
Ссылка: Джеймс Хиггинботам, Когда и как Вы обновляете Свой API?
Первоначальный адрес: https://dzone.com/articles/wh…