Requisiti per l'integrazione di un'API

Questo documento descrive i requisiti generali di un'API che vuoi aggiungere come 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 essere in grado di risolvere queste incoerenze utilizzando 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 repository GitHub di OpenAPI.

L'endpoint del documento descrittore dell'API è accessibile

Deployment Manager effettua una richiesta HTTP per ottenere il documento descrittore dell'API, quindi devi assicurarti di ospitare il documento descrittore in una posizione 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 attualmente supporta l'autenticazione di base (nome utente e password) e l'autenticazione OAuth 2.0 per determinate 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ù, leggi Creazione di un fornitore di tipi.

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

L'API in questione deve essere un'API RESTful che supporti le operazioni CRUD. ovvero esistono metodi che eseguono:

  • Operazioni create: 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
  • Elimina operazioni: elimina le risorse. Deve essere una richiesta HTTP DELETE.

Un'API che supporta solo operazioni CRUD parziali funzionerà comunque, 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ì Qualsiasi modifica a una risorsa esistente non andrebbe 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 l'acquisizione, ma non possono eliminarla.
Sì No No Sì Gli utenti possono eliminare una risorsa e ottenerne una o 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 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 per il parametro quando un utente lo fornisce. Si applicano le seguenti condizioni ai parametri di percorso e query.

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

Il seguente elemento 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 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 presente quando viene effettuata una richiesta POST. Se la proprietà id era necessaria per effettuare una richiesta a una risorsa esistente, ma la proprietà non era presente nella risorsa o disponibile nel percorso, ciò causa problemi durante il porting dell'API in Deployment Manager.

Il comportamento sottile dell'API richiede una configurazione aggiuntiva

Per integrare l'API con Deployment Manager, alcuni comportamenti dell'API richiedono una configurazione aggiuntiva. 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 invia una richiesta di aggiornamento di un deployment.

  • 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 a 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 un valore.

Per maggiori informazioni, leggi la sezione Impostare le opzioni avanzate dell'API.

Passaggi successivi