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

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

GET / 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 el nuevo API de tareas de Google simplemente documenta todos los parámetros de consulta en la guía de referencia. Documentaré la lista, pero también me gustaría hacerlo con HATEOAS.

Gracias de antemano!

preguntado el 16 de mayo de 11 a las 19:05

Ojalá pudiera hacer +10 en esta pregunta. -

3 Respuestas

Usando la sintaxis descrita en el borrador actual del Especificaciones de la plantilla de URI tu harías:

/users{?surname,maxresults}

contestado el 02 de mayo de 14 a las 16:05

La especificación de la plantilla URI parece muy útil. - Paul Sonier

La otra opción es usar un formulario html:

<form method="get" action="/es/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 se puede anotar con cualquier documentación adicional que desee colocar allí.

contestado el 17 de mayo de 11 a las 04:05

Tal vez me estoy perdiendo el punto, pero esto no funcionará si su recurso no es HTML. - Mark E. Haase

Este formulario html es una forma de formular la solicitud GET, lo que obtiene es en cualquier formato de tipo de medio que solicitó en ... podría ser (y probablemente sería) algo completamente diferente. - HDave

No soy un experto en REST, pero déjame agregar mis 2 ¢:

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

  1. Defina un tipo de medio para las descripciones de búsqueda, digamos application/prs.example.searchdescription+json (pero tome nota del 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 mediante la vinculación a ese sub-recurso desde otro lugar. Por ejemplo, digamos que el cliente ha solicitado GET /users. Podría recibir algo como esto:

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

El cliente puede seguir ese enlace y POST una especificación de búsqueda para ese recurso URI, por ejemplo:

POST /users/search
…
Content-Type: application/prs.example.search-definition+json
…

{ criteria: { surname: "Harvey" }, maxResults: 25 }

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

A una solicitud como se describe anteriormente, el servidor podría responder con un 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" } ] }

Luego, el cliente puede navegar al URI con el results relación para obtener los resultados de la búsqueda, sin tener que ensamblar un URI.

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

Respondido 13 Jul 16, 17:07

No es la respuesta que estás buscando? Examinar otras preguntas etiquetadas or haz tu propia pregunta.