API-styrning

Slutförd

API-styrning definieras som praxis att definiera och tillämpa standarder, principer och processer i stor skala för alla organisations-API:er. Med API Center kan du göra det med:

• Spåra API-metadata, inklusive API-titel, beskrivning, versioner, definitioner och distributioner. Dessutom kan du ange egna anpassade API-metadata – till exempel information om livewebbplatser, lagringsplats för källkontroll osv. – för att spåra metadata som är viktiga för din organisation (visas i en tidigare modul).
• Se till att alla API:er är utformade för att följa organisationens API-designfilosofier
• Säkerställa identifiering i tid av API-versioner med icke-bakåtkompatibla ändringar för sömlös distribution och kommunikation till API-konsumenter

I den här lektionen får vi se hur API Center gör att du kan konfigurera API-styrning i stor skala.

Förutsättningar

Om du vill styra dina API:er med API Center måste du:

1. Installera Azure CLI.
2. Installera Azure Developer CLI (azd).
3. Registrera Event Grid-resursprovidern i din prenumeration. Om du behöver registrera Event Grid-resursprovidern kan du läsa Prenumerera på händelser som publicerats av en partner med Azure Event Grid.

API-designefterlevnad

API-plattformsteam ansvarar ofta för att definiera en uppsättning riktlinjer för API-producenter. Med API Center kan du kodifiera API-riktlinjer genom att definiera regler med lintningsmotorn Spectral med öppen källkod. Som standard levereras API Center med en angiven Spectral-regel, men du kan alltid skapa en egen eller utnyttja den stora communityn med regler för öppen källkod. Varje gång en API-definition laddas upp kör API Center Spectral-lintern med hjälp av den angivna regeluppsättningen för att kontrollera API-definitionen för efterlevnad av regeln. En rapport om API-efterlevnad genereras som du kan visa i API-centret.

Så här konfigurerar du API-designefterlevnad för din organisation:

1. Klona GitHub-lagringsplatsen och öppna den i Visual Studio Code.

2. Ändra katalogen till APICenter-Analyzer mappen på lagringsplatsen.

3. resources/rulesets I mappen hittar du en oas.yaml fil. Den här filen visar den aktuella API-formatguiden och kan ändras baserat på organisationens behov och krav.

4. Autentisera med Azure Developer CLI och Azure CLI med följande kommandon:

   azd auth login
   
   az login
   

5. Kör följande kommando för att distribuera linting-infrastrukturen till din Azure-prenumeration.

   azd up
   

6. Följ anvisningarna för att ange nödvändig distributionsinformation och inställningar, till exempel miljönamnet och API Center-namnet. Mer information finns i Köra exemplet med hjälp av Azure Developer CLI (azd).

   Kommentar

   Distributionen kan ta några minuter.

7. När distributionen är klar går du till API-centret i Azure Portal. I den vänstra menyn väljer du Händelser>Händelseprenumerationer för att visa händelseprenumerationen som skapades.

Nu kan du ladda upp en API-definitionsfil till api-centret för att utlösa händelseprenumerationen och köra lintingmotorn.

Api-styrning för skift till vänster

De mest framgångsrika styrningsinitiativen är alltid utvecklare själva. Genom att tillämpa traditionella skift-vänster-principer kan API-plattformsteam se till att API-producenter vet exakt vilka krav de måste uppfylla för att publicera API:er tidigt i utvecklingscykeln. Detta sparar värdefull utvecklingstid genom att minska behovet av att åtgärda icke-kompatibla API:er senare i utvecklingscykeln.

API Center-tillägget för Visual Studio Code ger API-producenter en upplevelse för att köra API-designefterlevnadskontroller direkt i Visual Studio Code när API:et skapas. API-producenter kan dessutom använda funktionen för identifiering av icke-bakåtkompatibla ändringar för att identifiera när en ändring kan leda till en chatt för API-konsumenter.

API-designefterlevnad i Visual Studio Code

API Center-tillägget är integrerat med Spectral, en JSON/YAML-linter som stöder OpenAPI och anpassad regeluppsättning. Tillägget gör det möjligt för utvecklare att strikt följa den tillhandahållna eller rekommenderade API-stilguiden, vilket säkerställer konsekvens för alla API:er som utvecklas i olika team.

Kommentar

Du måste installera API Center - och Spectral-tilläggen för att kunna använda den här funktionen.

Aktivera genom att

1. Använd kortkommandot Ctrl+Skift+P för att öppna kommandopaletten. Skriv Azure API Center: Ange aktiv API Style Guide och tryck på Retur.
2. Välj någon av standardreglerna som tillhandahålls, eller, om din organisation redan har en formatguide tillgänglig, använd Välj lokal fil eller Ange fjärr-URL för att specificera den aktiva regeluppsättningen i Visual Studio Code. Tryck på Retur.

När en aktiv API-formatguide har angetts utlöser öppnandet av en OpenAPI- eller AsyncAPI-baserad specifikationsfil en lokal lintningsåtgärd i Visual Studio Code. Resultaten visas både infogade i redigeraren och i fönstret Problem (Visa > problem eller Ctrl+Skift+M).

Identifiera icke-bakåtkompatibla ändringar i Visual Studio Code

Leverans av API-versioner som bryter arbetsflöden för konsumentproduktion resulterar i en otillförlitlig och förlust av förtroende. MED API Center-tillägget kan utvecklare enkelt jämföra två API-versioner och identifiera eventuella icke-bakåtkompatibla ändringar som introducerades i API:et före distributionen.

Kommentar

Du måste installera Optic för att kunna använda den här funktionen. Installera med hjälp av följande kommando.

npm install -g @useoptic/optic*

Sedan kan du

1. Använd kortkommandot Ctrl+Skift+P för att öppna kommandopaletten. Skriv Azure API Center: Upptäck brytande ändring och tryck på Retur.
2. Välj det första API-specifikationsdokumentet som ska jämföras. Giltiga alternativ inkluderar API-specifikationer som finns i DITT API Center, en lokal fil eller den aktiva redigeraren i Visual Studio Code.
3. Välj det andra API-specifikationsdokumentet som ska jämföras. Giltiga alternativ inkluderar API-specifikationer som finns i DITT API Center, en lokal fil eller den aktiva redigeraren i Visual Studio Code.

Visual Studio Code öppnar en diff-vy mellan de två API-specifikationerna. Eventuella ändringar som bryter kompatibilitet visas både direkt i redigeraren och i problemfönstret (Visa > problem eller Ctrl+Skift+M).