¿Cómo diseñar una API REST con los criterios LIKE?

Question

Estoy diseñando una API REST y tienen una entidad de "Personas":

GET http://localhost/api/people 

devuelve una lista de todas las personas en el sistema

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

Devuelve la persona con id 1.

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

Devuelve todas las personas con nombres y apellidos coincidentes, pero tengo un requisito adicional. ¿Cuál es la forma más limpia/de mejores prácticas de permitir que los consumidores de la API recuperen a todas las personas cuyo nombre de pila comienza con "jo", por ejemplo?

que he visto algunas API hacen esto como:

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

donde la tilde, significa un "fuzzy". Por otro lado, lo he visto implementado con un criterio totalmente diferente, por ej.

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

que parece un poco complicado teniendo en cuenta que podría tener -endswith, -Contiene, -soundslike (por algún tipo de partido soundex).

¿Alguien puede sugerir por la experiencia que funciona mejor y también cualquier ejemplo de API REST bien diseñadas que tengan una funcionalidad similar.

Answer 1

AFAIK, ninguno de los anteriores es bastante RESTful. Ambos confían en un conocimiento previo por parte del cliente sobre cómo invocar consultas (en el primer caso, patrón de consulta y en el segundo una consulta DSL). En el segundo ejemplo, de hecho, la API se reduce a un envoltorio alrededor del almacén de datos. Como tal, API no define un dominio de servidor, es un proveedor de datos. Esto está en contraste con la restricción cliente-servidor de REST.

Si necesita exponer un almacén de datos en toda regla con todas las diversas capacidades de consulta, es mejor que se adhiera a los estándares conocidos que tenemos OData. OData se ha vendido como REST pero muchos REST-heads tienen problemas con él. De todos modos, al final del día funciona y las discusiones de REST pueden conducir a análisis-parálisis.

Si estuviera haciendo esto, probablemente restringiría la API a un caso de uso común, entonces algo más parecido al segundo sin definir una consulta DSL (de ahí forenameStartsWith rather than forename-startswith).

Habiendo dicho eso, si necesita hacer una consulta basada en muchos campos y varias condiciones, usaría OData.

Answer 2

Ambos ejemplos usan parámetros de consulta para el filtrado. No creo que importe cómo se llaman estos parámetros de consulta o si se usa alguna sintaxis de comodín.

Ambos enfoques son igualmente RESTFul.

Answer 3

En mi humilde opinión, no importa si tiene coincidencias difusas o tiene -contiene-contiene etc. Lo que importa es si su API REST permite un análisis sencillo de dichos parámetros para que pueda definir funciones para obtener datos de su fuente de datos (DB o archivo xml, etc.) en consecuencia

Si está utilizando PHP ... según mi experiencia, SlimFramework es una solución ligera, fácil de iniciar.

Answer 4

Yo le recomendaría el OData protocol que proporciona un Query String Options. Lo que hiciste está bien y sigue las convenciones REST.

Pero, el protocolo OData describe un parámetro $expand e incluso un parámetro $filter. Este $ prefijo denota "Opciones de consulta del sistema" y usted estará interesado en el último, ya que le permite escribir el URI siguiente:

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

Se le permite pasar de SQL como de datos, puede ser una buena alternativa a lo que describiste (ambas soluciones están bien, es solo cuestión de gusto).