Requisiti per l'integrazione di un'API

Questo documento descrive i requisiti generali di un'API che vuoi aggiungere come fornitore 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 da un documento descrittore Google Discovery possono essere integrate con Deployment Manager. Per informazioni complete su come creare una specifica OpenAPI, consulta il repo GitHub di OpenAPI.

L'endpoint del documento descrittore dell'API è accessibile

Deployment Manager invia una richiesta HTTP per recuperare il documento descrittore dell'API, quindi devi assicurarti di ospitare il documento descrittore in un luogo accessibile da 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 la sezione Creare un provider di tipi.

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

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

  • Crea operazioni: crea risorse. Deve essere una richiesta HTTP POST.
  • Operazioni di lettura: recupera informazioni sulle risorse API. Deve essere una richiesta 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 il comportamento sarà diverso a seconda delle operazioni disponibili.

Supporta le richieste GET Supporta le richieste CREATE Supporta le richieste UPDATE Supporta le richieste DELETE 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 andranno 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 al deployment aggiornandolo con il criterio ACQUIRE.
Sì No Sì No Gli utenti possono acquisire una risorsa o aggiornarla dopo che è stata acquisita, ma la risorsa non può essere eliminata.
Sì No No Sì Gli utenti possono eliminare una risorsa e ottenerne un'altra oppure aggiungere una risorsa esistente a 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 parametri di percorso e query dell'API devono esistere nel corpo della risorsa o in tutti i metodi dell'API, in modo che Deployment Manager possa associare il parametro quando un utente lo fornisce. Le seguenti condizioni si applicano ai parametri di percorso e di query.

Ogni parametro path/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.

Nel migliore dei casi, l'API potrebbe avere questo aspetto, in cui il parametro 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 essere visualizzato come parametro percorso per un metodo, ma non come parametro percorso per altri metodi. In questo caso, il campo deve essere parte della risorsa dell'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 presume che id sia un valore generato dal server presente nella risorsa, ma non quando viene effettuata 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 proprietà generate dal server che cambiano dopo ogni richiesta o quando si verifica un determinato evento nell'API. Puoi utilizzare le opzioni API avanzate per indicare a Deployment Manager di recuperare 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, consulta la sezione Impostare le opzioni API avanzate.

Passaggi successivi