REST progettazione endpoint completamento automatico

Question

REST progettazione endpoint completamento automatico

#1 da (4 voti)
#2 da (2 voti)

4

Stiamo progettando un endpoint di riposo per la ripetizione dei suggerimenti di completamento automatico del nome per i nomi degli hotel.

Attualmente è definito in questo modo: GET /suggest/:term , in modo che se hai chiesto "/ suggerisci / hil" riceverai risposte come "Hilton Paris", "Hilton New York", ecc.

Uno dei nostri colleghi sostiene che ciò è contrario alle best practice di progettazione dell'API REST e che il termine di ricerca dovrebbe essere invece un parametro di query, ovvero /suggest?term=hilt .

Guardando attorno ad altre famose API, sembra che tutti usino un parametro di query:

link
link

ma mi piacerebbe sapere perché; se il primo è in realtà un cattivo design e quali linee guida mi porterebbero a renderlo un parametro di query in primo luogo.

rest

posta Zoltán 24.08.2015 - 15:02

fonte

2 risposte

Leggi altre domande sui tag rest

Come calcolare i valori min / max dei numeri in virgola mobile? Stima in gruppi - Come estrarre statistiche / stime utili?

score 4 · Answer 1

I servizi REST sono in genere focalizzati sulle risorse, con il separatore del percorso (barra diretta) che indica le risorse secondarie in una gerarchia. Le risorse sono in genere cose ("nomi" in inglese) piuttosto che azioni ("verbi" in inglese).

Per conformarsi a questo stile, il tuo endpoint "suggerisci" (un verbo) potrebbe essere chiamato "suggerimenti" (un nome) perché fornisce accesso ai suggerimenti. Solo a titolo di esempio, una sotto risorsa per i suggerimenti potrebbe essere un singolo suggerimento con URL come /suggest/Hilton%20New%20York in cui la risposta potrebbe essere un link all'attuale risorsa hotel "Hilton New York".

Azioni come "suggerire" sono tipicamente rappresentate tramite verbi HTTP, ad es. GET /suggestions/ .

Il "termine" è essenzialmente un filtro, che in genere viene trasmesso attraverso i parametri di query o nel corpo della richiesta. Un'implementazione più solida è descritta in questa risposta SO .

score 2 · Answer 2

Ci sono un paio di commenti che ti suggerirei.

Denomini la tua risorsa usando il verbo al posto dei nomi. suggest non è davvero un buon nome di risorsa. Dà al cliente l'idea che stai costruendo un'azione controller e a REST non piace. suggestions è un nome migliore. Ora puoi vederlo come una serie di risorse di suggerimenti che è più RESTful.
A partire dalla risorsa suggestions hai 2 modalità di visualizzazione dell'API.

a. Ogni serie di completamenti è una risorsa. In questo caso è possibile utilizzare l'endpoint: ./suggestions/hil. Quindi puoi vederlo come una singola risorsa che produce tutti i suggerimenti che iniziano con hil.

b. Ogni risorsa è un nome di hotel. In questo caso l'endpoint apparirebbe come un parametro di query. ./suggestions?begin-with=hil. Ciò ti consente di progettare in seguito un'API per aggiungere un nuovo nome di hotel. ( POST ./suggestions con il corpo appropriato). Il parametro Query ha una comprensione più chiara per il tuo cliente poiché rivela l'intenzione begin-with , contain , ...

La mia preferenza va a b) come puoi immaginare, ma ti lascio giudicare come preferisci. a) potrebbe avere qualche vantaggio in base al tuo caso d'uso.