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, segui queste best practice quando configuri o crei un'API.

Creazione di una nuova API

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

Utilizza i metodi standard Create, Read, Update e Delete (CRUD) ed evita i metodi personalizzati

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

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

Metodo REST Denominazione 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.

Utilizza percorsi delle risorse prevedibili

Per le specifiche OpenAPI, Deployment Manager supporta due comportamenti per identificare un'interfaccia RESTful. Il primo è 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é fa riferimento alla stessa risorsa /foo:

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

Tuttavia, il seguente non è valido perché fa riferimento 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 nomi come i seguenti:

foo/create
  post:

foo/delete
  delete:

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

Utilizza una denominazione coerente nell'interfaccia

Mantieni invariati i nomi di input e percorso tra i metodi POST e PUT. Questo vale anche per i valori dei parametri. Ovvero, mantieni la stessa sintassi per i valori dei parametri tra i metodi.

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

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

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

Se devi aggiungere questo tipo di comportamento, indica a Deployment Manager come gestire questo comportamento 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, poiché non esiste un corpo della richiesta per questi metodi.

Integrazione di un'API esistente

L'integrazione di un'API esistente può essere un processo molto vario 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 ha 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 API, dovrai configurare le mappature di input per ottenere il valore generato dal server e mapparlo per ogni richiesta.

Passaggi successivi