Acceder al contenido principal

API desde cero con Drupal 9

Volver a Blog

API desde cero con Drupal 9

28 Jul 021
background api drupal
avatar-jose-carlos-raya

API , Drupal ,

Bienvenidos una vez más. En esta ocasión veremos cómo podemos aprovechar Drupal como backend para crear una API REST que más tarde pueda consumirse de forma propia o por terceros. Antes de nada vamos a ver un par de conceptos de qué es una API y qué beneficios tiene.

¿Qué es una API REST?

Es un recurso que pone a disposición los datos de una o varias entidades en formato XML o JSON para poder reusarlos en la misma aplicación que los sirve o en otras como por ejemplo aplicaciones móviles. Para que una API pueda llamarse REST tienen que cumplirse una serie de condiciones:

  • Protocolo cliente/servidor sin estado.
  • Sistema de capas.
  • Interfaz uniforme.
  • Los datos deben poder almacenarse en caché.

Beneficios que aporta

  • Reducen los costos de mantenimiento.
  • Permite separar la capa de presentación de la de negocio, por lo que es más fácil en un futuro migrar a una nueva tecnología para el frontend o hacer cambios en el diseño.
  • Es más fiable, escalable, mantenible y testeable; ya que cada petición apunta a un endpoint distinto por lo que si hay un error es fácil de localizar y subsanar.
  • Pueden implementarse nuevas versiones sin afectar a los clientes ya existentes.
  • Es independiente de la plataforma y el lenguaje, por lo que puede ser implementada en diversidad de entornos

📦 Instalación

Todo esto lo he hecho usando DDEV, si aún no sabes lo que es te recomiendo el artículo DDEV: Entornos de desarrollo PHP basados en Docker de mi compañero Manuel Aguilar en el que te explica todo lo necesario. También estoy usando drush, una utilidad de drupal de la que puedes aprender más con Cómo instalar drush

Primero vamos a instalarnos un proyecto nuevo de drupal. Para ello:

composer create-project drupal/recommended-project drupal-api-test

Instalamos drush para ayudarnos en ciertas tareas:

composer require drush/drush

Realizamos la instalación del sitio con drush:

drush site:install -y

Accedemos a nuestro sitio recién instalado

drush uli

📄 Generación de contenido

Para el ejemplo a realizar vamos a generar algo de contenido de prueba de forma automática. Para hacer esto necesitamos los módulos devel y devel_generate, que los vamos a solicitar como dependencias de desarrollo. Vamos a instalar y activar devel:

composer require --dev drupal/devel

drush en devel devel_generate

Ahora pasamos a generar el contenido con drush, aquí estamos usando el tipo de contenido article, pero nos valdría para cualquiera. Lo mismo para la cantidad, nostros vamos a generar 20 artículos, pero podrían ser todos los que nos hiciesen falta.

drush genc 20 --bundles=article

Con esto hecho ya tenemos suficiente para empezar a configurar nuestra API.

⚙️ Configuración

Drupal por defecto ya trae todo lo necesario para hacer una API, sólo hay que activar ciertos módulos:

  • HAL: serializa las entidades usando Hypertext Application Language.
  • RESTful Web Services: Expone las entidades en formato rest.
  • HTTP Basic Authentication: Provee una forma de autenticarnos para que nuestra api sea segura.
  • Serialization: Aporta el poder de/serializar las entidades desde/a otros formatos como XML o JSON.

Después de esta breve introducción a lo que hace cada módulo vamos a activarlos:

drush en hal rest basic_auth serialization

El módulo hal no es necesario activarlo ya que podríamos seguir accediendo con los formatos xml o json.

🎉 ¡Ya tenemos todo listo para crear nuestro endpoint! 🎉

🌐 Nuestro primer endpoint

Ya que tenemos todo configurado podemos proceder a crear nuestra primera ruta con la que accederemos a nuestro listado de artículos. Para lograr esto vamos a utilizar el potente sistema de vistas que proporciona Drupal.

