Эпизод 18.
Версионирование API. Обратная совместимость в API
Работаете с задачами на Backend, проектируете методы REST API или описываете интеграции? Этот эпизод актуален для вас.
В нём мы разберём, что такое версионирование API, когда и почему нужно вводить новые версии, какие подходы к версионированию лучше использовать и как это влияет на его пользователей.
Эпизод будет полезен системным аналитикам, которые работают с интеграциями, разрабатывают контракты методов API и сталкиваются с задачами изменения существующих API. Особенно это актуально в задачах на проектирование REST API методов.
00:19 - Знакомство со спикером и актуальность темы версионирования API.
03:05 - Что включает понятие версионирования API. Обратная совместимость в API.
7:55 - Сколько версий API могут работать одновременно.
8:59 - Как долго занимает переход с одной версии API на другую. Как правильно выводить из эксплуатации устаревшие версии API.
11:51 - Разработка контрактов REST API системными аналитиками: OpenAPI, Swagger, GitHub, Postman, Confluence.
14:51 - Проблемы тестирования и инфраструктуры при наличии нескольких активных версий API. Информирование клиентов об изменениях в API.
20:20 - Реализация версий в API и что об этом надо знать системному аналитику. Где указывать версию и в каком формате.
30:20 - Переход клиентских приложений на новые версии API. Проблемы и решения.
41:15 - Как отслеживать количество пользователей, использующих устаревшие версии API.
44:46 - Итоги эпизода и практические рекомендации.
Статья к эпизоду
Термины и определения
Версионирование API — это процесс управления изменениями в программном интерфейсе приложений (API), позволяющий вносить улучшения или корректировки без нарушения работы существующих интеграций к этому интерфейсу. Новая версия API создаётся, когда изменения могут повлиять на обратную совместимость, то есть на способность клиентских приложений продолжать работать без доработок.
Обратная совместимость в API — это внесение изменений в структуру данных, передаваемых запросами или возвращаемых ответами, без необходимости доработки клиентских приложений.
Пример:
В JSON-объект REST API добавлено новое поле.
Клиентские приложения, которые не используют это поле, продолжают корректно работать, так как игнорируют новое поле.
Обратная совместимость в БД — изменения в схеме базы данных, которые не требуют доработки функциональности и любых приложений системы.
Пример:
В таблицу базы данных добавлено новое поле.
Приложения, которые не используют это поле, продолжают работать без изменений, так как новое поле игнорируется.
Подходы к версионированию API
При версионировании REST API версии могут быть указаны различными способами. Каждый подход имеет свои преимущества и недостатки.
Версия в параметрах (Query-параметрах)
Версия указывается в строке запроса как параметр.
Пример:GET https://getanalyst.ru/api/resource?version=1.0Версия в URI
Версия включается в адрес запроса.
Пример:GET https://getanalyst.ru/v1/resourceВерсия в заголовках (Headers)
Версия указывается в HTTP-заголовке запроса.Версия в теле запроса (Body)
Версия передаётся как часть содержимого тела запроса.
Пример:
{
"version": "1.0",
"data":
{ "key": "value" }
}Подходы к версионированию API
Новая версия API требуется, когда изменения делают старую версию несовместимой с новыми требованиями. Например:
- Изменение структуры данных в запросах или ответах API, которое невозможно обработать существующими клиентами.
- Добавление новой функциональности, который влияет на базовую логику работы API.
- Устаревшие версии создают риски или ограничивают развитие системы.
Рекомендации по работе с версиями API
- Планируйте изменения так, чтобы минимизировать влияние на существующие интеграции.
- Поддерживайте обратную совместимость как можно дольше, добавляя новые поля или параметры без удаления существующих.
- Информируйте клиентов об изменениях заранее, указывая сроки перехода на новые версии.
- Создавайте документацию для каждой версии API, чтобы упростить интеграцию для разработчиков клиентских приложений.
- Используйте мониторинг, чтобы отслеживать использование устаревших версий и планировать их вывод из эксплуатации.
Контакты
+7 (499) 686-15-46
Лицензия №Л035-01255-50/01366872 от 28.08.2024
*Instagram — запрещенная на территории РФ организация
Практический опыт здесь, 2021-2024
Мы используем файлы cookie, для персонализации сервисов и повышения удобства пользования сайтом. Если вы не согласны на их использование, поменяйте настройки браузера.