Questa pagina si applica ad Apigee e Apigee hybrid.
Questo argomento spiega cosa devi sapere sulla creazione e sulla gestione delle versioni nell'hub API.
Cos'è una versione?
A ogni risorsa API è associata almeno una versione. Una versione può essere considerata come lo stato di un'API in un determinato momento. Fondamentalmente, le versioni consentono di raggruppare e organizzare le API in base a insiemi di operazioni, deployment e altri attributi sottostanti.
Nell'hub delle API, una versione rappresenta un raggruppamento logico di API. Solitamente, ma non necessariamente, questo raggruppamento è incentrato sulle operazioni che un'API può eseguire. Ad esempio, supponiamo di avere un'API Pet Store e che la prima versione di questa API ti consenta di eseguire attività di base, come aggiungere un animale domestico, trovare un animale domestico ed eliminare un animale domestico dal negozio. Ecco alcuni esempi di operazioni.
È buona norma che una versione includa un set di operazioni API di cui viene eseguito il deployment insieme. Ad esempio, un'API per un negozio di animali potrebbe avere una versione che include operazioni di aggiunta, ricerca ed eliminazione, tutte distribuite negli stessi ambienti.
Un altro modo valido per pensare a una versione è che rappresenti il punto di vista dell'API da parte del produttore dell'API. Si tratta della raccolta di caratteristiche e capacità che le persone che hanno creato l'API vi inseriscono e si aspettano di eseguirne il deployment.
Creazione delle versioni
Supponiamo che i dettagli di un'API che vuoi aggiungere all'hub API vengano acquisiti in una specifica OpenAPI. In questo caso, puoi aggiungere la specifica a una versione API. In questo caso, l'hub API analizza la specifica ed estrae informazioni da quest'ultima, ad esempio le operazioni incluse nell'API, e le archivia insieme alla versione. Se non hai una specifica OpenAPI, puoi comunque creare una versione, ma dovrai compilarla manualmente con informazioni descrittive pertinenti. Un altro caso in cui l'hub API supporta l'analisi dei dettagli delle API tramite la registrazione automatica dei proxy API Apigee.
Puoi caricare più file di specifiche API nella stessa versione.
Quando creare una nuova versione?
Se a un'API vengono aggiunte nuove operazioni, potrebbe giustificare la creazione di una nuova versione, o forse no.
Supponiamo che il producer di API aggiunga una nuova operazione a un'API e intenda eseguirne il deployment in tutti i deployment attualmente associati alla versione. In questo caso, il producer può scegliere di non creare una nuova versione dell'API. Se, invece, il producer apporta una modifica incompatibile con le versioni precedenti (una modifica che provoca un errore) e sceglie di associarla a un nuovo deployment, può essere opportuno creare una nuova versione.
Puoi vedere che l'hub API ti offre la flessibilità necessaria per definire e organizzare le versioni delle API in base alle esigenze della tua organizzazione e di produttori di API specifici.
Attributi di sistema
Per impostazione predefinita, le versioni includono i seguenti attributi di sistema. Puoi modificare i valori associati a questi attributi in Impostazioni. Per maggiori dettagli, vedi Gestire gli attributi.
| Attributo | Descrizione |
|---|---|
| Fase del ciclo di vita dell'API | Per ciclo di vita si intende un insieme ordinato di fasi attraverso le quali un'API deve avanzare, dall'ideazione alla fine del ciclo di vita. Poiché ogni versione di un'API solitamente si sposta nel proprio ciclo di vita separatamente, non impostiamo direttamente la fase del ciclo di vita di un'API, ma consentiamo a ogni versione dell'API di avere una fase del ciclo di vita assegnata. |
| Documentazione | Un link alla documentazione dell'API a cui è allegata la versione. |
| Conformità | Tramite le impostazioni, puoi definire valori che rappresentino i dettagli di conformità di interesse per il tuo team o la tua organizzazione. Per maggiori dettagli, vedi Gestire gli attributi. |
| Accreditamento | Tramite le Impostazioni, puoi definire valori che rappresentano i dettagli di accreditamento di interesse per il tuo team o la tua organizzazione. Per maggiori dettagli, vedi Gestire gli attributi. |
Attributi definiti dall'utente
A seconda delle esigenze del team o dell'organizzazione, puoi definire attributi personalizzati (coppie nome/valore) per le versioni. Consulta Gestire gli attributi.