Best practice per l'aggiunta di un provider di tipi

Questa pagina descrive le best practice per creare una nuova API da aggiungere a Deployment Manager come provider di tipi o per aggiungere un'API esistente come provider di tipi.

Deployment Manager ti consente di aggiungere API come provider di tipi per esporre le risorse dell'API come tipi che puoi chiamare nella loro configurazione. Per semplificare la procedura, segui queste best practice durante la configurazione o la creazione di un'API.

Creazione di una nuova API

Se stai creando una nuova API che intendi integrare con Deployment Manager, utilizza queste best practice.

Utilizza i metodi standard Crea, Leggi, Aggiorna ed Elimina (CRUD) ed evita i metodi personalizzati

Se possibile, evita di creare metodi personalizzati. Utilizza i metodi REST standard come GET, POST, PUT e DELETE. Questi metodi sono riconosciuti da Deployment Manager e possono essere mappati automaticamente.

Per le API Discovery, devi assegnare un nome ai metodi dell'API in base alla seguente mappatura:

Metodo REST Nomi delle API consigliati
POST create o insert
GET get
PUT update
DELETE delete

Per le specifiche OpenAPI, non puoi assegnare ai metodi API nomi diversi da quelli dei metodi REST standard.

Utilizzare percorsi delle risorse prevedibili

Per le specifiche OpenAPI, Deployment Manager supporta due comportamenti per identificare un'interfaccia RESTful. La prima è se tutti i metodi REST per una risorsa appartengono allo stesso percorso della risorsa:

/foo/{name}
  post:
  get:
  delete:
  put:

Se devi separare i metodi, utilizza lo stesso percorso della risorsa. Ad esempio, quanto segue è valido perché si riferisce alla stessa risorsa /foo:

/foo/
  post:
/foo/{id}
  get:
  delete:
  put:

Tuttavia, il seguente non è valido perché si riferisce a due risorse diverse dal punto di vista di Deployment Manager:

/foo/
 post:
/foo-bar/{id}:
 get:
 put:
 delete:

In rari casi, potresti essere tentato di assegnare ai percorsi delle risorse i seguenti nomi:

foo/create
  post:

foo/delete
  delete:

Questo valore non è valido dal punto di vista di Deployment Manager perché non è possibile identificare l'interfaccia RESTful.

Utilizza una denominazione coerente nell'interfaccia

Mantieni invariati i nomi di input e percorso tra i metodi POST e PUT. Lo stesso vale anche per i valori dei parametri. In altre parole, mantieni invariata la sintassi per i valori dei parametri tra i metodi.

Ad esempio, se hai un parametro denominato email per il corpo della richiesta di una richiesta POST, non assegnare lo stesso nome emailAddress al parametro per la richiesta PUT.

POST
{
    “email”: “my-email”
}

PUT
{
    “email”: “my-email@gmail.com”
}

Se devi aggiungere questo tipo di comportamento, indica a Deployment Manager come gestirlo impostando le opzioni API avanzate.

Inoltre, mantieni invariato il corpo della richiesta per i metodi POST e PUT. Per i metodi GET e DELETE, è applicabile solo il percorso perché non esiste nessun corpo della richiesta per questi metodi.

Integrazione di un'API esistente

L'integrazione di un'API esistente può essere un processo molto diverso a seconda dell'API. Di conseguenza, non esiste un insieme concreto di best practice che possa essere applicato genericamente a tutte le API. Di seguito è riportato un elenco di consigli generali che potrebbero essere utili per valutare i modi per integrare un'API esistente.

  • Utilizza un wrapper dell'API per le API non RESTful.

    Se un'API esistente non è un'API RESTful, puoi creare un wrapper dell'API per esporre solo i metodi REST.

  • Se l'API è quasi RESTful, identificala e aggiornala.

    Se la tua API è quasi RESTful e presenta solo alcuni comportamenti non REST, puoi aggiornarla per risolvere questi comportamenti.

  • I valori generati dal server richiedono sempre una mappatura di input.

    Se la tua API ha valori generati dal server richiesti dai metodi dell'API, dovrai configurare mappature di input per ottenere il valore generato dal server e mapparlo per ogni richiesta.

Passaggi successivi