Vamos a Structure > Views > Add View. El nombre de la vista puede ser cualquiera, yo por seguir una nomenclatura voy a llamarlo "Articles". En los ajustes configuramos que muestre contenido de tipo Article, aquí podríamos añadir más opciones como que filtre por categoría o que ordene de forma inversa, etc; eso lo dejo a vuestra imaginación. Para terminar, en el último bloque vamos a marcar la casilla "Provide a REST export" y en la ruta introduciremos api/v1/articles.

Podríamos simplemente poner api/articles pero si algún día quisiéramos cambiar cualquier ajuste de la vista los clientes actuales se verían afectados, de esta forma estamos versionando la API. Hay más formas de hacer esto, por ejemplo por las cabeceras de la petición.

Con esto ya podemos probar nuestro endpoint. Yo voy a utilizar Postman como herramienta pero hay más opciones disponibles. Si hacemos una petición a nuestra url (https://nombre-de-mi-sitio.dominio/api/v1/articles) mediante el navegador veremos que nos da un "Client error". Esto se debe a que no le hemos especificado el formato en el que queremos recibir los datos (hal_json, json o xml). Basta con añadir un parámetro "_format" que tenga el valor que queremos (https://nombre-de-mi-sitio.dominio/api/v1/articles?format=hal_json).

Si nos vamos a postman veremos el listado de nuestros artículos:

postman json

Si queremos especificar un formato específico tenemos que realizar unos ajustes en la vista. Nos vamos a la edición de ésta y en el apartado "Format" modificamos los settings y marcamos la casilla del formato deseado. En mi caso voy a seleccionar hal_json. Con esto ya no es necesario especificar el formato en la url. Podemos seleccionar más de uno para tener distintas opciones.

Como tampoco quiero tanta información en lugar de mostrar la entidad voy a mostrar los campos. Modificamos el ajuste "Show" y seleccionamos "Fields". Ahora en la sección "Fields" añadimos los campos que queramos mostar. Así quedaría la configuración de mi vista:

rest view config

Si volvemos a realizar la petición con postman vemos que la estructura de nuestro contenido ha cambiado y muestra la información que nos interesa.

postman rest api fields

Como todo esto está construido alrededor de las views de drupal podemos seguir aplicando formateadores específicos, añadiendo reglas en caso de que algún campo esté vacío, etc..

Todo esto está muy bien, pero hay un aspecto que no hemos tenido en cuenta: la seguridad. Vamos a verlo.

🔒 Securizando nuestra API

Cuando tenemos datos sensibles no nos interesa que cualquiera pueda acceder a esos datos, es por eso que muchas API necesitan un método de autenticarse. Hay varios métodos de autenticación, aquí algunos de ellos:

  • Mediante un token en la url
  • OAuth2
  • JWT
  • Basic auth
  • Mediante cookies

En nuestro caso vamos a utilizar basic auth, ya que es de los más sencillos de implementar. Vamos a modificar nuestra vista una vez más y en la sección "Path Settings" modificamos el ajuste "Authentication" y seleccionamos la casilla basic_auth. En "Access" cambiamos "Permission" por "Role" y seleccionamos "Authenticated user". De esta forma si volvemos a acceder vemos que nos devuelve un código 401.

Para probar que funciona nos vamos a ir a postman y en la pestaña Authorization vamos a seleccionar basic auth. Aquí introduciremos las credenciales de un usuario de Drupal. Si está todo correcto nos volvería a mostrar nuestra lista de artículos.

Hasta aquí esta introducción a la creación de APIs con Drupal. Estad atentos ya que en un futuro vendrán más posts de cómo añadir más funcionalidades tales como crear nuevos registros, acutalizarlos y eliminarlos. Además también veremos cómo añadir nuestra propia lógica e integrar la API con otras aplicaciones como React.

 

Comentarios

Añadir nuevo comentario