Mi pregunta es sobre el diseño de un punto final para obtener una lista de elementos en una colección. Aquí, según tengo entendido, un GET en una colección devuelve una lista de los elementos de esa colección, pero no hay detalles sobre ellos.

Una lista de ID de recursos no es muy agradable para un ser humano, por lo que una interfaz gráfica de usuario solicitaría detalles de cada elemento de la colección.

Si la colección es, digamos, los "usuarios", entonces el GET en la colección solo devuelve una lista de ID de usuario (¡TODOS ELLOS! ¿Paginados, me imagino?)

Luego, la GUI solicita detalles para cada ID y los usa para completar una interfaz. Para obtener una lista, puede decir, como ejemplo, mostrar el nombre completo y la dirección de correo electrónico del usuario en esta interfaz, lo que permite al usuario seleccionar uno para ver más detalles.

Ahora estoy pensando que ahorraría mucho retroceso y avance entre el cliente y la API si la "recuperación de lista" devolviera un poco más que solo las ID, tal vez incluir ID, nombre completo y dirección de correo electrónico para cada elemento.

¿Eso rompe el DESCANSO? ¿Dónde se detiene con la cantidad de detalles que debe devolver en una sola solicitud? ¿Le permite al cliente especificar qué atributos incluir como parte de la solicitud?

¿Qué hay de "buscar" en una colección? ¿Permite que se especifiquen argumentos en el GET contra la colección para "filtrar" los resultados?

1
The Tahaan 3 ene. 2017 a las 15:28

1 respuesta

La mejor respuesta

La API existe para atender las necesidades de los clientes. Si sus clientes necesitan los detalles, debe devolverlos.

Dicho esto, existe una compensación para los elementos que se pueden almacenar en caché. Si la lista no es estática pero el contenido sí lo es, es mejor que le sirva devolver la lista de enlaces. Luego, el cliente realiza una llamada para cada elemento y se ubican en el caché. Las llamadas posteriores a esos elementos son atendidas por una caché intermedia, ya sea en el cliente o en algún lugar entre el cliente y el servidor. Eso reduciría el ancho de banda general de las llamadas a la lista a costa de una mayor cantidad absoluta de llamadas al principio.

Otra opción es admitir un parámetro de consulta como ?include=id, full-name, email. De forma predeterminada, solo devuelva el vínculo propio, pero los clientes pueden especificar qué propiedades les gustaría que aparecieran en las representaciones que obtienen. Si admite este parámetro de consulta, le sugiero que devuelva solo la información más esencial de forma predeterminada.

En cuanto a la búsqueda de la colección, depende de la naturaleza y complejidad de la búsqueda. Los parámetros de consulta son una opción. Usar POST para un punto final de búsqueda y enviar los criterios de búsqueda en el cuerpo también es razonable, especialmente si su URL puede tener más de 2k caracteres (el límite de longitud de URL predeterminado para algunos navegadores). También puede realizar búsquedas guardadas de esta manera: deje que POST cree un recurso de criterios de búsqueda en el servidor y deje que los clientes GET /widgets?search-criteria=<id>.

1
Eric Stein 3 ene. 2017 a las 17:55
Esto suena como una forma razonable de implementarlo y +1 para incluir el razonamiento, especialmente en torno a la capacidad de almacenamiento en caché.
 – 
The Tahaan
4 ene. 2017 a las 13:45