Requisiti per l'integrazione di un'API

Questo documento descrive i requisiti generali di un'API che vuoi aggiungere come un provider di tipi a Deployment Manager. Utilizza queste linee guida per comprendere le caratteristiche di un'API previste da Deployment Manager. Se la tua API non corrisponde esattamente alle specifiche descritte qui, potresti riuscire a risolvere queste incoerenze utilizzando le Opzioni API avanzate.

L'API ha un documento descrittore valido

Un documento descrittore descrive un'API e le relative risorse. Solo le API supportate da Una specifica OpenAPI o un Google Discovery può essere integrato con Deployment Manager. Per una visione completa informazioni su come creare una specifica OpenAPI, consulta Repository GitHub di OpenAPI.

L'endpoint del documento descrittore dell'API è accessibile

Deployment Manager effettua una richiesta HTTP per ottenere il documento descrittore del API, quindi devi assicurarti di ospitare il documento descrittore in una posizione che accessibili a Deployment Manager. Può essere un URL disponibile pubblicamente o è un endpoint protetto dall'autenticazione di base.

L'API accetta l'autenticazione di base o OAuth2 se ospitata su determinati servizi Google

Attualmente Deployment Manager supporta l'autenticazione di base (nome utente e password) e l'autenticazione OAuth 2.0 per alcune API ospitate su Google Kubernetes Engine o su endpoint Google. Puoi configurare l'autenticazione in modo da utilizzare l'account di servizio del progetto.

Per ulteriori informazioni, consulta Creazione di un provider di tipi.

Supporta le operazioni di creazione, lettura, aggiornamento, eliminazione (CRUD)

L'API in questione deve essere un'API RESTful che supporta le operazioni CRUD. In altre parole, esistono metodi che eseguono:

  • Operazioni di creazione: crea le risorse. Deve essere una richiesta HTTP POST.
  • Operazioni di lettura: recupera informazioni sulle risorse API. Deve essere un Richiesta di HTTP GET.
  • Operazioni di aggiornamento: aggiorna una risorsa. Deve essere una richiesta HTTP PUT
  • Operazioni di eliminazione: elimina le risorse. Deve essere una richiesta HTTP DELETE.

Un'API che supporta solo operazioni CRUD parziali continuerà a funzionare, ma sarà diverso a seconda delle operazioni disponibili.

Supporta GET richieste Supporta le richieste CREATE Supporta UPDATE richieste Supporta le richieste DELETE Un comportamento speciale dell'API?
Sì Sì Sì Sì Nessuno.
Sì Sì Sì No Gli utenti possono abbandonare una risorsa, ma non possono eliminarla.
Sì Sì No Sì Eventuali modifiche a una risorsa esistente non andrebbero a buon fine. Gli utenti dovranno eliminare e ricreare una risorsa per aggiornarla.
Sì Sì No No Entrambi i comportamenti descritti sopra.
Sì No Sì Sì Se un'API non supporta le richieste di creazione, gli utenti possono aggiungere risorse esistenti aggiornandolo con ACQUIRE .
Sì No Sì No Gli utenti possono acquisire o aggiornare una risorsa dopo che è stata acquisita, ma la risorsa non può essere eliminata.
Sì No No Sì Gli utenti possono eliminare e recuperare una risorsa oppure aggiungerne una esistente risorsa in un deployment.
Sì No No No Gli utenti possono acquisire una risorsa esistente o rimuoverla con il criterio ABANDON.

Tutti i parametri di percorso e query vengono risolti correttamente

Tutti i percorsi e parametri di ricerca dell'API devono esistere nella risorsa corpo o esistere in tutti i metodi dell'API, in modo che Deployment Manager possa quando un utente lo fornisce. Le seguenti condizioni si applicano ai parametri di percorso e di query.

Ogni parametro di percorso/query per un POST deve essere un parametro per PUT

Il seguente valore non è valido perché myParameter esiste per POST, ma non per PUT:

POST  /my-api/{myParameter}/resource/{mySecondParameter}
PUT   /my-api/resource/{mySecondParameter}  # myParameter is not present

Ogni parametro per il metodo non POST deve essere presente in tutte le interfacce del metodo o all'interno della risorsa, con considerazioni speciali se questo parametro viene generato dal server.

Nella migliore delle ipotesi, l'API potrebbe avere il seguente aspetto, dove name viene visualizzato per tutti i metodi.

POST   /my-api/my-resource/{name}
PUT    /my-api/my-resource/{name}
GET    /my-api/my-resource/{name}
DELETE /my-api/my-resource/{name}

In un altro scenario, un campo potrebbe apparire come parametro di percorso per un metodo, ma non come parametro di percorso per altri metodi. In questo caso, il campo dovrebbe essere della risorsa API. Ad esempio:

POST  /my-api/my-resource ← the 'id' field  is not present on the POST request
GET   /my-api/my-resource/{id}

schema for my-resource
type: object
properties:
# id is part of the resource so Deployment Manager will use this value for
# POST requests after creation
  id:
    type: string

In questo esempio, si presuppone che id sia un valore generato dal server presente nella risorsa, ma non presente quando si effettua una richiesta POST. Se la proprietà id era obbligatoria per effettuare una richiesta a una risorsa esistente, ma la proprietà non era presente nella risorsa o non era disponibile nel percorso, si verificano problemi durante il porting dell'API in Deployment Manager.

Il comportamento dell'API richiede una configurazione aggiuntiva

Alcuni comportamenti dell'API richiedono una configurazione aggiuntiva per integrarla con Deployment Manager. Questi comportamenti includono:

  • Valori generati dal server: alcune risorse API hanno valori generati dal server. che cambiano dopo ogni richiesta o quando si verifica un determinato evento l'API. Puoi utilizzare le opzioni API avanzate per comunicare a Deployment Manager di questo nuovo valore ogni volta che viene effettuata una richiesta.

    Ad esempio, un'API potrebbe richiedere la proprietà fingerprint più recente di una risorsa prima di consentire una richiesta di aggiornamento. Utilizza Opzioni API avanzate per indicare a Deployment Manager di recuperare questo valore ogni volta che un utente effettua una richiesta per aggiornare un deployment con questo valore.

  • Manipolazione dell'input utente: ad esempio, se la tua API richiede che il valore di un campo debba sempre essere preceduto da un ID progetto, puoi utilizzare le mappature di input per aggiungere automaticamente queste informazioni, anziché costringere gli utenti ad aggiungerle manualmente.

  • Valori di campo che cambiano con ogni metodo: per i metodi che riutilizzano lo stesso campo, ma con valori diversi, puoi utilizzare le opzioni dell'API per indicare a Deployment Manager quando utilizzare quale valore.

Per ulteriori informazioni, leggi le informazioni Impostazione delle opzioni API avanzate.

Passaggi successivi