Crear una API en Drupal 7 con el módulo RESTful

Thursday, August 10, 2017

Vamos a ver cómo podemos crear una API en Drupal con el módulo RESTful, usando la versión 2.x.

El módulo RESTful tiene las siguientes ventajas respecto a otros módulos que también permiten crear servicios:

Versiones: cada endpoint que creemos puede tener diferentes versiones y coexistir con las anteriores. Esto facilita el mantenimiento a la hora de tener que hacer cambios y no provocar problemas de compatibilidad con los usuarios de la API.
API para manejo de entidades.
El código del módulo está muy orientado a objetos. Además, utiliza el módulo Plug para crear cada servicio, por lo que el código será más sencillo de mantener.

Como ejemplo crearemos un servicio que liste los nodos de tipo página de nuestra web.

Para empezar, necesitaremos instalar RESTful en nuestro Drupal. Hay que tener en cuenta que la versión de PHP mínima para tener RESTful es la 5.5.9.

En el módulo donde vayamos a codificar el servicio debemos añadir estas líneas en el .info:

...
registry_autoload[] = PSR-4

De esta forma diremos que queremos autocargar clases con PSR-4.

Ahora, empezaremos con la clase que represente al servicio. Debemos crearla en una carpeta que se llame src/Plugin/resource , ya que es la que establece RESTful para declarar los servicios REST.

src/Plugin/resource/Page__1_0.php

<?php

namespace Drupal\my_module\Plugin\resource;

use Drupal\restful\Plugin\resource\ResourceNode;

/**
 * Class Page__1_0.
 *
 * @Resource(
 *   name = "page:1.0",
 *   resource = "page",
 *   label = "Page",
 *   description = "Node page endpoint.",
 *   authenticationTypes = {
 *     "cookie"
 *   },
 *   dataProvider = {
 *     "entityType": "node",
 *     "bundles": {
 *       "page"
 *     },
 *     "idField": "id"
 *   },
 *   authenticationOptional = TRUE,
 *   majorVersion = 1,
 *   minorVersion = 0,
 * )
 */
class Page__1_0 extends ResourceNode {

  /**
   * {@inheritdoc}
   */
  public function publicFields() {
    $fields = parent::publicFields();
    $fields['body'] = array(
      'property' => 'body',
      'sub_property' => 'value',
    );
    return $fields;
  }
}

El archivo acaba en __1_0 para poder indicar la versión 1.0.

En el código podemos apreciar lo siguiente:

Extendemos de la clase ResourceNode, clase base para crear servicios sobre tipos de contenido.
Usamos la anotación @Resource para indicar que esta clase corresponde a un servicio. Las variables más importantes son:
- resource: ruta del servicio.
- majorVersion.
- minorVersion.
- name: nombre completo del servicio. Debe seguir este patrón: resource:majorVersion.minorVersion.
- dataProvider: aquí indicamos el tipo de entidad que queremos mostrar (nodos) y su tipo (página). Si quisiéramos añadir otro tipo de entidad solo deberíamos cambiar la propiedad entityType.
Con la información de la anotación sabemos que la ruta será /api/v1.0/page.
En la clase sobreescribimos el método publicFields el cual nos permite añadir todos los campos que necesitemos en el servicio. Nosotros añadimos el campo body (property) y la propiedad value (sub_property) bajo el nombre de body (clave del array, podemos poner cualquiera). Todos los campos que queramos los podemos consultar en la gestión de campos del tipo de contenido en concreto. También tendremos otros campos que se añaden por defecto: el título del nodo (label), el identificador(id) y la ruta al servicio para el nodo en concreto (self).

Con esto ya tendremos listo nuestro servicio, en /api/v1.0/page. Este servicio también permitirá crear, editar y borrar contenido (si el usuario que lo pide tiene los permisos adecuados).

Si consultamos el servicio desde el mismo navegador veremos lo siguiente.

{
  "data": [
    {
      "id": 1,
      "label": "Example",
      "self": "http://drupal-modules.me/api/v1.0/page/1",
      "body": "<p>Example</p> "
    },
    {
      "id": 2,
      "label": "Example 2",
      "self": "http://drupal-modules.me/api/v1.0/page/2",
      "body": "<p>Example 2</p> "
    }
  ],
  "count": 2,
  "self": {
    "title": "Self",
    "href": "http://drupal-modules.me/api/v1.0/page"
  }
}

Tendremos todos nuestros nodos de tipo página recopilados en data, con los campos que necesitamos.

La estructura del JSON viene formada de esta forma ya que RESTful ofrece diferentes formatos para la respuesta del servicio, en este caso partimos del formato Simple JSON. Si quisiéramos cambiar el formato lo podemos hacer en Configuración > Servicios web > Restful, cambiando el campo Default Formatter.

Configuración de Restful