¿Objeto raíz o no? ¿Cuál es la mejor práctica para las respuestas API?

¿Cuál es la mejor práctica para los datos de respuesta de JSON, anidar el object dentro de un object padre e include el recorrido de la raíz de la raíz o no?

{ "activity": { "id": 20, "description": "a nice walk", "time_occurnetworking": "2013-07-15T22:10:23Z", "duration": 45, "distance": 4.24, "location":"McDonalds" } } 

O

 { "id": 20, "description": "a nice walk", "time_occurnetworking": "2013-07-15T22:10:23Z", "duration": 45, "distance": 4.24, "location":"McDonalds" } 

Parece que la mayoría de los frameworks HTTP (RestKit, GSON, etc.) pueden manejar cualquier caso, pero me encantaría tener una respuesta definitiva sobre qué enfoque es mejor y por qué. Siento que el primer enfoque es más descriptivo, que siempre es bueno, pero el segundo enfoque es más liviano y ya debería saber a qué object apuntar según la ruta url.

Nota: Estoy preguntando con reference específica a los backends de aplicaciones mobilees.

Parece que ambos lados tienen tracción.

A favor de los elementos raíz

De acuerdo con JSONAPI.org

Su key raíz DEBE ser la misma que la key raíz proporcionada en la respuesta del server a la request GET para la recostackción.

Por ejemplo, suponiendo la siguiente request para la recolección de fotos:

 GET /photos HTTP/1.1 200 OK Content-Type: application/json { "photos": [{ "id": "1", "title": "Mustaches on a Stick" }] } 

En favor de ningún elemento raíz

Twitter no cuando usa un object de configuration

 { "always_use_https": true, "discoverable_by_email": true, "geo_enabled": true, "language": "en", "protected": false, "screen_name": "theSeanCook", "show_all_inline_media": false, "sleep_time": { "enabled": false, "end_time": null, "start_time": null }, "time_zone": { "name": "Pacific Time (US & Canada)", "tzinfo_name": "America/Los_Angeles", "utc_offset": -28800 }, "trend_location": [ { "country": "United States", "countryCode": "US", "name": "Atlanta", "parentid": 23424977, "placeType": { "code": 7, "name": "Town" }, "url": "http://where.yahooapis.com/v1/place/2357024", "woeid": 2357024 } ], "use_cookie_personalization": true } 

Instagram usa una combinación de datos y metadatos, pero no usa un object de usuario raíz

 { "meta": { "code": 200 }, "data": { "username": "obama", "bio": "", "website": "", "profile_picture": "http://images.ak.instagram.com/profiles/anonymousUser.jpg", "full_name": "", "counts": { "media": 30, "followed_by": 113, "follows": 130 }, "id": "2082346" } } 

Cuando recibe un object de una fuente externa (o en cualquier otro lugar), todo es posible. Debe verificar el object para ver cómo y si puede utilizarlo.

Mantenlo simple.

La API de Twitter es más fácil de consumir que la de Facebook simplemente porque cuando obtiene un resultado, no tiene que anularlo casi tanto.

Considere este código:

Gorjeo:

 if (result.profile_image_url) { // use it } 

Vs. Facebook:

 if (result.data && result.data.picture && result.data.picture.url) { // use it } 

OMI, la mejor solución es clara. No hay nada malo con los objects raíz, pero su API debería hacerlo simple y fácil de consumir.

a) Clave raíz que describe el recurso / recolección

Esto tiene el beneficio de un context adicional en la respuesta. La key raíz describe el recurso o la colección. Personalmente, me gusta este enfoque porque es obvio lo que describe el documento de respuesta; puede argumentar que es obvio desde el punto final, pero este no siempre es el caso.

b) Sin key de raíz que describe el recurso / colección

Este enfoque es más común en la naturaleza. Las API que necesitan alta disponibilidad y rapidez a menudo eliminan los datos innecesarios del documento de respuesta para networkingucir la carga del server y el tamaño de la request. Esto es típico de las API populares que otros ven cuando diseñan las suyas, por lo que las emula para las API que no funcionan bajo las mismas condiciones.

No comprendo el argumento de que la falta de una key raíz hace que la respuesta sea más fácil de usar. Es una cantidad insignificante de esfuerzo para get datos de un object JSON nested en un nivel profundo.

c) La key raíz es "data"

Cuando se publicó esta pregunta, la especificación de la API de JSON todavía no había alcanzado la v1.0, lo que significa que es probable que se produzcan cambios de última hora. Si ve su especificación (estable) ahora, verá que su postura en la key raíz ha cambiado.

La propuesta para v1.0 Release Candidate 2 cambió la key de nivel superior a "data" .

Los resources primarios DEBEN aparecer ahora bajo la key de "data" nivel superior.

Tomemos por ejemplo este singular recurso

 { "data": { "type": "articles", "id": "1", "attributes": { "title": "The best article of all time", "author": "Kanye West" } } 

No pude encontrar la razón detrás de esto, pero sospecho que es por coinheritance. Sin importar el recurso, siempre se puede get datos de la respuesta del documento porque los miembros de nivel superior son consistentes, suponiendo que la API sigue la especificación JSON API v1.0.