Metodi personalizzati

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

Per metodi personalizzati si intendono i metodi API oltre ai cinque metodi standard. Loro deve essere utilizzato solo per funzionalità che non possono essere espresse facilmente con metodi standard. In generale, i progettisti di API devono scegliere i metodi standard rispetto a quelli personalizzati, se possibile. I metodi standard sono più semplici e una semantica ben definita con cui 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 meglio e supporta 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 e restituire una risposta arbitraria. supporta anche richieste e risposte di flussi di dati.

I nomi dei metodi personalizzati devono seguire 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 utilizzare : anziché / per separare il verbo personalizzato dal del nome della risorsa deve supportare percorsi arbitrari. Ad esempio, l'annullamento dell'eliminazione di un file può essere mappato a POST /files/a/long/file/name:undelete

Quando si sceglie il mapping HTTP, devono essere applicate le seguenti linee guida:

• I metodi personalizzati devono utilizzare il verbo HTTP POST poiché ha il semantica flessibile, ad eccezione dei metodi che fungono da get o list alternativo che possono utilizzare GET quando possibile. (vedi il terzo punto per le specifiche).
• I metodi personalizzati non devono utilizzare HTTP PATCH, ma possono utilizzare altri verbi HTTP. In questi casi, i metodi devono seguire lo standard semantica HTTP per quel verbo.
• In particolare, i metodi personalizzati che utilizzano HTTP GET devono essere idempotenti e non hanno effetti collaterali. Ad esempio, i metodi personalizzati che implementano le viste speciali della risorsa devono utilizzare HTTP GET.
• I campi dei messaggi di richiesta che ricevono il nome della risorsa o raccolta a cui è associato il metodo personalizzato deve essere mappato 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 una richiesta HTTP (questo si applica a POST, PUT, PATCH o a un verbo HTTP personalizzato), La configurazione HTTP del metodo personalizzato deve utilizzare body: "*" e tutti i restanti campi dei messaggi di richiesta dovranno mapparsi Corpo della richiesta HTTP.
• Se il verbo HTTP utilizzato per il metodo personalizzato non accetta un HTTP corpo della richiesta (GET, DELETE), la configurazione HTTP il metodo non deve utilizzare la clausola body e tutto il resto i campi dei messaggi di richiesta devono essere mappati ai parametri di ricerca dell'URL.

AVVISO: se un servizio implementa più API, il producer di API deve creare attentamente la configurazione del servizio per evitare conflitti con i 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 potrebbero essere la scelta giusta:

• Riavvia una macchina virtuale. Le alternative di progettazione potrebbero essere "crea una risorsa di riavvio in una raccolta di riavvii" che sembra complesso o "una macchina virtuale ha uno stato variabile che il client può aggiornare da IN ESECUZIONE a RIAVVIO" che domande aperte su quali altre transizioni di stato sono possibili. Inoltre, il riavvio è un concetto noto che può tradursi bene in un metodo personalizzato che soddisfi intuitivamente le aspettative degli sviluppatori.
• Invia email. La creazione di un messaggio email non deve necessariamente inviare (bozza). Rispetto all'alternativa progettuale (spostare un messaggio in "Posta in uscita" raccolta) ha il vantaggio di essere più rilevabili dall'utente dell'API e modella il concetto in modo più diretto.
• Promuovi un dipendente. Se implementato come standard update, il cliente dovrebbe replicare i criteri aziendali che disciplina il processo di promozione per garantire che si verifichi il livello corretto, nella stessa carriera e così via.
• Metodi batch. Per i metodi critici per le prestazioni, potrebbe essere utile fornire metodi batch personalizzati per ridurre il sovraccarico per richiesta. Ad esempio: accounts.locations.batchGet.

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

• Esegui query sulle risorse con parametri di ricerca diversi (utilizza list standard con il metodo standard di filtraggio degli elenchi).
• Semplice modifica delle proprietà della risorsa (utilizza il metodo update standard con maschera dei campi).
• Ignorare una notifica (utilizza il metodo delete standard).

Metodi personalizzati comuni

Di seguito è riportato l'elenco selezionato di nomi di metodi personalizzati di uso comune o utili. I progettisti di API devono prendere in considerazione questi nomi prima di introdurre per semplificare 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	Acquisizione collettiva di più risorse. Consulta i dettagli nella descrizione dell'elenco.
Move	:move	POST	Spostare una risorsa da una risorsa all'altra, ad esempio folders.move.
Search	:search	GET	Alternativa all'elenco per il recupero dei dati che non ottempera alla 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.