Hacia un Drupal desacoplado (JSONApi + OpenAPI)

Cadenas rotas

Desacoplar Drupal básicamente es la práctica por la que separamos la gestión del contenido, es decir, la creación, modificación y versionado del contenido; de la representación del mismo. Esto nos permite que un mismo contenido sirva para cualquier canal de comunicación sin necesidad de romperse la cabeza con un frontend monolítico.

El objetivo es exponer un API que pueda ser consumido por diversos frontends sin necesidad de alterar el contenido. Como ya hemos visto en otros artículos:

/pequena-version-movil-con-jquery-mobile

Es posible exponer el contenido del sitio en forma de API REST mediante los servicios de Drupal, pero si realmente queremos empezar a trabajar de forma desacoplada, siempre es mejor abrazar estándares en lugar de hacer la guerra por nuestra cuenta. Hay dos estándares que merece la pena seguir:

  • JSON:API que nos permite unificar las API entorno a un estandar que indica cómo debe realizar el cliente las peticiones y cómo han de ser las repuestas del servidor.
  • OpenAPI que nos permite unificar como describimos y documentamos las API

Afortunadamente, en Drupal disponemos de módulos para conseguirlo, de tal manera que podemos convertir nuestro desaguisado en un API ordenada siguiendo unos pequeños pasos:

JSONAPI

Drupal dispone de dos módulos para implementar nuestro nuevo API de manera 100% acorde al estándar:

  • JsonAPI.- Incluye las funcionalidades necesarias para que nuestro sitio exponga un API 100% compatible con el estándar.
  • JsonAPI extras.- Permite configurar qué entidades y qué campos de la entidad expondremos en nuestro API

Realizaremos la instalación según tengamos instalado nuestro sitio (Composer o a capón), en el momento de escribir este artículo está implementada la versión 2.0 del estándar, para que no nos de guerra tendremos que instalar la última versión de ambos módulos.

Json API no proporciona ninguna página para saber qué está pasando, por lo que la única forma de comprobar que el módulo funciona correctamente es haciendo una llamada a algún endpoint del API, por ejemplo:

Ejemplo de respuesta OpenAPI

Json API Extras nos proporciona un UI con el que podremos configurar qué puntos están disponibles y qué campos tenemos disponibles:

Pantalla de configuración de Json API Extras

Además de poder elegir qué endpoints están activados, podremos cambiar la ruta, elegir los campos y además alterar la respuesta del campo con formateadores:

Configuración de JSON API Extras

 

OPENAPI

Una vez que tenemos una API publicada en nuestro sitio (no es imprescindible que sea mediante JsonAPI), es importante poder compartir las especificaciones con otros, para ello, existe una iniciativa que pretende estandarizar la forma en la que se describen las API. Esta estandarización nos permite poder usar las especificaciones en distintos entornos, en visores creados para la consulta de estas API, o mover las especificaciones a otros sistemas (por ejemplo Amazon AWS).

En Drupal existen módulos para implementar las especificaciones de OpenAPI:

  • OpenAPI.- Incluye las funcionalidades necesarias para generar la especificación partiendo de APIs existentes.
  • OpenAPI UI.- Genera las funcionalidades necesarias para integrar nuevos plugins que nos permiten explorar la especificación mediante un visor como Swagger o Redoc.

Una vez se haya instalado el módulo, tendremos una nueva página de configuración en:

Administración > Configuración > Servicios Web > OpenAPI Downloads

Descargas de OpenAPI

Si navegamos a cualquiera de las descargas disponibles, obtendremos la especificación de nuestro API:

Especificación Swagger OpenAPI

Como ya dijimos, es posible mostrar esta implementación en un visor como Swagger o Redoc, para ello, solo tenemos que instalar OpenAPI UI y elegir uno de los módulos disponibles:

En el momento de escribir este artículo, ReDoc funciona mejor, por lo que lo recomendamos como primera opción, una vez instalado el visor, podemos acceder a nuestra nueva documentación usando la estructura:

admin/config/services/openapi/<visor>/<api>

En nuestro caso, instalamos redoc para ver nuestra jsonapi luego:

admin/config/services/openapi/redoc/jsonapi

Visor Redoc para OpenAPI

Con esto, ya tenemos un API estándar definido bajo el estandar OpenAPI y con un cómodo visor para su consulta, lo que nos facilitará enormemente el desarrollo de aplicaciones que consuman dichas APIs.

En próximos artículos veremos cómo consumir las APIs desde un frontend, como usar autenticación en nuestro API o como mejorar el enrutado para aplicaciones de mayor tamaño.

Tags