"El buen diseño es obvio. El gran diseño es transparente"
- Joe Sparano

Hypermedia REST

4 minutos de lectura
Fecha: 20/3/2019

Hypermedia REST es una manera de enfocar nuestras API REST. Actualmente existe un gran debate acerca cual es la mejor manera de construir una API.

Entre las distintas tecnologías que existen podemos destacar SOAP y REST como las más conocidas tradicionalmente. Y posiblemente GraphQL como la especificación moderna mas prometedora. De hecho si quieres saber más acerca de GraphQL puedes visitar este post que publiqué hace ya tiempo…

Sin embargo a día de hoy REST es sin duda el rey. Y entrando de lleno detalles de implementación que podemos aplicarle Hypermedia es tremendamente interesante.

De hecho la mayoría de las «innovaciones y ventajas» que tratan de vendernos por ejemplo con GraphQL también son propias de una API Hypermedia REST.

Obviamente esto no quiere decir que debas escoger una tecnología u otra, pero esta bien tener el contexto de cuales existen y que nos ofrecen y hoy quiero hablar de Hypermedia REST.

¿Qué es Hypermedia REST?

Hypermedia es una manera de implementar nuestras APIS pero es mucho más. Cuando hablamos de Hypermedia estamos haciendo referencia a una serie de controles y métodos para que el contenido soporte recursos como audio, video otros textos, etc. Y que además el usuario pueda interactuar con esto.

El caso más conocido en el mundo web son los hipervínculos, que nos permiten enriquecer nuestro contenido con enlaces.

Y precisamente por ahí van los tiros cuando hablamos de aplicarlo a una API REST. En resumen Hypermedia REST es utilizar la base de REST pero enriqueciéndola con métodos como estos.

Una de las peculiaridades que tiene una API Hypermedia REST es que tiene un único punto de entrada. En este aspecto es igual que lo que propone GraphQL.

Esto tiene cierta lógica, si tu quieres entrar en mi web tienes que escribir en el navegador la url de entrada (https://www.oscarlijo.com), si después quieres llegar hasta el blog tienes un link que te envía a https://www.oscarlijo.com/blog y si quieres ir a una entrada concreta tienes dentro del blog otro link que será https://www.oscarlijo.com/blog/lo-que-sea.

Hypermedia REST sigue la misma filosofía que una web, te da una url de entrada, luego allí publica entre otras cosas, los links para que podamos ir navegando y consumiendo, en este caso, otros endpoints usando los verbos REST.

Claro navegar por una API suena mas abstracto que por una web. Donde contamos con un navegador y vamos interactuando de forma visual. Pero no es algo tan complicado.

Tratemos de pensar en que ese punto de entrada es como el índice de una enciclopedia.

Cuando queremos buscar información de algo en vez de recorrer todas las páginas de la enciclopedia, consultamos el término en el índice, en el se registra la página o la dirección a la que debemos ir o navegar para encontrar la información.

Aquí lo normal es que busquemos en esta url de entrada el recurso con el que queremos trabajar (hacer alguna operación CRUD) y lo que se nos va a devolver es el endpoint donde esta alojado y posiblemente también el verbo que debemos usar en el caso de que lo que estemos listado sean acciones.

Como cada vez que queremos hacer uso de algún recurso acabamos en la url de entrada seguramente decidamos cachear el contenido que en ella se expone e irlo refrescando cada cierto tiempo para directamente tener en memoria este ‘índice’.

Comenzando con Hypermedia

Obviamente, aunque un antes he hablado de que con hypermedia tenemos un endpoint de entrada, no penséis que eso es palabra de Dios. Realmente hypermedia es usar las uris para develar en nuestra API las acciones que podemos realizar.

Nada impide que vayamos poco a poco, si ya tenemos nuestra API podemos comenzar a aplicarlo por ejemplo en un endpoint concreto.

El ejemplo que veo mas a menudo para ‘iniciarse’ en esto es el de las tablas paginadas en servidor. Sería algo así..

[
    {
        "contextUri": "https://api.example.com/things",
        "contextPointer": "",
        "rel": "self",
        "targetUri": "https://api.example.com/things?offset=20,limit=2",
        "attachmentPointer": ""
    }, {
        "contextUri": "https://api.example.com/things",
        "contextPointer": "",
        "rel": "next",
        "targetUri": "https://api.example.com/things?offset=22,limit=2",
        "attachmentPointer": ""
    }
]

Este es un ejemplo muy simple de la página de json-schema.org que refleja como se puede implementar. Como se observa en el JSON tenemos tanto una referencia a la página actual como a la siguiente. En ambas uno esta el campo targetUri que nos proporciona el endpoint donde consultarlo.

Especificaciones

Existen muchas maneras de implementar una API Hypermedia REST. Si deseas investigar un poco mas puedes buscar alguna de estas especificaciones:

Si por ejemplo buscamos un esquema de como funciona alguna de estas implementaciones, veremos esto.

Descripción de la imagen

Esquema tipo HAL

Como se aprecia la respuesta de la API no solo incluye las propiedades del recurso que solicitamos, sino también los links.

Por ejemplo si pidiéramos como recurso este post. En las propiedades esta la información asociada a él como su título, contenido, fecha de publicación, categoría… Pero también tendríamos links a información complementaria o acciones.

Información complementaria podría ser la información del autor/es que obviamente es otra entidad. Las acciones podrían ser las de navegar al siguiente post o al anterior. Todo se expresaría mediante links

Aunque yo intente explicar más o menos lo que es Hypermedia REST, está claro que para aprender de verdad lo mejor es que consultéis los enlaces de arriba.

Allí tenéis muchos ejemplo muy bien pensados. Y aunque cada uno lo implementa siguiendo unas normas concretas, en todos se ve la esencia de como sacarle partido a esta técnica.

Secciones