Metodi personalizzati

Questo capitolo illustra come utilizzare i metodi personalizzati per le progettazioni di API.

I metodi personalizzati si riferiscono ai metodi API oltre ai cinque metodi standard. Deve essere utilizzato solo per funzionalità che non possono essere facilmente espresse tramite metodi standard. In generale, quando possibile, i designer delle API devono scegliere metodi standard anziché metodi personalizzati. I metodi standard hanno una semantica più semplice e ben definita che la maggior parte degli sviluppatori conosce. Pertanto, sono più facili da usare e meno soggetti a errori. Un altro vantaggio dei metodi standard è che la piattaforma API ha una migliore comprensione e supporto dei metodi standard, come fatturazione, gestione degli errori, logging e monitoraggio.

Un metodo personalizzato può essere associato a una risorsa, una raccolta o un servizio. Potrebbe accettare una richiesta arbitraria e restituire una risposta arbitraria. Inoltre, supporta anche richieste e risposte in modalità flusso.

I nomi dei metodi personalizzati devono seguire le convenzioni di denominazione dei metodi.

Mapping HTTP

I metodi personalizzati devono utilizzare la seguente mappatura HTTP generica:

https://service.name/v1/some/resource/name:customVerb

Il motivo per utilizzare : anziché / per separare il verbo personalizzato dal nome della risorsa è supportare percorsi arbitrari. Ad esempio, l'annullamento dell'eliminazione di un file può essere mappato su POST /files/a/long/file/name:undelete

Quando scegli la mappatura HTTP, dovranno essere applicate le seguenti linee guida:

I metodi personalizzati devono utilizzare il verbo HTTP POST poiché ha la semantica più flessibile, ad eccezione dei metodi che fungono da get o list alternativi che possono utilizzare GET quando possibile. (per le specifiche, vedi il terzo punto dell'elenco.)
I metodi personalizzati non devono utilizzare HTTP PATCH, ma possono utilizzare altri verbi HTTP. In questi casi, i metodi devono seguire la semantica HTTP standard per quel verbo.
In particolare, i metodi personalizzati che utilizzano HTTP GET devono essere idempotenti e non avere effetti collaterali. Ad esempio, i metodi personalizzati che implementano visualizzazioni speciali della risorsa devono utilizzare HTTP GET.
I campi del messaggio di richiesta che ricevono il nome della risorsa o della raccolta a cui è associato il metodo personalizzato devono essere mappati al percorso dell'URL.
Il percorso dell'URL deve terminare con un suffisso costituito da due punti seguiti dal verbo personalizzato.
Se il verbo HTTP utilizzato per il metodo personalizzato consente il corpo di una richiesta HTTP (questo si applica a POST, PUT, PATCH o a un verbo HTTP personalizzato), la configurazione HTTP di quel metodo personalizzato deve usare la clausola body: "*" e tutti i campi dei messaggi della richiesta rimanenti devono essere mappati al corpo della richiesta HTTP.
Se il verbo HTTP utilizzato per il metodo personalizzato non accetta un corpo della richiesta HTTP (GET, DELETE), la configurazione HTTP di questo metodo non deve utilizzare la clausola body e tutti i campi dei messaggi di richiesta rimanenti devono essere mappati ai parametri di ricerca dell'URL.

AVVISO: se un servizio implementa più API, il producer di API deve creare con attenzione la configurazione del servizio per evitare conflitti di verbi personalizzati tra le API.

// This is a service level custom method.
rpc Watch(WatchRequest) returns (WatchResponse) {
  // Custom method maps to HTTP POST. All request parameters go into body.
  option (google.api.http) = {
    post: "/v1:watch"
    body: "*"
  };
}

// This is a collection level custom method.
rpc ClearEvents(ClearEventsRequest) returns (ClearEventsResponse) {
  option (google.api.http) = {
    post: "/v3/events:clear"
    body: "*"
  };
}

// This is a resource level custom method.
rpc CancelEvent(CancelEventRequest) returns (CancelEventResponse) {
  option (google.api.http) = {
    post: "/v3/{name=events/*}:cancel"
    body: "*"
  };
}

// This is a batch get custom method.
rpc BatchGetEvents(BatchGetEventsRequest) returns (BatchGetEventsResponse) {
  // The batch get method maps to HTTP GET verb.
  option (google.api.http) = {
    get: "/v3/events:batchGet"
  };
}

Casi d'uso

Ecco alcuni scenari aggiuntivi in cui i metodi personalizzati possono essere la scelta giusta:

Riavvia una macchina virtuale. Le alternative di progettazione potrebbero essere "creare una risorsa di riavvio in una raccolta di riavvii", che sembra sproporzionatamente complessa, o "la macchina virtuale ha uno stato modificabile che il client può aggiornare da IN ESECUZIONE a RIAVVIO IN CORSO", con domande su quali siano possibili altre transizioni di stato. Inoltre, il riavvio è un concetto ben noto e può tradursi in un metodo personalizzato che soddisfa intuitivamente le aspettative degli sviluppatori.
Invia email. La creazione di un messaggio email non deve necessariamente inviarlo (bozza). Rispetto al metodo personalizzato alternativo di progettazione (spostamento di un messaggio in una raccolta "Posta in uscita"), offre il vantaggio di essere più rilevabile dall'utente dell'API e di modellare il concetto in modo più diretto.
Promuovi un dipendente. Se implementato come standard update, il cliente dovrebbe replicare le norme aziendali che regolano il processo di promozione per garantire che la promozione avvenga al livello corretto, all'interno della stessa carriera e così via.
Metodi batch. Per i metodi critici per le prestazioni, potrebbe essere utile fornire metodi batch personalizzati per ridurre l'overhead per richiesta. ad esempio accounts.locations.batchGet.

Ecco alcuni esempi in cui un metodo standard è più adatto rispetto a un metodo personalizzato:

Esegui una query sulle risorse con diversi parametri di ricerca (utilizza il metodo list standard con il filtro standard degli elenchi).
Modifica semplice della proprietà della risorsa (utilizza il metodo update standard con la maschera del campo).
Ignorare una notifica (utilizza il metodo delete standard).

Metodi personalizzati comuni

Di seguito è riportato l'elenco selezionato di nomi di metodi personalizzati utili o di uso comune. I designer delle API devono prendere in considerazione questi nomi prima di introdurne uno per facilitare la coerenza tra le API.

Nome metodo	Verbo personalizzato	Verbo HTTP	Nota
`Cancel`	`:cancel`	`POST`	Annullare un'operazione in sospeso, ad esempio `operations.cancel`.
`BatchGet`	`:batchGet`	`GET`	Recupero in batch di più risorse. Per informazioni dettagliate, consulta la descrizione dell'elenco.
`Move`	`:move`	`POST`	Spostare una risorsa da un elemento padre all'altro, ad esempio `folders.move`.
`Search`	`:search`	`GET`	Opzione alternativa all'elenco per recuperare i dati che non rispettano la semantica dell'elenco, ad esempio `services.search`.
`Undelete`	`:undelete`	`POST`	Ripristina una risorsa eliminata in precedenza, ad esempio `services.undelete`. Il periodo di conservazione consigliato è di 30 giorni.