Как предотвратить критические изменения API с помощью API Gateway
September 11, 2023
При разработке API иногда происходят изменения, которые могут вызвать проблемы для текущих потребителей API. Эволюция вашего API без влияния на текущих пользователей крайне важна, иначе они могут потерять доверие к вашему предложению. Полностью избежать этих проблем невозможно, но можно минимизировать их влияние или выявить критические изменения до их внедрения. Критические изменения необходимо выявлять на этапе разработки, и если они происходят, API-шлюз должен обрабатывать их, чтобы клиентские приложения оставались незатронутыми. В этой статье мы рассмотрим лучшие практики и стратегии для предотвращения критических изменений в API и способы их обработки с использованием API-шлюза APISIX.
Что такое критические изменения в API?
Программные продукты постоянно развиваются, и их API не являются исключением. Эти API служат основным интерфейсом, через который внешние потребители взаимодействуют с вашей системой, отражая любые изменения в продукте. Существуют различные причины для таких изменений, включая технологические улучшения, изменения в бизнес-направлении, исправление критических ошибок и многое другое. Проще говоря, критическое изменение — это изменение в API, которое может вызвать проблемы у клиентских приложений, использующих его. Некоторые из этих изменений легче обнаружить, чем другие. Вот несколько примеров критических изменений:
- Удаление конечной точки: Если у вас есть конечная точка
GET /users, и вы решите её удалить, любой клиент, пытающийся получить к ней доступ, получит ошибки. - Изменение URL конечной точки: Если вы измените URL конечной точки с
GET /usersнаGET /members, любой клиент, использующий старый URL, столкнётся с проблемами. - Изменение полезной нагрузки запроса: Если конечная точка ожидает определённые данные в запросе, например,
POST /usersожидает{ "name": "John" }, но вы изменяете требование на{ "firstName": "John" }, это нарушит работу клиентов, отправляющих старый формат. - Удаление или переименование полей в ответе: Если клиенты ожидают определённые поля в ответе API, удаление или переименование этих полей приведёт к сбою клиентов. Например, изменение
{ "id": 1, "name": "John" }на{ "id": 1, "fullName": "John Doe" }. - Изменение типов данных: Если поле API ожидается как строка, а вы изменяете его на целое число или другой тип, это может нарушить работу клиентов. Например, изменение
"age": "25"на"age": 25. - Изменение механизмов аутентификации: Если вы переходите с базовой аутентификации на токен-базированную без должного перехода, существующие клиенты столкнутся с ошибками аутентификации.
- Введение обязательных полей: Если у вас есть конечная точка, например,
POST /users, которая принимает необязательные поля, и вы внезапно делаете одно из этих полей обязательным, существующие клиенты, не отправляющие это поле, столкнутся с проблемами. - Изменение форматов ошибок: Если клиенты запрограммированы на понимание определённых форматов ошибок, изменение этих форматов может привести к неправильной обработке ошибок на стороне клиента.
- Изменение HTTP-статус кодов: Изменение статус-кодов для определённых операций, например, возврат
200 OKвместо201 Createdдля создания ресурса, может ввести клиентов в заблуждение. - Прекращение поддержки старых версий API: Если вы прекращаете поддержку старых версий без должного переходного периода, клиенты, полагающиеся на эти версии, перестанут работать.
Каждое изменение в API имеет потенциал нарушить работу клиентского приложения. Если вы используете API-шлюз как входную дверь для всех бэкенд-API, шлюз знает, куда перенаправить запрос на основе набора правил, определённых в конфигурации маршрута, и это правильное место для обработки критических изменений в API. Давайте посмотрим, как мы можем использовать APISIX для выявления некоторых изменений в API.
Валидация схемы запроса и ответа
Определение строгих схем для ваших маршрутов позволяет убедиться, что структуры запроса и ответа соответствуют ожиданиям. Используйте плагин request-validation для валидации входящих запросов и плагин response-rewrite для перезаписи ответа API на основе определённых условий.
Логирование
APISIX поддерживает различные плагины для логирования, такие как http-logger, elasticsearch-logger, file-logger и другие. Настройте логгер для хранения данных запросов и ответов API и регулярно анализируйте логи, чтобы обнаружить изменения в заголовках запросов/ответов, структурах полезной нагрузки или любые другие необычные паттерны.
Мониторинг маршрутов и вышестоящих серверов
Мониторинг маршрутов, проходящих через шлюз. Если ранее доступный маршрут внезапно начинает возвращать ошибки 404, это может быть признаком того, что API претерпел изменения или конечная точка была удалена. Включите функцию API health check для постоянного мониторинга общего состояния вышестоящих узлов. Если один из узлов начинает работать с ошибками, отвечая быстрее или медленнее, чем обычно, это может указывать на изменение в обработке базового бэкенд-сервиса. Интегрируйте APISIX с инструментами мониторинга, такими как Prometheus, используя плагин prometheus. Настройте оповещения на основе метрик, таких как увеличение частоты ошибок 4xx или 5xx, что может указывать на критические изменения в вашем API.
Использование версионирования
Версионирование API — это практика управления изменениями в API и обеспечения того, что эти изменения вносятся без нарушения работы приложений-потребителей API. Существуют различные методы настройки версионирования с APISIX, такие как использование путей URI, параметров запроса, заголовков или выбор типа содержимого. Например, у вас могут быть веб-адреса, такие как /v1/users или /v2/users, чтобы показать версию вашего API. Имея эти версии, вы можете предложить более одного варианта вашего API, позволяя потребителям API решать, когда переходить на последнюю версию в своём темпе. APISIX может легко перенаправлять весь трафик обратно на старую, стабильную версию API, пока вы устраняете проблемы в новой версии, что делает ваши API обратно совместимыми. Используйте APISIX для сохранения старой совместимости при внедрении новых изменений. Если вы обнаружите проблемы в новой версии, плагин traffic-split позволяет быстро откатиться.
Уведомления об устаревании
Перед удалением или изменением функций пометьте их как устаревшие, предоставив потребителям достаточно времени для адаптации. С помощью APISIX мы можем настроить маршрут для информирования о его будущем устаревании и его замене. Для этого APISIX предлагает плагин response-rewrite.
Интеграция с системой контроля версий
Хотя вы можете надеяться, что рецензенты pull request заметят любые критические изменения, полагаться исключительно на этот метод небезопасно и может привести к сбоям. Если у вас есть документация OpenAPI/Swagger для ваших API, её можно контролировать с помощью системы контроля версий и включить в CI-конвейер. APISIX не поддерживает нативную интеграцию с системами контроля версий, такими как Git, для изменений в спецификации API. Однако вы можете настроить процесс вне APISIX. Инструменты, такие как Oasdiff или Bump, могут выявлять изменения в спецификациях API и запускать CI-конвейер (добавьте GitHub Action), который запускает тесты для конечных точек маршрутов в APISIX, чтобы убедиться, что критические изменения не внесены.
Другие способы обнаружения изменений
Postman содержит шаблон для автоматической проверки текущей версии вашего API на наличие критических изменений и описывает, как это работает, в этой статье. Вы можете добавить детектор в CI-конвейер как дополнительный шаг. Каждый раз, когда ваш конвейер выполняется, детектор критических изменений будет анализировать текущую спецификацию API по сравнению с предыдущей и уведомлять вас о любых различиях. В зависимости от вашего стека разработки существуют другие библиотеки для сравнения спецификаций OpenAPI. Эта статья хорошо объясняет, как выявить их на практике, используя проверенные стратегии развёртывания перед внесением новых изменений в производство.
Итог
Обнаружение и предотвращение критических изменений в API важно для поддержания доверия потребителей API и обеспечения успеха вашего сервиса. Интегрируя возможности APISIX, такие как валидация запросов, версионирование, логирование, мониторинг и оповещение, с техниками автоматизированного тестирования контрактов API, вы можете гарантировать, что ваши API развиваются без негативного влияния на ваших клиентов.