Metodi personalizzati

Questo capitolo illustra come utilizzare i metodi personalizzati per la progettazione di API.

Oltre ai cinque metodi standard, i metodi personalizzati si riferiscono ai metodi API. Utilizzali solo per funzionalità che non possono essere espresse facilmente tramite metodi standard. In generale, i designer API dovrebbero scegliere i metodi standard, anziché i metodi personalizzati, quando possibile. I metodi standard hanno una semantica più semplice e ben definita che la maggior parte degli sviluppatori conosce, quindi è più facile da usare e meno soggetta a errori. Un altro vantaggio dei metodi standard è che la piattaforma API offre una migliore comprensione e supporto di metodi standard, come fatturazione, gestione degli errori, logging e monitoraggio.

Un metodo personalizzato può essere associato a una risorsa, a una raccolta o a un servizio. Può prendere una richiesta arbitraria e restituire una risposta arbitraria e supporta anche il flusso di richieste e risposte.

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

Mappatura HTTP

Per i metodi personalizzati, dovrebbero utilizzare la seguente mappatura HTTP generica:

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

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

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

• I metodi personalizzati dovrebbero utilizzare il verbo HTTP POST perché ha la semantica più flessibile, ad eccezione dei metodi che servono come metodo alternativo o un elenco alternativo che potrebbe usare GET quando possibile. Per le specifiche, consulta il terzo punto dell'elenco.
• I metodi personalizzati non devono utilizzare HTTP PATCH, ma possono usare 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 dovrebbero utilizzare HTTP GET.
• I campi dei messaggi 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 composto da due punti seguito dal verbo personalizzato.
• Se il verbo HTTP utilizzato per il metodo personalizzato consente un corpo di richiesta HTTP (si applica a POST, PUT, PATCH o un verbo HTTP personalizzato), la configurazione HTTP di quel metodo personalizzato deve utilizzare la clausola body: "*" e tutti i campi del messaggio di richiesta rimanenti devono essere mappati sul corpo della richiesta HTTP.
• Se il verbo HTTP utilizzato per il metodo personalizzato non accetta un corpo di richiesta HTTP (GET, DELETE), la configurazione HTTP di questo metodo non deve utilizzare la clausola body e tutti i restanti campi del messaggio di richiesta 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 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

Altri scenari in cui i metodi personalizzati potrebbero essere la scelta giusta:

• Riavvia una macchina virtuale. Le alternative di progettazione potrebbero essere "creare una risorsa di riavvio nella raccolta di riavvii" che risulta sproporzionatamente complessa oppure "la macchina virtuale ha uno stato modificabile che il client può aggiornare da RUNNING a RESTARTING" ed è possibile aprire domande su quali possibili transizioni di stato sono possibili. Inoltre, il riavvio è un concetto ben noto che può tradurre bene in un metodo personalizzato che soddisfa in modo intuitivo le aspettative degli sviluppatori.
• Inviare email. Le email create non devono necessariamente essere inviate (bozza). Rispetto al metodo di progettazione alternativo (spostare un messaggio in una raccolta "Posta in uscita") ha il vantaggio di essere più rilevabile dall'utente dell'API e modella il concetto più direttamente.
• Promuovi un dipendente. Se implementato come standard, update il cliente dovrà replicare le norme aziendali che regolano il processo di promozione per garantire che la promozione avvenga al livello corretto, all'interno della stessa scala della carriera e così via.
• Metodi batch. Per i metodi fondamentali per le prestazioni, potrebbe essere utile fornire metodi batch personalizzati per ridurre le spese generali per richiesta. Ad esempio, accounts.locations.batchGet.

Alcuni esempi in cui un metodo standard è più adatto di un metodo personalizzato:

• Risorse delle query con parametri di ricerca diversi (utilizza il metodo list standard con filtri degli elenchi standard).
• Facile modifica della proprietà delle risorse (utilizza il metodo update standard con la maschera di campo).
• Ignora una notifica (utilizza il metodo standard delete).

Metodi personalizzati comuni

Di seguito è riportato un elenco curato di nomi di metodi personalizzati di uso comune o utili. I designer delle API dovrebbero prendere in considerazione questi nomi prima di presentarli 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. Vedi i dettagli nella descrizione dell'elenco.
Move	:move	POST	Spostare una risorsa da un elemento padre a un altro, ad esempio folders.move.
Search	:search	GET	Metodo alternativo all'elenco per il recupero dei dati che non rispettano la semantica dell'elenco, come services.search.
Undelete	:undelete	POST	Ripristinare una risorsa precedentemente eliminata, ad esempio services.undelete. Il periodo di conservazione consigliato è di 30 giorni.