Condividi tramite

Usare DevOps e CI/CD per pubblicare le API

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

Con il valore strategico delle API nell'azienda, l'adozione di tecniche di integrazione (CI) e distribuzione (CD) continue DevOps è diventato un aspetto importante dello sviluppo di API. Questo articolo illustra le decisioni da prendere per adottare i principi DevOps per la gestione delle API.

L'API DevOps è costituita da tre parti:

Diagramma che illustra il flusso devOps dell'API.

Di seguito viene descritta ogni parte della pipeline DevOps dell'API.

Definizione API

Uno sviluppatore di API scrive una definizione di API fornendo una specifica, impostazioni (ad esempio le impostazioni di registrazione, diagnostica e back-end) e i criteri da applicare all'API. La definizione dell'API fornisce le informazioni necessarie per effettuare il provisioning dell'API in un servizio Gestione API di Azure. La specifica può essere basata su una specifica API basata su standard (ad esempio WSDL, OpenAPIo GraphQL) oppure può essere definita usando le API di Azure Resource Manager (ARM), ad esempio un modello di Resource Manager che descrive l'API e le operazioni di Azure Resource Manager. La definizione dell'API cambierà nel tempo e deve essere considerata "codice sorgente". Verificare che la definizione dell'API sia archiviata nel controllo del codice sorgente e sia sottoposta a una revisione appropriata prima dell'adozione.

Sono disponibili diversi strumenti per facilitare la produzione della definizione dell'API:

  • Azure APIOps Toolkit offre un flusso di lavoro basato su un sistema di controllo del codice sorgente Git, ad esempio GitHub o Azure Repos. Usa un estrattore per produrre una definizione API che viene quindi applicata a un servizio Gestione API di destinazione da un server di pubblicazione. APIOps supporta attualmente le API REST e GraphQL.
  • Lo strumento dotnet-apim converte una definizione YAML ben formata in un modello ARM per una distribuzione successiva. Lo strumento è incentrato sulle API REST.
  • Terraform è un'alternativa ad Azure Resource Manager per configurare le risorse in Azure. È possibile creare una configurazione Terraform (insieme ai criteri) per implementare l'API nello stesso modo in cui viene creato un modello di Resource Manager.

È anche possibile usare strumenti basati su IDE per gli editor, ad esempio Visual Studio Code, per produrre gli artefatti necessari per definire l'API. Ad esempio, esistono più di 30 plug-in per la modifica dei file di specifica OpenAPI nel Marketplace di Visual Studio Code. È anche possibile usare generatori di codice per creare gli artefatti. Il linguaggio CADL consente di creare facilmente blocchi predefiniti di alto livello e quindi di compilarli in un formato di definizione API standard, ad esempio OpenAPI.

Approvazione API

Dopo aver prodotto la definizione dell'API, lo sviluppatore indicherà la definizione dell'API per la revisione e l'approvazione. Se si usa un sistema di controllo del codice sorgente basato su Git (ad esempio GitHub o Azure Repos), l'invio può essere eseguito tramite richiesta pull. Una richiesta pull informa altri utenti delle modifiche proposte alla definizione dell'API. Dopo aver confermato i controlli di approvazione, un responsabile dell’approvazione unisce la richiesta pull nel repository principale per indicare che la definizione dell'API può essere distribuita nell'ambiente di produzione. Il processo di richiesta pull consente allo sviluppatore di correggere eventuali problemi rilevati durante il processo di approvazione.

Sia GitHub che Azure Repos consentono di configurare le pipeline di approvazione che vengono eseguite quando viene inviata una richiesta pull. È possibile configurare le pipeline di approvazione per eseguire strumenti come:

  • Linter delle specifiche API, ad esempio Spectral, per garantire che la definizione soddisfi gli standard API richiesti dall'organizzazione.
  • Rilevamento di modifiche che causano un'interruzione usando strumenti come openapi-diff.
  • Strumenti di controllo e valutazione della sicurezza. OWASP gestisce un elenco di strumenti per l'analisi della sicurezza.
  • Framework di test automatizzati dell'API.

Nota

Le API di Azure devono essere conformi a una serie rigorosa di linee guida che è possibile usare come punto di partenza per le proprie linee guida per le API. È disponibile una configurazione Spectral per l’applicazione delle linee guida.

Una volta eseguiti gli strumenti automatizzati, la definizione dell'API viene esaminata dall'occhio umano. Gli strumenti non intercettano tutti i problemi. Un revisore umano garantisce che la definizione dell'API soddisfi i criteri dell'organizzazione per le API, inclusa la conformità alle linee guida per la sicurezza, la privacy e la coerenza.

Pubblicazione API

La definizione dell'API verrà pubblicata in un servizio Gestione API tramite una pipeline di versione. Gli strumenti usati per pubblicare la definizione dell'API dipendono dallo strumento usato per produrre la definizione dell'API:

  • Se si usa Azure APIOps Toolkit, il toolkit include un server di pubblicazione che scrive la definizione dell'API nel servizio di destinazione.
  • Se si usa dotnet-apim, la definizione dell'API viene rappresentata come modello di Resource Manager. Sono disponibili attività per Azure Pipelines e GitHub Actions per distribuire un modello di Resource Manager.
  • Se si usa Terraform, gli strumenti dell'interfaccia della riga di comando distribuiranno la definizione dell'API nel servizio. Sono disponibili attività per Azure Pipelines e GitHub Actions.

È possibile usare altri sistemi di controllo del codice sorgente e CI/CD?

Sì. Il processo descritto funziona con qualsiasi sistema di controllo del codice sorgente (anche se APIOps richiede che il sistema di controllo del codice sorgente sia basato su Git). Analogamente, è possibile usare qualsiasi piattaforma CI/CD, purché possa essere attivata da un'archiviazione e possa eseguire strumenti da riga di comando che comunicano con Azure.

Procedure consigliate

Non esiste uno standard di settore per la configurazione di una pipeline DevOps per la pubblicazione di API e nessuno degli strumenti menzionati funzionerà in tutte le situazioni. Tuttavia, si noterà che la maggior parte delle situazioni è coperta dall'uso di una combinazione dei seguenti strumenti e servizi:

Le distribuzioni dei clienti hanno dato esito positivo e si consigliano le procedure seguenti:

  • Configurare GitHub o Azure Repos per il sistema di controllo del codice sorgente. Questa scelta determinerà anche la scelta dello strumento di esecuzione della pipeline. GitHub può usare Azure Pipelines o GitHub Actions, mentre Azure Repos deve usare Azure Pipelines.
  • Configurare un servizio Gestione API di Azure per ogni sviluppatore di API in modo da poter sviluppare definizioni API insieme al servizio API. Usare lo SKU per l'utilizzo o lo sviluppo durante la creazione del servizio.
  • Usare frammenti di criteri per ridurre i nuovi criteri che gli sviluppatori devono scrivere per ogni API.
  • Usare valori denominati e back-end per assicurarsi che i criteri siano generici e possano essere applicati a qualsiasi istanza di Gestione API.
  • Usare Azure APIOps Toolkit per estrarre una definizione dell'API funzionante dal servizio per sviluppatori.
  • Configurare un processo di approvazione dell'API eseguito in ogni richiesta pull. Il processo di approvazione dell'API deve includere il rilevamento delle modifiche di rilievo, il linting e il test automatizzato dell'API.
  • Usare il server di pubblicazione Azure APIOps Toolkit per pubblicare l'API nel servizio Gestione API di produzione.

Per altre informazioni su come configurare ed eseguire una pipeline di distribuzione CI/CD con APIOps, vedere Distribuzioni API automatizzate con APIOps.

Riferimenti