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 che si aspetta 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 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 del 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 da 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 alcune API ospitate su Google Kubernetes Engine o Google Endpoints. Puoi configurare l'autenticazione per utilizzare l'account di servizio del progetto.

Per ulteriori informazioni, consulta la sezione Creazione di un provider dei tipi.

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

L'API in questione deve essere un'API RESTful che supporta le operazioni CRUD. Cioè, esistono metodi che funzionano:

  • Creazione delle operazioni: crea le risorse. Deve essere una richiesta HTTP POST.
  • Operazioni di lettura: ottiene informazioni sulle risorse dell'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 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 devono 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 aggiornando quest'ultimo con il criterio ACQUIRE.
Sì No Sì No Gli utenti possono acquisire una risorsa o aggiornarne una dopo che è stata acquisita, ma la risorsa non può essere eliminata.
Sì No No Sì Gli utenti possono eliminare una risorsa e ottenerne una oppure possono 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 percorsi e parametri di ricerca vengono risolti correttamente

Tutti i percorsi e parametri di ricerca dell'API devono esistere come parte del corpo della risorsa o esistere in tutti i metodi dell'API, in modo che Deployment Manager possa trovare corrispondenze con il parametro quando viene fornito da un utente. Le seguenti condizioni si applicano ai parametri di percorso e query.

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

Quanto segue 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 il seguente 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 del percorso per un metodo, ma non come parametro del 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 suppone 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 necessaria per effettuare una richiesta a una risorsa esistente, ma la proprietà non si trovava nella risorsa o non era disponibile nel percorso, ciò causa un problema durante il trasferimento dell'API a Deployment Manager.

Il comportamento dell'API sottile richiede una configurazione aggiuntiva

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

  • Valori generati dal server: alcune risorse dell'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 ottenere 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 ottenere questo valore ogni volta che l'utente effettua una richiesta di aggiornamento di un deployment con questo valore.

  • Manipolazione dell'input utente: ad esempio, se la tua API richiede che il valore di un campo debba essere sempre preceduto da un ID progetto, puoi utilizzare le mappature degli input per aggiungere automaticamente queste informazioni, anziché obbligare 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 ulteriori informazioni, consulta la sezione sull'impostazione delle opzioni avanzate per l'API.

Passaggi successivi