Поделиться через

Использование DevOps и CI/CD для публикации API

ПРИМЕНЯЕТСЯ КО ВСЕМ уровням управления API

Благодаря стратегическому значению API в организации внедрение методов непрерывной интеграции DevOps и непрерывного развертывания (CD) стало важным аспектом разработки API. В этой статье рассматриваются решения, которые необходимо принять для внедрения принципов DevOps в управление API.

API DevOps состоит из трех частей:

Схема, демонстрирующая поток API DevOps.

Ниже рассматривается каждая часть конвейера API DevOps.

Определение API

Разработчик API записывает определение API, предоставляя спецификацию, параметры (такие как ведение журнала, диагностика и параметры серверной части), а также политики, применяемые к API. Определение API предоставляет сведения, необходимые для подготовки API в службе управления API Azure. Спецификация может быть основана на спецификации API на основе стандартов (например , WSDL, OpenAPI или GraphQL) или может быть определена с помощью API Azure Resource Manager (ARM), например шаблона ARM, описывающего API и операции. Определение API изменится со временем и должно рассматриваться как "исходный код". Убедитесь, что определение API хранится в системе управления исходным кодом и имеет соответствующую проверку перед внедрением.

Существует несколько средств для создания определения API:

  • Набор средств Azure APIOps предоставляет рабочий процесс, созданный на основе системы управления исходным кодом Git (например, GitHub или Azure Repos). Он использует средство извлечения для создания определения API, которое затем применяется к целевой службе управления API издателем. APIOps поддерживает API REST и GraphQL в настоящее время.
  • Средство dotnet-apim преобразует четко сформированное определение YAML в шаблон ARM для последующего развертывания. Средство ориентировано на REST API.
  • Terraform — это альтернатива Azure Resource Manager для настройки ресурсов в Azure. Вы можете создать конфигурацию Terraform (вместе с политиками) для реализации API таким же образом, как и шаблон ARM.

Вы также можете использовать средства на основе интегрированной среды разработки для редакторов, таких как Visual Studio Code , для создания артефактов, необходимых для определения API. Например, существует более 90 плагинов для редактирования файлов спецификаций OpenAPI в Visual Studio Code Marketplace. Вы также можете использовать генераторы кода для создания артефактов. Язык TypeSpec позволяет определить API и фигуры облачной службы и очень расширяемый с примитивами, которые могут описывать фигуры API, распространенные среди REST, OpenAPI, gRPC и других протоколов.

Утверждение API

После создания определения API разработчик отправляет определение API для проверки и утверждения. Если используется система управления исходным кодом на основе Git (например, GitHub или Azure Repos), разработчик может отправить pull request. Запрос pull request информирует других пользователей об предложенных изменениях в определении API. После подтверждения ворот утверждения утверждающий объединяет pull-запрос в основной репозиторий, что означает, что определение API можно развернуть в среде эксплуатации. Процесс pull request позволяет разработчику устранять любые проблемы, обнаруженные в ходе утверждения.

GitHub и Azure Repos позволяют настроить потоки утверждения, которые выполняются при создании пулл-реквеста. Конвейеры утверждения можно настроить для запуска таких средств, как:

  • API линтеры, такие как Spectral, используются для проверки, что определение соответствует стандартам API, необходимым для организации.
  • Обнаружение критических изменений с помощью таких средств, как openapi-diff.
  • Средства аудита и оценки безопасности. OWASP поддерживает список средств для проверки безопасности.
  • Автоматизированные платформы тестирования API.

Note

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

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

Публикация API

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

  • При использовании набора средств Azure APIOps этот набор включает публикатор, который записывает определение API в целевую службу.
  • При использовании dotnet-apim определение API представлено как шаблон ARM. Задачи доступны для Azure Pipelines и GitHub Actions для развертывания шаблона ARM.
  • При использовании Terraform средства CLI развертывают определение API в службе. Доступны задачи для Azure Pipelines и GitHub Actions.

Можно ли использовать другие системы управления исходным кодом и CI/CD?

Yes. Описанный процесс работает с любой системой управления исходным кодом (хотя APIOps требует, чтобы система управления исходным кодом была основана на Git ). Аналогичным образом можно использовать любую платформу CI/CD, если ее можно активировать с помощью средств командной строки, которые взаимодействуют с Azure.

Лучшие практики

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

  • Azure Repos хранит определения API в репозитории Git .
  • Azure Pipelines выполняет автоматизированные процессы утверждения API и публикации API.
  • Azure APIOps Toolkit предоставляет средства и рабочие процессы для публикации API.

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

  • Настройте GitHub или Azure Repos для системы управления исходным кодом. Этот выбор также определяет выбор исполнителя конвейера. GitHub может использовать Azure Pipelines или GitHub Actions, в то время как Azure Repos должен использовать Azure Pipelines.
  • Настройте службу управления API Azure для каждого разработчика API, чтобы они могли разрабатывать определения API вместе со службой API. При создании службы используйте номер SKU потребления или разработчика.
  • Используйте фрагменты политики для уменьшения новой политики, которую разработчики должны писать для каждого API.
  • Используйте именованные значения и бэкенды, чтобы гарантировать, что политики являются универсальными и могут применяться к любому экземпляру управления API.
  • Используйте набор средств Azure APIOps для извлечения определения рабочего API из службы разработчиков.
  • Настройте процесс утверждения API, который запускается при каждом pull request. Процесс утверждения API должен включать обнаружение изменений, нарушающих совместимость, линтинг и автоматическое тестирование API.
  • Используйте издателя Azure APIOps Toolkit для публикации API в рабочей службе управления API.

Ознакомьтесь с разделом Автоматизированные развертывания API с APIOps в Центре архитектуры Azure, чтобы получить дополнительную информацию о настройке и запуске конвейера развертывания CI/CD с помощью APIOps.

References

  • Last updated on