json - estandares - rest api tutorial español

¿Debería una respuesta RESTful GET devolver la ID de un recurso?

Question

Algunos de los desarrolladores aquí están teniendo una discusión amistosa (algunos dirían que es religiosa) sobre si una solicitud GET de una API RESTful debería devolver el ID del recurso solicitado . Asumamos la siguiente solicitud GET:

http://my.api.com/rest/users/23

Esto devuelve actualmente:

{"name": "Jim", "age": 40, "favoriteColor": "blue"}

Tenga en cuenta que falta "id" en el conjunto de resultados.

Hay básicamente 4 campos luchando con este problema.

CAMP # 1: Cuando las personas que llaman realizan la solicitud GET, ya conocen la ID. Por lo tanto, el conjunto de resultados no debe incluir el ID. Si las personas que llaman necesitan estos datos para habilitar la edición de UI, entonces las personas que llaman deben pasar por el ID 23, tal vez agregando el miembro {"id": 23} al JSON manualmente.
Las personas en el Campamento # 1 también argumentan que la presencia de la ID en el conjunto de resultados indicaría que este valor puede modificarse, lo que por supuesto no puede.

CAMP # 2: Sin el ID, el conjunto de resultados JSON no se puede usar de forma nativa para las operaciones de edición / actualización en los formularios de UI. En su lugar, el mecanismo de devolución de llamada AJAX debe ser responsable de pasar los campos de identificación y agregarlos manualmente al conjunto de resultados. Esto parece torpe y propenso a errores. Los individuos de la interfaz de usuario están argumentando que el conjunto de resultados "siente" que faltan datos que deberían estar presentes, es decir, la ID.

CAMPAMENTO # 3: Estas personas están preocupadas por la consistencia. Si alguna vez tenemos una colección de objetos de usuario devueltos por una API, estos objetos DEBEN incluir la ID. Por lo tanto, por coherencia, la versión singleton de un GET también debe incluir el ID.

CAMPAMENTO # 4: Estas personas están sugiriendo que la solicitud GET para un usuario podría devolver metadatos en la forma de HyperMedia o SelfLinks que incluiría la ID.

Esto no es un esotérico "¿Quién tiene razón?" argumento, tampoco. El enfoque que tomemos determinará la forma de nuestra API y afectará la carga de trabajo de varios desarrolladores en las próximas semanas.

Answer 1

Esta es una cuestión de opinión, que no es el tipo de pregunta que Stackoverflow le encanta ver. En cualquier caso, voy a ofrecer la mía.

Está devolviendo la representación del estado de un objeto o recurso. El ID es parte de esa representación y, por lo tanto, debe incluirse en el paquete JSON. Es una propiedad del recurso. Si la persona que llama conoce la identificación o no, no está particularmente relacionado con la discusión. El CAMP # 1 está en un terreno inestable.

El punto que plantea sobre las colecciones es muy relevante. ¿Tiene sentido usar una representación para la operación de recuperación-1 y otra representación para la operación de recuperación-N? Yo creo que no.

Sin embargo, el problema al que se enfrenta es más general: ¿qué datos deben incluirse en la representación que se transfiere a los clientes y en qué circunstancias? En algunos casos, a la persona que llama simplemente no le importa un subconjunto significativo de las propiedades. Especialmente en los escenarios en los que se recupera un gran conjunto de objetos, donde el costo de transmitir los datos es mayor en comparación con el costo de comunicación base, le gustaría optimizar lo que se envía.

Todos los protocolos REST suficientemente maduros tienen la capacidad de dar forma a los datos devueltos.

Para ejemplos, ver

• la API de Facebook Graph, http://developers.facebook.com/docs/reference/api/
• La API de StackExchange v2.0: hay un objeto de "filtro" que puede pasar para dar forma precisa a lo que se devuelve.
• CouchDb API: tiene una función de mapa para cada vista, que determina qué datos se devuelven. También tiene un parámetro de consulta general, include_docs , que dirige al servidor para que incluya objetos completos o solo metadatos. (En algunos casos, es posible que desee solo el recuento de los datos, no los datos reales).

Facebook te permite especificar explícitamente los campos que deseas.

La API de stackexchange es interesante. Han definido un tipo de objeto completamente nuevo para respaldar la conformación. Puede utilizar la API para definir un "filtro" y guardarlo en el lado del servidor. Luego, en su consulta, pasa un parámetro de filtro con el ID del filtro, y las representaciones de objeto devueltas incluyen todos los atributos especificados en el filtro. Sin filtro, se obtiene un subconjunto de campos "predeterminado". Para obtener "todos los campos" es necesario definir un filtro todo incluido.

Puede ver esto en acción en https://api.stackexchange.com/docs/answers

... y específicamente ver el diálogo de especificación del filtro.

No hay una sola manera correcta de hacer las cosas. Debe equilibrar la complejidad de la función de "configuración" que soporta con el costo de desarrollo y las necesidades de las aplicaciones que utilizarán la API.

Answer 2

Vieja pregunta, pero desde que llegué buscando algo, aquí va otra opinión:

En primer lugar, creo que la URL debería ser:

http://my.api.com/rest/Users/23

no

http://my.api.com/rest/getUsers/23

El "GET" se encuentra en el método HTTP, no en la URL. Es solo nombrar, pero ayuda a aclarar las cosas, IMHO.

Si piensa en esto, una modificación de recursos debe ocurrir en la misma URL con un PUT

PONGA http://my.api.com/rest/Users/23

En ese caso, el cliente debe realizar un seguimiento de las URL, no de las ID. No importa si el recurso devuelve un campo de ID. Depende del cliente mantener un mapa de dónde se obtuvo.

Si intenta PONER un recurso a una URL diferente, diga " http://my.api.com/rest/Users/24 ", se producirían algunos escenarios:

1) http://my.api.com/rest/Users/24 ya existe en el servidor y el servidor acepta el recurso como una actualización

2) http://my.api.com/rest/Users/24 no existe en el servidor y:

a) el servidor acepta que un usuario proporciona una identificación (24) a un recurso inexistente (no recomendado) b) el servidor acepta un PUT como POST

En a + b, el servidor crearía un nuevo recurso.

Asi que:

1) Dependiendo de cuánto confíe en su cliente, probablemente debería crear un control de "check-in / check-out" en el servidor para evitar sobrescribir un recurso con otro (¿está RESTful?)

2) No debe aceptar clientes que crean ID (está bien publicar http://my.api.com/rest/Users/ , no http://my.api.com/rest/Users/24 ) y no debe aceptar PONER a recursos no existentes.

EDITAR :

Así que creo que el recurso se identifica por su URL, no por el ID. O, en otras palabras, el ID de recurso es http://my.api.com/rest/Users/23 , no 23.

¿Tiene sentido?