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 che Deployment Manager si aspetta. Se la tua API non corrisponde esattamente alle specifiche descritte qui, potresti essere in grado di risolvere queste incongruenze 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 di Google Discovery possono essere integrate con Deployment Manager. Per informazioni complete su come creare una specifica OpenAPI, consulta il repository GitHub di OpenAPI.

L'endpoint del documento descrittore API è accessibile

Deployment Manager effettua una richiesta HTTP per ottenere il documento descrittore dell'API, quindi devi assicurarti di ospitare il documento descrittore in un luogo accessibile a Deployment Manager. Può trattarsi di un URL disponibile pubblicamente o di un endpoint protetto dall'autenticazione di base.

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

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

Per saperne di più, consulta Creazione di un fornitore di tipi.

Supporta le operazioni Create, Read, Update, Delete (CRUD)

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

  • Operazioni di creazione: crea risorse. Deve trattarsi di una richiesta HTTP POST.
  • Operazioni di lettura: recupera informazioni sulle risorse API. Deve trattarsi di una richiesta HTTP GET.
  • Operazioni di aggiornamento: aggiorna una risorsa. Deve trattarsi di una richiesta HTTP PUT.
  • Operazioni di eliminazione: elimina le risorse. Deve trattarsi di 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 eliminarla.
Sì Sì No Sì Qualsiasi modifica a una risorsa esistente non andrà 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 la policy ACQUIRE.
Sì No Sì No Gli utenti possono acquisire una risorsa o aggiornarla dopo che è stata acquisita, ma non può essere eliminata.
Sì No No Sì Gli utenti possono eliminare una risorsa e recuperarla oppure aggiungere una risorsa esistente a un deployment.
Sì No No No Gli utenti possono acquisire una risorsa esistente o rimuoverla con la policy ABANDON.

Tutti i parametri di percorso e di query vengono risolti correttamente

Tutti i parametri di percorso e di query dell'API devono esistere come parte del corpo della risorsa o in tutti i metodi dell'API, in modo che Deployment Manager possa trovare una corrispondenza con il parametro quando un utente lo fornisce. Ai parametri di percorso e di query si applicano le seguenti condizioni.

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

Il seguente codice 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 un metodo non POST deve essere presente in tutte le interfacce del metodo o come parte 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 di percorso per un metodo, ma non come parametro di percorso per altri metodi. In questo caso, il campo deve far parte 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 quando si effettua una richiesta POST. Se la proprietà id fosse necessaria per effettuare una richiesta a una risorsa esistente, ma la proprietà non fosse presente nella risorsa o disponibile nel percorso, ciò causerebbe problemi durante la migrazione dell'API a Deployment Manager.

Il comportamento API sottile richiede una configurazione aggiuntiva

Esistono determinati comportamenti API che richiedono una configurazione API aggiuntiva per integrare l'API 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 l'utente effettua una richiesta di aggiornamento di un deployment con questo valore.

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

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

Per saperne di più, consulta Configurazione delle opzioni API avanzate.

Passaggi successivi