Governance delle API

Completato

La governance delle API è definita come la pratica per definire e applicare standard, criteri e processi su larga scala in tutte le API aziendali. Il Centro API consente di eseguire questa operazione con:

• Rilevamento dei metadati dell'API, inclusi titolo DELL'API, descrizione, versioni, definizioni e distribuzioni. Inoltre, è possibile specificare i metadati personalizzati dell'API, ad esempio informazioni sul sito live, repository di controllo del codice sorgente e così via, per tenere traccia dei metadati importanti per l'organizzazione (mostrati in un modulo precedente).
• Garantire che tutte le API siano progettate per essere conformi alle filosofie di progettazione dell'API dell'organizzazione
• Garantire un rilevamento tempestivo delle versioni dell'API con modifiche di rilievo per l'implementazione e la comunicazione senza problemi con i consumer di API

In questa unità verrà illustrato come il Centro API consente di configurare la governance delle API su larga scala.

Prerequisiti

Per gestire le API con il Centro API, è necessario:

1. Installare l'interfaccia della riga di comando di Azure.
2. Installare l'interfaccia della riga di comando per sviluppatori di Azure (azd).
3. Registrare il provider di risorse di Griglia di eventi nella sottoscrizione. Se è necessario registrare il provider di risorse di Griglia di eventi, vedere Sottoscrivere eventi pubblicati da un partner con Griglia di eventi di Azure.

Conformità alla progettazione dell'API

I team della piattaforma API sono spesso responsabili della definizione di un set di linee guida per i produttori di API. Il Centro API consente di codificare le linee guida dell'API definendo regole con il motore di linting open source Spectral. Per impostazione predefinita, il Centro API include una regola Spectral fornita, ma è sempre possibile creare un set di regole open source personalizzato o sfruttare la grande community di set di regole open source. Ogni volta che viene caricata una definizione API, il Centro API esegue il linter Spectral usando il set di regole fornito per verificare la conformità della definizione API alla regola. Viene generato un report sulla conformità api che è possibile visualizzare nel centro API.

Per configurare la conformità alla progettazione api per l'organizzazione:

1. Clonare il repository GitHub e aprirlo in Visual Studio Code.

2. Passare alla cartella APICenter-Analyzer nel repository.

3. Nella cartella resources/rulesets è possibile trovare un file oas.yaml. Questo file riflette la guida di stile dell'API corrente e può essere modificata in base alle esigenze e ai requisiti dell'organizzazione.

4. Eseguire l'autenticazione con l'interfaccia della riga di comando per sviluppatori di Azure e l'interfaccia della riga di comando di Azure usando i comandi seguenti:

   azd auth login
   
   az login
   

5. Eseguire il comando seguente per distribuire l'infrastruttura di linting nella sottoscrizione di Azure.

   azd up
   

6. Seguire le istruzioni per specificare le informazioni e le impostazioni di distribuzione necessarie, ad esempio il nome dell'ambiente e il nome del centro API. Per informazioni dettagliate, vedere Esecuzione dell'esempio usando l'interfaccia della riga di comando per sviluppatori di Azure (azd).

   Nota

   La distribuzione può richiedere alcuni minuti.

7. Al termine della distribuzione, passare al centro API nel portale di Azure. Nel menu a sinistra selezionare Eventi>sottoscrizioni di eventi per visualizzare la sottoscrizione di eventi creata.

È ora possibile caricare un file di definizione API nel centro API per attivare la sottoscrizione di eventi ed eseguire il motore di linting.

Governance dell'API maiuscole/sinistra

Le iniziative di governance più efficaci includono sempre gli sviluppatori stessi. Applicando i tradizionali principi di spostamento a sinistra, i team della piattaforma API possono garantire che i produttori di API sappiano esattamente quali requisiti devono soddisfare per pubblicare le API all'inizio del ciclo di sviluppo. Ciò consente di risparmiare tempo prezioso per lo sviluppo riducendo la necessità di correggere le API noncomplaint più avanti nel ciclo di sviluppo.

L'estensione Centro API per Visual Studio Code offre ai produttori api un'esperienza per eseguire controlli di conformità della progettazione API direttamente in Visual Studio Code durante la compilazione dell'API. Inoltre, i produttori di API possono usare la funzionalità di rilevamento delle modifiche che causano un’interruzione per rilevare quando una modifica può causare l’interruzione di una chat per gli utenti di API.

Conformità alla progettazione dell'API in Visual Studio Code

L'estensione Centro API è integrata con Spectral, un linter JSON/YAML che supporta OpenAPI e un set di regole personalizzato. L'estensione consente agli sviluppatori di seguire rigorosamente la guida allo stile dell'API fornita o consigliata, garantendo la coerenza tra tutte le API sviluppate in team diversi.

Nota

Per usare questa funzionalità, è necessario installare Centro API e Estensioni Spectral.

Per attivare,

1. Usare il tasto di scelta rapida CTRL+MAIUSC+P per aprire il riquadro comandi. Digitare Centro API di Azure: Impostare la Guida di stile API attiva e premere Invio.
2. Selezionare una delle regole predefinite specificate oppure, se l'organizzazione dispone già di una guida di stile, usare Selezionare file locale o URL remoto di input per specificare il set di regole attivo in Visual Studio Code. Premere INVIO.

Dopo aver impostato una guida di stile API attiva, l'apertura di qualsiasi file di specifica basata su OpenAPI o AsyncAPI attiva un'operazione di linting locale in Visual Studio Code. I risultati vengono visualizzati sia inline nell'editor che nella finestra Problemi (Visualizza problemi > o CTRL+MAIUSC+M).

Rilevamento di modifiche di rilievo in Visual Studio Code

La distribuzione di versioni dell'API che interrompono i flussi di lavoro di produzione dei consumer comporta una perdita di attendibilità ed affidabilità. L'estensione centro API, usando l'ottica, consente agli sviluppatori di confrontare facilmente due versioni dell'API e rilevare eventuali modifiche di rilievo introdotte all'API prima della distribuzione.

Nota

È necessario installare l'ottica per usare questa funzionalità. Eseguire l'installazione usando il comando seguente.

*npm install -g @useoptic/optic*

Con questi presupposti,

1. Usare il tasto di scelta rapida CTRL+MAIUSC+P per aprire il riquadro comandi. Digitare Centro API di Azure: Rilevare le modifiche di rilievo e premere INVIO.
2. Selezionare il primo documento di specifica dell'API da confrontare. Le opzioni valide includono le specifiche API disponibili nel centro API, un file locale o l'editor attivo in Visual Studio Code.
3. Selezionare il secondo documento di specifica dell'API da confrontare. Le opzioni valide includono le specifiche API disponibili nel centro API, un file locale o l'editor attivo in Visual Studio Code.

Visual Studio Code apre una visualizzazione diff tra le due specifiche dell'API. Tutte le modifiche di rilievo vengono visualizzate sia inline nell'editor che nella finestra Problemi (Visualizza problemi > o CTRL+MAIUSC+M).