Una especificación para construir API's

Ma boys 'n girls, hoy les quiero hablar de nuestro Elohim, perdón canal equivocado, quiero escribir sobre la especificación JSON:API. 

¿Qué es JSON:API Spec?

Es una especificación de cómo un cliente debe solicitar que se busquen o modifiquen recursos, y cómo un servidor debe responder a estas peticiones. Esto con el fin de mantener un estándar. 

Pero, ¿Por qué utilizarlo?

Empecemos por un caso que estoy viviendo en mi trabajo actual, es un caos, como hay servicios que aún se están desarrollando, la respuesta no mantiene la estructura, no hay un estándar, el front no sabe que esperar, todo lo malo es un 400 y todo lo bueno es un 200.

Aquí van algunos puntos de por qué la vida sería más fácil al usar esta especificación.

• Convención
  • Al tener reglas preestablecidas, tanto front como back se pueden desarrollar en paralelo. Ya que estamos seguros de que formato tendrán las peticiones y las respuestas.
• Eficacia en el desarrollo
  • Al no tener que crear tu propia convención, solo queda enfocarse en la lógica de negocio.
• Herramientas
  • Existen muchas que nos facilitan el adherirnos a la especificación tanto para consumir como para crear. Aquí  puedes checar las implementaciones en diferentes lenguajes y frameworks.

Todo esto ayuda a tener buenas prácticas y claro un software de mejor calidad.

Pero bueno, dejemos de tanto dato duro, y veamos la estructura de un documento. Como documento sabe' que me refiero al cuerpo de una petición o respuesta no? 😜

Tanto el API con el cliente debe ignorar cualquier otro miembro que no se contemplen aquí. Sin embargo esto no quiere decir que siempre deban existir todas estas llaves en el documento.

Esto es bastante claro, si la respuesta es correcta se devuelve 'data', si por el contrario contienen errores entonces traerá 'errors', pero nunca ambas al mismo tiempo. 

El miembro 'meta', básicamente es para cualquier información adicional que deseemos incluir.
'jsonapi' es un objeto que contiene la versión del API, si no se envía se asume que es la versión es la 1.0

Aún queda explicar el resto de llaves, y profundizar en data, ya que este es el miembro más importante por que contiene la información principal del documento. Y otros detalles, pero para no extenderme más lo escribiré en un segundo y posible tercer post. 

Si ustedes son impacientes lean la especificación JSON:API y comenten sus experiencias si ya han usado esta o las complicaciones que han vivido al no usar algún estándar.

~Happy Coding