Este cuarto y último artículo hace un breve resumen sobre los distintos estándares aplicados en el diseño de una API HTTP para el intercambio de información.
Simple Response
Uno de los objetivos de nuestra API es responder con información que entienda el consumidor. Muchas veces, solo nos bastará con responder con solo el recurso solicitado o una matriz de recursos solicitados. Sin embargo, también hay metadatos que queremos proporcionar a nuestros consumidores. Una alternativa es usar los HTTP Headers, los cuales son usados para proporcionar metadatos, pero por lo general no es lo suficientemente potente como para transmitir todo lo que el consumidor necesita saber del recurso.
Unos de los casos que se dan muy a menudo, son los mensajes de error que debemos proporcionar al consumidor de nuestra API. Si bien, podemos suministrar un código de estado 4XX o 5XX cuando falla una solicitud, pero ¿Cómo podemos ser más específicos?¿Cómo hacemos para que nuestro cliente sepa si una solicitud es un error y cómo obtener mayor información del error?.
Ante este escenario, podemos responder con un objeto principal a los datos reales (en del HTTP Response). Nos referimos a responder con un objeto JSON estandarizado como un “sobre” (respuesta simple), ya que envuelve los datos importantes. Por ejemplo:
| { | |
| «error«: «redis_connection_failed«, | |
| «error_description«: «No se puede establecer una conexión al servidor redis«, | |
| «data«: null | |
| } |
En el ejemplo, se observa dos propiedades de error. El primero, “error“, es un código de error analizable por una aplicación (consumidor). Hay APIs que optan por usar valores numéricos en vez de un valor de cadena, pero ¿por qué usar un formato numérico ilegible cuando lo tratan como una cadena? También queremos una cadena separada legible por humanos, como por ejemplo la propiedad “error_description“. Esta cadena podría traducirse teóricamente para coincidir con el Accept-Language del Request y mostrarle a un usuario final.
Si la respuesta (HTTP Response) fuera exitosa, podemos agregar propiedades adicionales como estas:
| { | |
| «error«: null, | |
| «error_description«: null, | |
| «data«: [{«id«: «10000«,«name«:«Gonzalo Chacaltana Buleje«}, {«id«: «10001«,«name«:«Carlos Vargas«}], | |
| «offset«: 10, | |
| «per_page«: 10 | |
| } |
En este caso, todavía tenemos la propiedad de “error” y “error_description“, pero dado que no hay un error, lo configuramos en nulo (null). La propiedad “data” contiene el contenido solicitado por el consumidor, en este caso, el consumidor solicita una recopilación de datos (por ejemplo: estudiantes), por lo que proporcionamos una serie de recursos en esa colección (id y name). Finalmente tenemos dos propiedades de metadatos adicionales, “offset” y “per_page“, que le informa al consumidor sobre la respuesta. En este caso, el cliente ha solicitado la segunda página de resultados con 10 entradas por página, por lo que básicamente respondemos con esos datos para el contexto.
JSON API
API JSON es un estándar para el intercambio de información entre aplicaciones, que recomienda buenas prácticas para eliminar redundancias de datos, a la hora de devolver información a nuestros consumidores. Por citar un ejemplo, tenemos una API que representa a una colección de libros de una reconocida cadena de librerías. Cada libro tendrá un contenido único, es decir, tendrá un título, un código (identificador) y un precio. Sin embargo, cada libro tendrá información potencialmente redundante, como la información del autor.
Por lo general, ante estas situaciones, una API devuelve la información del autor de forma redundante por cada libro. Es probable que existan muchos libros cuyo autor es el mismo, por lo tanto, estaríamos enviando un montón de contenido al consumidor. El estándar API JSONnos permite, en cambio, definir relaciones entre diferentes tipos de recursos, eliminando así las redundancias. Mira el siguiente ejemplo:
| { | |
| «data«: [ | |
| { | |
| «type«: «books«, | |
| «isbn«: «978-1788473699«, | |
| «attributes«: { | |
| «title«: «Mastering Android Development with Kotlin«, | |
| «price«: 39.99 | |
| }, | |
| «relationships«: { | |
| «author«: { | |
| «data«: { | |
| «id«: «9823« | |
| } | |
| } | |
| } | |
| } | |
| ], | |
| «included«: [ | |
| { | |
| «id«: «9823«, | |
| «attributes«: { | |
| «name«: «Milos Vasic«, | |
| «country«: «Servia« | |
| } | |
| } | |
| ] | |
| } |
GraphQL
GraphQL es un estándar API desarrollado por Facebook. Incluye un formato personalizado para consultar datos. Normalmente, las respuestas se envían en formato JSON. El formato de consulta requiere que el consumidor especifique todos los atributos que desea en la respuesta. Esto nació de la necesidad de que las aplicaciones clientes móviles obtengan solo datos importantes, desperdiciando menos bytes en la transferencia de información.
Otra característica de GraphQL es que los atributos solicitados en la respuesta pueden correlacionarse con datos de diferentes colecciones. Esto hace que GraphQL sea particularmente atractivo cuando se construyen componentes estructurales (facades), servicios que consumen datos de otros servicios. GraphQL puede realizar las agregaciones necesarias en una única solicitud (HTTP Request), evitando que el cliente tenga que realizar múltiples solicitudes a diferentes colecciones.
Las solicitudes generalmente usan un endpoint HTTP único, con el cuerpo recibido a través de POST. GraphQL NO es una práctica RESTful de HTTP, y en realidad se puede usar completamente por separado de HTTP. Este es un ejemplo de una consulta GraphQL:
| { | |
| user(user_account: «@gchacaltanab») { | |
| user_account | |
| name | |
| photo { | |
| id | |
| url | |
| } | |
| tweets { | |
| id | |
| url | |
| } | |
| } | |
| } |
Este es un ejemplo de la respuesta correlacionada (HTTP Response):
| { | |
| «data«: { | |
| «user«: { | |
| «name«: «Gonzalo Chacaltana«, | |
| «user_account«: «@gchacaltanab«, | |
| «photo«: { «id«: «607430054361088000«, «url«: «https://pbs.twimg.com/profile_images/607430054361088000/zl59othh_400x400.jpg« }, | |
| «tweets«: [ | |
| {«id«: «888191162707828736«, «url«: «https://twitter.com/gchacaltanab/status/888191162707828736«} | |
| ] | |
| } | |
| } | |
| } |
MessagePack
MessagePack se puede considerar como una representación binaria 1:1 de JSON. Cualquier documento JSON se puede representar como MessagePack, lo que significa que se puede usar con API JSON o GraphQL. Se elimina cualquier espacio en blanco superfluo y también se eliminan algunas otras redundancias, como los caracteres de comillas y dos puntos. La representación binaria suele ser más pequeña y puede ser más rápida de serializar y deserializar.
Observa el siguiente documento. Este archivo tiene 109 bytes (sin contar espacios en blanco). Es un objeto con tres propiedades, la primera es un identificador, la segunda una cadena y la tercera una matriz de dos valores numéricos:
| { | |
| «id«: «1090932876765«, | |
| «place_name«: «Movistar Tienda Miraflores«, | |
| «xy«: [-12.1245631, -77.0283029] | |
| } |
El siguiente es el mismo contenido del archivo anterior, pero en formato MessagePack reducido a 78 bytes (72% del anterior).
| 83 a2 69 64 ad 31 30 39 30 39 33 32 38 37 36 37 36 35 aa 70 6c 61 63 65 5f | |
| 6e 61 6d 65 ba 4d 6f 76 69 73 74 61 72 20 54 69 65 6e 64 61 20 4d 69 72 61 | |
| 66 6c 6f 72 65 73 a2 78 79 92 cb c0 28 3f c6 bc 11 93 a6 cb c0 53 41 cf b6 | |
| f7 78 72 |
JSON RPC (Remote Procedure Call)
JSON RPC es un paradigma muy diferente del HTTP RESTful que hemos estado viendo en todas estas publicaciones. En lugar de abstraer los datos en recursos y realizar operaciones CRUD en ellos, simplemente puede exponer las funciones y sus parámetros y permitir que los clientes llamen a estas funciones semi-directamente. Este patrón se llama RPC. JSON RPC es entonces
De forma similar a GraphQL, si usa estas solicitudes a través de HTTP, probablemente use un endpoint único, acepte las solicitudes a través de una solicitud POST y responda. JSON RPCtambién puede funcionar completamente fuera de HTTP, por ejemplo con TCP o IPC (Inter-Process Communications).
Aquí hay un ejemplo de una solicitud JSON RPC. El documento es muy simple; la solicitud requiere un número de versión (propiedad “jsonrpc“), un identificador (para correlacionar los request con los response, ya que no estamos casados con HTTP). También nombramos el método RPC (propiedad “method“) que queremos ejecutar y proporcionamos argumentos en la propiedad “params”. Los parametros pueden ser una matriz o un objeto, correlacionando a parámetros de función normal o parámetros nombrados, respectivamente.
| { | |
| «jsonrpc«:«2.0«, | |
| «method«:«suma«, | |
| «params«:[16,29], | |
| «id«:1000 | |
| } |
La respuesta (HTTP Response) también contiene una versión y un identificador correspondiente a la solicitud (HTTP Request). La propiedad importante es “result” que contiene el resultado de la operación.
| { | |
| «jsonrpc«: «2.0«, | |
| «result«: 45, | |
| «id«: 1000 | |
| } |
Te esperamos en los próximos artículos en donde hablaremos mas acerca de estos temas que hoy en día son de importancia e interés en el mundo de la tecnología.
