Best practice per l'aggiunta di un provider di tipi

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

Deployment Manager ti consente di aggiungere API come provider di tipi per esporre le risorse API come tipi che puoi chiamare nella configurazione. Per semplificare la procedura, utilizza 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 di creazione, lettura, aggiornamento ed eliminazione (CRUD) ed evita i metodi personalizzati

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

Per le API Discovery, devi denominare i metodi API in base al seguente mapping:

Metodo REST Nomenclatura delle API consigliata
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. Il primo caso si verifica 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, il seguente è valido perché si riferisce alla stessa risorsa /foo:

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

Tuttavia, il seguente è un riferimento 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 denominare i percorsi delle risorse nel seguente modo:

foo/create
  post:

foo/delete
  delete:

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

Utilizzare una denominazione coerente nell'interfaccia

Mantieni invariati i nomi di input e dei percorsi tra i metodi POST e PUT. Questo vale anche per i valori dei parametri. ovvero mantieni la stessa sintassi per i valori dei parametri in tutti i metodi.

Ad esempio, se hai un parametro denominato email per il corpo della richiesta di una richiesta POST, non denominare lo stesso parametro emailAddress 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, in quanto non è presente un corpo della richiesta per questi metodi.

Integrazione di un'API esistente

L'integrazione di un'API esistente può essere un processo molto variabile a seconda dell'API. Pertanto, non esiste un insieme concreto di best practice che possa essere applicato in modo generico a tutte le API. Di seguito è riportato un elenco di consigli generali che potrebbero essere utili quando valuti i modi per integrare un'API esistente.

  • Utilizza un wrapper API per le API non RESTful.

    Se un'API esistente non è un'API RESTful, puoi creare un wrapper 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, potresti 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 API, dovrai configurare mappature di input per ottenere il valore generato dal server e mapparlo per ogni richiesta.

Passaggi successivi