Best practice per l'aggiunta di un provider di tipi

In questa pagina vengono descritte 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 consente di aggiungere API come provider di tipi per esporre le risorse API come tipi che puoi chiamare nella loro configurazione. Per semplificare il processo, 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, segui 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. Attieniti ai metodi REST standard, come i metodi GET, POST, PUT e DELETE. Questi metodi sono riconosciuti da Deployment Manager e possono essere mappati automaticamente.

Per le API di rilevamento, devi denominare i 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 un nome ai metodi dell'API in modo diverso rispetto ai 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 di 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é fa riferimento alla stessa risorsa /foo:

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

Tuttavia, quanto segue 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 avere la tentazione di assegnare un nome ai percorsi delle risorse in questo modo:

foo/create
  post:

foo/delete
  delete:

Non è valido per la visualizzazione di Deployment Manager perché non è in grado di identificare l'interfaccia RESTful.

Utilizza una denominazione coerente in tutta l'interfaccia

Mantieni uguali i nomi dei percorsi e degli input tra i metodi POST e PUT. Questo vale anche per i valori parametro. In altre parole, mantieni la stessa sintassi per i valori parametro in tutti i metodi.

Ad esempio, se hai un parametro denominato email per il corpo di una richiesta POST, non assegnare un nome allo 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 gestire questo comportamento impostando 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é per questi metodi non è presente un corpo della richiesta.

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 da applicare in modo generico a tutte le API. Di seguito è riportato un elenco di consigli generali che potrebbero esserti utili per valutare modi per integrare un'API esistente.

  • Utilizza un wrapper 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, identifica e aggiorna l'API.

    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 un mapping di input.

    Se l'API contiene valori generati dal server richiesti dai metodi dell'API, dovrai configurare mappature degli input per ottenere il valore generato dal server e mapparlo per ogni richiesta.

Passaggi successivi