web-services - specifically - spring hal

¿Cómo puedo usar HATEOAS y los parámetros de consulta para la búsqueda RESTful?

Question

Me gustaría diseñar un URI de búsqueda RESTful utilizando parámetros de consulta. Por ejemplo, este URI devuelve una lista de todos los usuarios:

OBTENER / usuarios

Y los primeros 25 usuarios con el apellido "Harvey":

GET / users? Surname = Harvey & maxResults = 25

¿Cómo puedo usar hipermedia para describir qué parámetros de consulta están permitidos por el recurso "/ users"? Noté que la nueva API de Google Tasks solo documenta todos los parámetros de consulta en la guía de referencia. Documentaré la lista, pero me gustaría hacerlo también con HATEOAS.

¡Gracias de antemano!

Answer 1

La otra opción es usar un formulario html:

<form method="get" action="/users">
<label for="surname">Surname: </label>
<input type="text" name="surname"/>
<label for="maxresults">Max Results: </label>
<input type="text" name="maxresults" value="25"/> <!-- default is 25 -->
<input type="submit" name="submitbutton" value="submit"/>
</form>

Un formulario como este documenta completamente las opciones disponibles y los valores predeterminados, crea la URL especificada y puede anotarse con cualquier documentación adicional que desee colocar allí.

Answer 2

No soy un experto en REST, pero permítanme agregar mis 2 ¢:

En la Web humana, los formularios HTML a menudo se utilizan para construir un URI a una representación de los resultados de búsqueda. El problema es que la web programable no tiene formularios. Pero podría definir fácilmente algo análogo a usted mismo, es decir:

1. Defina un tipo de medio para las descripciones de búsqueda, digamos application/prs.example.searchdescription+json (pero tome nota de la PS al final de esta respuesta);

2. Exponer un sub-recurso que representa una búsqueda de usuarios, /users/search .

El segundo paso se lograría al vincular a ese sub-recurso desde otro lugar. Por ejemplo, digamos que el cliente ha solicitado GET /users . Puede recibir algo como esto:

{ _links: [ …, { rel: "search", href: "/users/search" }, …] }

El cliente podría seguir ese enlace y POST una especificación de búsqueda a ese URI de recursos, por ejemplo:

POST /users/search
…
Content-Type: application/prs.example.search-definition+json
…
{ criteria: { surname: "Harvey" }, maxResults: 25 }

Aquí, los criteria contienen una representación (parcial) de los objetos que se encuentran. Esto podría convertirse en una descripción arbitrariamente compleja.

A una solicitud como la descrita anteriormente, el servidor puede responder con el código de estado 200 OK y, en el cuerpo de la entidad, un enlace a un recurso que representa los resultados de la búsqueda publicada:

{ _links: [ { rel: "results", href: "/users?surname=Harvey&maxResults=25" } ] }

El cliente puede navegar hasta el URI con la relación de results para obtener los resultados de la búsqueda, sin haber tenido que ensamblar un URI.

PD : Cuando originalmente escribí esto, aún no me había dado cuenta de que definir nuevos tipos de medios todo el tiempo puede volverse problemático. Mark Nottingham blogueó sobre la "proliferación de medios de comunicación" y cómo combatirla haciendo uso de la relación de enlace de profile .

Answer 3

Usando la sintaxis descrita en el borrador actual de la especificación de la plantilla URI, usted haría:

/users{?surname,maxresults}