Por qué usar API REST
Aprende qué son las APIs y por qué resultan tan importantes en la actualidad, por qué se usan cada vez más y...
Si tienes dudas sobre cómo deberían formatearse tus respuestas JSON, la especificación API JSON es una buena práctica. Te contamos todo sobre la misma.
Tabla de contenidos
La discusión sobre cómo formatear las respuestas JSON es algo muy habitual.
El cliente que consume esa API, es decir, la persona o la aplicación que consume esa API, y el servidor muchas veces tienen ciertas discrepancias sobre la forma de hacer la paginación de los resultados, las forma de presentar las referencias o las relaciones de una entidad con otra, sobre los datos de la referencia… en general sobre cómo formateamos ese tipo de respuesta.
Los puntos conflictivos o puntos dónde surgen las discrepancias son varios:
De todas estas discrepancias nace la especificación JSON API, que no es más que una forma de hacer las cosas. Posiblemente no sea ni peor ni mejor que otras especificaciones que se pueden realizar, pero sí que es cierto que tiene muchas ventajas, de las que destacamos algunas:
Si accedemos a la web de la propia especificación JSO API, podemos ver una breve descripción sobre la misma, y a continuación se nos muestra una respuesta a lo que sería una hipotética petición a un backend de artículos.
{
"links": {
"self": "http://example.com/articles",
"next": "http://example.com/articles?page[offset]=2",
"last": "http://example.com/articles?page[offset]=10"
},
"data": [{
"type": "articles",
"id": "1",
"attributes": {
"title": "JSON API paints my bikeshed!"
},
"relationships": {
"author": {
"links": {
"self": "http://example.com/articles/1/relationships/author",
"related": "http://example.com/articles/1/author"
},
"data": { "type": "people", "id": "9" }
},
"comments": {
"links": {
"self": "http://example.com/articles/1/relationships/comments",
"related": "http://example.com/articles/1/comments"
},
"data": [
{ "type": "comments", "id": "5" },
{ "type": "comments", "id": "12" }
]
}
},
"links": {
"self": "http://example.com/articles/1"
}
}],
"included": [{
"type": "people",
"id": "9",
"attributes": {
"first-name": "Dan",
"last-name": "Gebhardt",
"twitter": "dgeb"
},
"links": {
"self": "http://example.com/people/9"
}
}, {
"type": "comments",
"id": "5",
"attributes": {
"body": "First!"
},
"relationships": {
"author": {
"data": { "type": "people", "id": "2" }
}
},
"links": {
"self": "http://example.com/comments/5"
}
}, {
"type": "comments",
"id": "12",
"attributes": {
"body": "I like XML better"
},
"relationships": {
"author": {
"data": { "type": "people", "id": "9" }
}
},
"links": {
"self": "http://example.com/comments/12"
}
}]
}
Lo primero que vemos es que está enlazando links, es decir, el primer resultado es una serie de enlaces con los que poder continuar la exploración de contenido en base al contenido que se está mostrando.
Dentro de esos enlaces, en primer lugar aparece un enlace a sí mismo, después hay otro enlace a la siguiente página de listados de artículos y un enlace la última página.
El siguiente ítem es data, que es donde está incluida la propia información del artículo que estamos viendo. Es un elemento de tipo artículo con id 1, con una serie de atributos, que en este caso sólo tiene un título, pero todos los atributos que se quisieran mostrar vendrían listados aquí.
Además de esos atributos aparecen todas las relaciones. En este caso aparece el autor, y muestra el enlace para obtener más información sobre el autor de este contenido.
Además nos muestra que ese autor es una relación, que es con un elemento de tipo people, o sea, una persona, y con el identificador 9, por lo que si se quisiera más información sobre ese elemento, habría que hacer la petición.
Y también nos muestra los links para obtener los comentarios de este artículo, sobre los mismos son datos de tipo 5 y otro de tipo 12.
Así podríamos seguir con todas las relaciones que se muestran en el ejemplo.
Lo más importante de JSON API es que se encarga de definir una forma de dar salida a los datos de una forma más estándar, y que además solventa los problemas.
Para ahondar un poco más en cómo tiene que ser esa respuesta, en la web de la especificación pulsamos en el apartado Specification, dónde podemos ir navegando a través de la misma por sus apartados.
Podemos saber más sobre, por ejemplo, cómo obtener datos, cómo crear recursos o actualizar recursos, cómo es un objeto de tipo JSON API, etc., sobre la especificación actual, la 1.0, o la que está por venir, que es la 1.1.
También te puede interesar
Aprende qué son las APIs y por qué resultan tan importantes en la actualidad, por qué se usan cada vez más y...
Te contamos cómo exponer de manera muy rápida, tu contenido de Drupal 8 utilizando RESTful.
En este curso aprenderás todas las herramientas que contiene Drupal para crear servicios web basados en el protocolo...