Creación de Endpoint personalizado (POST resource)

Vamos a crear un endpoint que obtenga un email y pueda hacer con él las operaciones que necesitemos.

Para crear un endpoint por código de tipo POST en Drupal 8, 9 ó 10, debemos seguir estos pasos:

1. Crear una clase siguiendo la estructura de carpeta /src/Plugin/rest/resource/ ,

• Dicha clase será nuestro recurso personalizado.
• Para nuestro ejemplo dicha clase la pondremos en el archivo SetEmailResource.php, con lo que la ruta de dicha clase quedará así:

          /modules/custom/module_name/src/Plugin/rest/resource/SetEmailResource.php

2. En dicho archivo estableceremos estas lineas al inicio:

• El namespace
• Importacines de las clases ResourceBase y ResourceResponse de Drupal, que son esenciales para la creación de recursos REST.

<?php

namespace Drupal\module_name\Plugin\rest\resource;

use Drupal\rest\Plugin\ResourceBase;
use Drupal\rest\ResourceResponse;

3. Ahora escribiremos la Clase SetEmailResource que extiende ResourceBase. Esto es necesario al crear recursos REST en Drupal.

class SetEmailResource extends ResourceBase {

}

4. Luego debemos escribir una anotación @RestResource justo sobre la clase. Dicha anotación sirve para difinir propiedades del recurso REST, En este caso:

•  id: Identificador único del recurso.
•  label: Etiqueta del recurso para identificarlo en la pantalla activación de REST UI.
•  uri_paths: Rutas URIs para este recurso. En este caso, el recurso manejará solicitudes de creación (POST) en la ruta /people/set_email.
•  "create": indica que este recurso responderá a solicitudes de creación, que corresponden a solicitudes HTTP de tipo POST

/**
 * Provides a Demo Resource
 *
 * @RestResource(
 *   id = "set_email_resource",
 *   label = @Translation("Set email of people"),
 *   uri_paths = {
 *     "create" = "/people/set_email"
 *   }
 * )
 */

  Observaciones:

• Si quisieras definir un recurso que responda a solicitudes de lectura (GET), podrías usar "canonical" en lugar de "create". Podemos encontrar un ejemplo de GET en https://softwinperu.com/drupal-developer/blog/creacion-de-endpoint-personalizado-rest-resource
• En resumen, dentro de la anotación @RestResource, el término utilizado en uri_paths especifica el tipo de solicitud HTTP al que responde el recurso. "create" se asocia con POST, mientras que "canonical" se asocia con GET.

  Hasta este paso el código va quedando de esta manera:

<?php

namespace Drupal\module_name\Plugin\rest\resource;

use Drupal\rest\Plugin\ResourceBase;
use Drupal\rest\ResourceResponse;

/**
 * Provides a Demo Resource
 *
 * @RestResource(
 *   id = "set_email_resource",
 *   label = @Translation("Set email of asistents"),
 *   uri_paths = {
 *     "create" = "/people/set_email"
 *   }
 * )
 */
class SetEmailResource extends ResourceBase {

}

 

5. Vamos a implementa el método post, que manejará las solicitudes POST al recurso. Recibe un parámetro $data, que contendrá los datos de la solicitud POST.

public function post($data) {
   
}

• Drupal cambiará automaticamente el cuerpo de la solicitud (ya sea JSON, XML, formularios URL-encoded, etc.) y lo convierte en un array asociativo. Esto significa que, cuando accedes al parámetro $data en el método post en mención, ya es un array PHP, sin importar el formato en que se haya enviado originalmente.
• Entonces si el cliente por ejemplo envía sus datos en formato JSON en el cuerpo de la solicitud, Drupal decodificará por sí solo ese JSON y nos retornará $data como un array sin que tengamos la necesidad de decodificar el JSON a mano.
• Por supuesto que para que la conversión a un array se pueda dar, el formato de origen debería ser un formato entendible, por lo general es un JSON en donde las llaves del JSON son interpretadas a las llaves de un array asociativo.

6. Ahora haremos el Procesamiento de Datos y Actualización de la Base de Datos:

  

  public function post($data) {
    $email = $data['email'];
  
    //Pon aquí tu código para grabar el correo en la base de datos

    $response = ['message' => 'The email '.$email.' was added'];
  
    return new ResourceResponse($response);
  }

 

  Con lo que el código quedará así:

 

<?php

namespace Drupal\module_name\Plugin\rest\resource;

use Drupal\rest\Plugin\ResourceBase;
use Drupal\rest\ResourceResponse;

/**
 * Provides a Demo Resource
 *
 * @RestResource(
 *   id = "set_email_resource",
 *   label = @Translation("Set email of asistents"),
 *   uri_paths = {
 *     "create" = "/people/set_email"
 *   }
 * )
 */
class SetEmailResource extends ResourceBase {
  public function post($data) {
    $email = $data['email'];
  
    //Pon aquí tu código para grabar el correo en la base de datos

    $response = ['message' => 'The email '.$email.' was added'];
  
    return new ResourceResponse($response);
  }
}

  7. No olvidemos que después de hacer todo esto debemos activar nuestro recurso POST en la pantalla de administración del módulo contribuido REST UI.

      Para hacer esta activación encontraremos nuestro recurso con el label que definimos en el comentario del paso 4 "Set email of people" o por la ruta que ahi definimos.