Publikowanie interfejsów API za pomocą metodyki DevOps i ciągłej integracji/ciągłego wdrażania

  • Artykuł

DOTYCZY: Wszystkie warstwy usługi API Management

Dzięki strategicznej wartości interfejsów API w przedsiębiorstwie wdrażanie technik ciągłej integracji i wdrażania metodyki DevOps (CD) stało się ważnym aspektem opracowywania interfejsów API. W tym artykule omówiono decyzje, które należy podjąć, aby przyjąć zasady metodyki DevOps dotyczące zarządzania interfejsami API.

Metodyka DevOps interfejsu API składa się z trzech części:

Diagram ilustrujący przepływ metodyki DevOps interfejsu API.

Każda część potoku DevOps interfejsu API została omówiona poniżej.

Definicja interfejsu API

Deweloper interfejsu API pisze definicję interfejsu API, podając specyfikację, ustawienia (takie jak rejestrowanie, diagnostyka i ustawienia zaplecza) oraz zasady, które mają być stosowane do interfejsu API. Definicja interfejsu API zawiera informacje wymagane do aprowizacji interfejsu API w usłudze Azure API Management. Specyfikacja może być oparta na specyfikacji interfejsu API opartej na standardach (na przykład WSDL, OpenAPI lub GraphQL) lub może być zdefiniowana przy użyciu interfejsów API usługi Azure Resource Manager (ARM) (na przykład szablonu usługi ARM opisującego interfejs API i operacje). Definicja interfejsu API zmieni się w czasie i powinna zostać uznana za "kod źródłowy". Upewnij się, że definicja interfejsu API jest przechowywana w ramach kontroli kodu źródłowego i ma odpowiedni przegląd przed wdrożeniem.

Istnieje kilka narzędzi ułatwiających tworzenie definicji interfejsu API:

  • Zestaw narzędzi Azure APIOps Toolkit udostępnia przepływ pracy oparty na systemie kontroli kodu źródłowego git (takim jak GitHub lub Azure Repos). Używa wyodrębniającego do tworzenia definicji interfejsu API, która jest następnie stosowana do docelowej usługi API Management przez wydawcę. Usługa APIOps obsługuje obecnie interfejsy API REST i GraphQL.
  • Narzędzie dotnet-apim konwertuje dobrze sformułowaną definicję YAML na szablon usługi ARM na potrzeby późniejszego wdrożenia. Narzędzie koncentruje się na interfejsach API REST.
  • Narzędzie Terraform to alternatywa dla usługi Azure Resource Manager do konfigurowania zasobów na platformie Azure. Możesz utworzyć konfigurację programu Terraform (wraz z zasadami), aby zaimplementować interfejs API w taki sam sposób, w jaki został utworzony szablon usługi ARM.

Możesz również użyć narzędzi opartych na środowisku IDE dla edytorów, takich jak Visual Studio Code , aby utworzyć artefakty niezbędne do zdefiniowania interfejsu API. Na przykład w witrynie Visual Studio Code Marketplace istnieje ponad 30 wtyczek do edytowania plików specyfikacji interfejsu OpenAPI. Możesz również użyć generatorów kodu, aby utworzyć artefakty. Język CADL umożliwia łatwe tworzenie bloków konstrukcyjnych wysokiego poziomu, a następnie kompilowanie ich w standardowym formacie definicji interfejsu API, takim jak OpenAPI.

Zatwierdzanie interfejsu API

Po utworzeniu definicji interfejsu API deweloper prześle definicję interfejsu API do przeglądu i zatwierdzenia. Jeśli korzystasz z systemu kontroli kodu źródłowego opartego na usłudze Git (na przykład GitHub lub Azure Repos), przesyłanie można wykonać za pośrednictwem żądania ściągnięcia. Żądanie ściągnięcia informuje inne osoby o zmianach, które zostały zaproponowane w definicji interfejsu API. Po potwierdzeniu bram zatwierdzania osoba zatwierdzająca scali żądanie ściągnięcia do repozytorium głównego, aby potwierdzić, że definicję interfejsu API można wdrożyć w środowisku produkcyjnym. Proces żądania ściągnięcia umożliwia deweloperowi korygowanie wszelkich problemów znalezionych podczas procesu zatwierdzania.

