Best practice per l'aggiunta di un provider di tipi

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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 l'aggiunta di un'API esistente come provider del tipo.

Deployment Manager consente di aggiungere le API come provider di tipi per esporre le risorse dell'API come tipi che puoi chiamare nella loro configurazione. Per semplificare la procedura, utilizza 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.

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

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

Per le API Discovery, assegna 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 denominare i metodi 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 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 elemento è valido perché si riferisce alla stessa risorsa /foo:

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

Tuttavia, quanto segue non è valido perché fa riferimento a due diverse risorse dalla visualizzazione di Deployment Manager:

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

In rari casi, potresti tentare di assegnare ai percorsi delle risorse un nome simile al seguente:

foo/create
  post:

foo/delete
  delete:

L'azione non è valida dalla visualizzazione di Deployment Manager perché non è in grado di identificare l'interfaccia RESTful.

Utilizza una denominazione coerente in tutta l'interfaccia

Mantieni gli stessi nomi di input e percorso tra i metodi POST e PUT. Questo vale anche per i valori dei parametri. In altre parole, mantieni la stessa sintassi dei 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 assegnare 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 gestire questo comportamento impostando le opzioni avanzate dell'API.

Inoltre, non modificare il corpo della richiesta per i metodi POST e PUT. Per i metodi GET e DELETE, è applicabile solo il percorso, in quanto non esiste un corpo di 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. Di conseguenza, non esiste un insieme concreto di best practice che possono essere applicate in modo generico a tutte le API. Di seguito è riportato un elenco di consigli generali che potrebbero essere utili per valutare come 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 aggiornare l'API per risolvere questi comportamenti.

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

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

Passaggi successivi