Qué especificación seguir para crear una API JSON

Discrepancias en las respuestas JSON

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:

• ¿Cómo formatear contenido?: ¿Qué datos devuelvo?, ¿cómo los devuelvo?, ¿qué hago con las imágenes?, ¿devuelvo siempre el link principal?
• ¿Cómo paginarlo?: ¿Cómo sabemos cuándo no hay más páginas?, ¿cómo sabemos cuándo hemos acabado un listado paginado de elementos?, ¿cómo construimos los links para acceder a la página anterior y a la página siguiente?
• ¿Cómo formatear contenido relacionado?: Todo lo referente al formato de las relaciones, por ejemplo, si un artículo lo ha hecho un usuario y obtenemos el artículo, ¿qué mostramos de su usuario?, ¿mostramos el nombre y el email?, ¿mostramos solo el identificador y obligamos a crear una segunda petición para obtener el usuario?

Ventajas de la especificación JSON API

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:

• Es “estándar”: En realidad no está escrito en ningún sitio que haya que usarse, pero es muy usada, por lo tanto si todo el mundo la utiliza, de cara a que cuando haya que cambiar de entorno o cambiar de aplicación, se conocerá perfectamente la estructura de esa otra aplicación y cómo funciona su API, porque funcionará de la misma forma mientras siga la misma especificación.
• Si definimos nuestra propia API sin seguir ninguna especificación, nos podemos encontrar problemas relacionados con cosas que no hemos planeado o que no hemos tenido en cuenta, y tener que resolverlos a posteriori. Por lo tanto, en general, esta especificación también nos ayuda a resolver problemas que aún no sabemos que existen.
• Esto nos ayuda a centrarnos en nuestra aplicación, en nuestra tu lógica de negocio y en cómo estructurar la arquitectura de nuestra información, y no en las cosas menos importantes, como puede ser el formateo de datos y las relaciones, ya que todo eso lo hacemos siguiendo el estándar.
• Además nos ahorrará una documentación extensiva sobre cómo funciona nuestra API, ya que al seguir la especificación, ya habrá alguien que lo haya escrito por ti.

Un vistazo a la especificación JSON API

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.

Conclusiones

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.