Zarówno usługi GitHub, jak i Azure Repos umożliwiają skonfigurowanie potoków zatwierdzania, które są uruchamiane po przesłaniu żądania ściągnięcia. Potoki zatwierdzania można skonfigurować do uruchamiania narzędzi, takich jak:

  • Linters specyfikacji interfejsu API, takie jak Spectral , aby upewnić się, że definicja spełnia standardy interfejsu API wymagane przez organizację.
  • Wykrywanie zmian powodujących niezgodność przy użyciu narzędzi, takich jak openapi-diff.
  • Narzędzia do inspekcji i oceny zabezpieczeń. Program OWASP utrzymuje listę narzędzi do skanowania zabezpieczeń.
  • Zautomatyzowane struktury testów interfejsu API, takie jak Newman, moduł uruchamiający testy dla kolekcji Postman.

Uwaga

Interfejsy API platformy Azure muszą być zgodne z rygorystycznym zestawem wytycznych , których można użyć jako punktu początkowego dla własnych wytycznych dotyczących interfejsu API. Istnieje konfiguracja spectralna wymuszania wytycznych.

Po uruchomieniu zautomatyzowanych narzędzi definicja interfejsu API jest przeglądana przez ludzkie oko. Narzędzia nie przechwytują wszystkich problemów. Recenzent zapewnia, że definicja interfejsu API spełnia kryteria organizacyjne interfejsów API, w tym przestrzeganie wytycznych dotyczących zabezpieczeń, prywatności i spójności.

Publikacja interfejsu API

Definicja interfejsu API zostanie opublikowana w usłudze API Management za pośrednictwem potoku wydania. Narzędzia używane do publikowania definicji interfejsu API zależą od narzędzia używanego do tworzenia definicji interfejsu API:

Czy mogę używać innych systemów kontroli kodu źródłowego i ciągłej integracji/ciągłego wdrażania?

Tak. Opisany proces działa z dowolnym systemem kontroli kodu źródłowego (chociaż metodyka APIOps wymaga, aby system kontroli kodu źródłowego był oparty na narzędziu git ). Podobnie możesz użyć dowolnej platformy ciągłej integracji/ciągłego wdrażania, o ile może zostać wyzwolona przez zaewidencjonowane i uruchamiane narzędzia wiersza polecenia komunikujące się z platformą Azure.

Najlepsze rozwiązania

Nie ma standardu branżowego do konfigurowania potoku DevOps na potrzeby publikowania interfejsów API, a żadne z wymienionych narzędzi nie będzie działać we wszystkich sytuacjach. Widzimy jednak, że większość sytuacji jest objęta kombinacją następujących narzędzi i usług:

Widzieliśmy największy sukces we wdrożeniach klientów i zalecamy następujące rozwiązania:

  • Skonfiguruj repozytoria GitHub lub Azure Repos dla systemu kontroli kodu źródłowego. Ten wybór określi również wybór modułu uruchamiającego potok. Usługa GitHub może używać usługi Azure Pipelines lub GitHub Actions, natomiast usługa Azure Repos musi używać usługi Azure Pipelines.
  • Skonfiguruj usługę Azure API Management dla każdego dewelopera interfejsu API, aby mogli opracowywać definicje interfejsu API wraz z usługą interfejsu API. Użyj jednostki SKU użycia lub jednostki SKU dewelopera podczas tworzenia usługi.
  • Użyj fragmentów zasad, aby zmniejszyć nowe zasady, które deweloperzy muszą napisać dla każdego interfejsu API.
  • Użyj nazwanych wartości i zapleczy , aby upewnić się, że zasady są ogólne i mogą być stosowane do dowolnego wystąpienia usługi API Management.
  • Użyj zestawu narzędzi Azure APIOps Toolkit , aby wyodrębnić działającą definicję interfejsu API z usługi dewelopera.
  • Skonfiguruj proces zatwierdzania interfejsu API uruchamiany w każdym żądaniu ściągnięcia. Proces zatwierdzania interfejsu API powinien obejmować wykrywanie zmian powodujących niezgodność, linting i zautomatyzowane testowanie interfejsu API.
  • Użyj wydawcy zestawu narzędzi Azure APIOps Toolkit, aby opublikować interfejs API w produkcyjnej usłudze API Management.

Aby uzyskać więcej informacji na temat konfigurowania i uruchamiania potoku wdrażania ciągłej integracji/ciągłego wdrażania za pomocą metodyki APIOps, zapoznaj się z tematem Zautomatyzowane wdrożenia interfejsu APIOps przy użyciu metodyki APIOps.

Informacje