Metodi personalizzati

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

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

I metodi personalizzati si riferiscono ai metodi API oltre ai 5 metodi standard. Devono essere utilizzate solo per funzionalità che non possono essere espresse facilmente tramite metodi standard. In generale, i designer delle API dovrebbero scegliere i metodi standard piuttosto che quelli personalizzati, laddove possibile. I metodi Standard hanno una semantica più semplice e ben definita che la maggior parte degli sviluppatori ha familiarità, quindi sono più facili da usare e meno soggetti a errori. Un altro vantaggio dei metodi standard è che la piattaforma API comprende e supporta meglio i 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, restituire una risposta arbitraria e supportare anche lo streaming e la richiesta di risposta.

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

Mappatura HTTP

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

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

Il motivo per cui utilizzare : invece di / per separare il verbo personalizzato dal nome della risorsa è supportare i percorsi arbitrari. Ad esempio, se annulli l'eliminazione di un file puoi mappare a POST /files/a/long/file/name:undelete

Quando scegli il mapping di HTTP, devono essere applicate le seguenti linee guida:

  • I metodi personalizzati dovrebbero utilizzare il verbo POST HTTP perché presenta la semantica più flessibile, ad eccezione dei metodi che forniscono metodi di recupero o elenchi che possono usare GET quando possibile. (Consulta il terzo punto per le specifiche).
  • I metodi personalizzati non devono utilizzare PATCH HTTP, ma possono usare altri verbi HTTP. In questi casi, i metodi devono seguire la sintassi HTTP standard per quel verbo.
  • In particolare, i metodi personalizzati che utilizzano HTTP GET devono essere idempotenti e non devono avere effetti collaterali. Ad esempio, i metodi personalizzati che implementano visualizzazioni speciali nella risorsa dovrebbero usare GET HTTP.
  • 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 composto da due punti seguiti dal verbo personalizzato.
  • Se il verbo HTTP utilizzato per il metodo personalizzato consente un corpo di richiesta HTTP (questo vale per POST, PUT, PATCH o per un verbo HTTP personalizzato), la configurazione HTTP di quel metodo personalizzato deve utilizzare la clausola Clausolare e tutti i campi dei messaggi di richiesta rimanenti vengono mappati al 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 tale 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 produttore dell'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", il che sembra un processo sproporzionatamente complesso, o "una macchina virtuale ha uno stato modificabile che il client può aggiornare da RUNNING a RESTARTING", che aprirebbe domande sulle possibili transizioni di stato. Inoltre, il riavvio è un concetto ben noto che può tradurre bene in un metodo personalizzato che soddisfa in modo intuitivo le aspettative degli sviluppatori.
  • Invia email. Quando crei un messaggio email, non devi necessariamente inviarlo (bozza). Rispetto all'alternativa strutturale (spostamento di un messaggio in una raccolta personalizzata di Outbox), offre il vantaggio di essere più rilevabile dall'utente dell'API e di modellare il concetto più direttamente.
  • Promuovi un dipendente. Se implementato come standard, update dovrebbe replicare le norme aziendali che regolano il processo promozionale, per assicurare che la promozione avvenga al livello corretto, nella stessa carriera e così via.
  • Metodi batch. Per i metodi fondamentali per le prestazioni, potrebbe essere utile fornire metodi batch personalizzati per ridurre l'overhead richiesto per richiesta. Ad esempio, accounts.locations.batchGet.

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

  • Query delle risorse con parametri di ricerca diversi (utilizza il metodo list standard con il filtro elenco standard).
  • Modifica semplice della proprietà delle risorse (utilizza il metodo update standard con maschera dei campi).
  • Ignora una notifica (utilizza il metodo standard delete).

Metodi personalizzati comuni

Di seguito è riportato un elenco selezionato di nomi di metodi personalizzati comunemente utilizzati o utili. I designer delle API dovrebbero prendere in considerazione questi nomi prima di introdurne uno proprio 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. Consulta i dettagli nella descrizione dell'elenco.
Move :move POST Spostare una risorsa da un genitore all'altro, ad esempio folders.move.
Search :search GET Alternativa all'elenco per il recupero dei dati non conformi alla semantica dell'elenco, ad esempio services.search.
Undelete :undelete POST Ripristinare una risorsa eliminata in precedenza, ad esempio services.undelete. Il periodo di conservazione consigliato è di 30 giorni.