Come progettare un'API REST con i criteri LIKE?

Question

Sto progettando un'API REST e hanno un soggetto per "gente":

GET http://localhost/api/people 

Restituisce un elenco di tutte le persone nel sistema

GET http://localhost/api/people/1 

Restituisce la persona con id 1.

GET http://localhost/api/people?forename=john&surname=smith 

Restituisce tutte le persone con nomi e cognomi corrispondenti, ma ho un ulteriore requisito. Qual è il modo più pulito/migliore per consentire ai consumatori delle API di recuperare tutte le persone il cui nome inizia con "jo", ad esempio.

Ho visto alcune API fanno questo tipo:

GET http://localhost/api/people?forename=jo~&surname=smith 

dove la tilde indica un match "fuzzy". D'altra parte, l'ho visto implementato con criteri completamente diversi, ad es.

GET http://localhost/api/people?forename-startswith=jo&surname=smith 

che sembra un po 'ingombrante considerando che potrei avere -endswith, -contains, -soundslike (per una sorta di partita soundex).

Qualcuno può suggerire per esperienza che funziona meglio e anche qualche esempio di API REST ben progettate che hanno funzionalità simili.

Answer 1

AFAIK, nessuno di sopra è abbastanza RESTful. Entrambi si basano su una conoscenza a priori sulla parte del client su come richiamare le query (nel primo caso, il modello di query e sul secondo una query DSL). Nel secondo esempio, infatti, l'API viene ridotta semplicemente a un wrapper attorno all'archivio dati. In quanto tale, l'API non definisce un dominio del server: è un fornitore di dati. Ciò è in contrasto con il vincolo del client-server di REST.

Se è necessario esporre un archivio dati completo con tutte le varie funzionalità di query, è meglio attenersi agli standard noti che abbiamo OData. OData è stato venduto come REST ma molte teste REST hanno problemi con esso. In ogni caso, alla fine della giornata funziona e le discussioni di REST possono comunemente portare alla paralisi dell'analisi.

Se facevo questo, probabilmente limiterei l'API a un caso d'uso comune, quindi qualcosa di più come il secondo senza definire una query DSL (quindi forenameStartsWith piuttosto che forename-startswith).

Detto questo, se è necessario eseguire una query in base a molti campi e varie condizioni, utilizzare OData.

Answer 2

Entrambi gli esempi utilizzano parametri di query per il filtro. Non penso che importi ciò che vengono chiamati questi parametri di query o se viene utilizzata una sintassi con caratteri jolly.

Entrambi gli approcci sono ugualmente RESTFul.

Answer 3

IMHO non importa se si dispone di corrispondenze fuzzy o di -endswith-contiene ecc. Ciò che conta è se l'API REST consente di analizzare facilmente tali parametri in modo da poter definire le funzioni per recuperare i dati dall'origine dati (DB o xml file ecc.)

Se si utilizza PHP ... dalla mia esperienza, SlimFramework è una soluzione leggera e facile da avviare.

Answer 4

Ti consiglio lo OData protocol che fornisce uno Query String Options. Quello che hai fatto è ok e segue le convenzioni REST.

Tuttavia, il protocollo OData descrive un parametro $expand e anche un parametro $filter. Questo $ prefisso denota "Opzioni query di sistema" e si sarà interessato a quello ultimo, perché permette di scrivere il seguente URI:

http://services.odata.org/Northwind/Northwind.svc/Customers?$filter=tolower(CompanyName) eq 'foobar' &select=FirstName,LastName&$orderby=Name desc 

Esso consente di passare SQL come i dati, può essere una bella alternativa a quello che hai descritto (entrambe le soluzioni vanno bene, è solo questione di gusti).