Cómo crear un endpoint en la API de Magento2

Pasado otro #MageTravel, toca seguir agregándole funcionalidades (y documentado para cuando falle la memoria) al módulo Barbanet_SampleModule.

Hoy un primer acercamiento, muy básico, a la API. En este ejemplo vamos a definir un muy simple endpoint para nuestro módulo.

Para definir un endpoint, dentro del directorio etc creamos el archivo webapi.xml.

<?xml version="1.0"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
    <route url="/V1/samplemodule/ping/" method="GET">
        <service class="Barbanet\SampleModule\Api\PingInterface" method="pong" />
        <resources>
            <resource ref="anonymous" />
        </resources>
    </route>
</routes>

Lo que acabo de hacer es especificar una ruta para mi nuevo endpoint que responderá a un request GET.

<route url="/V1/samplemodule/ping/" method="GET">

Luego indicamos qué clase y qué método responderá la petición:

<service class="Barbanet\SampleModule\Api\PingInterface" method="pong" />

Y, finalmente, le indicamos qué tipo de control de autenticación vamos a implementar.

<resources>
    <resource ref="anonymous" />
</resources>

En este caso estoy definiendo un endpoint que no necesitará de autenticación.

Ahora, a crear la interfase. Para esto creamos el directorio Api en la raíz de nuestro módulo y alli crearemos nuestra interfase: PingInterface.php

<?php
 
namespace Barbanet\SampleModule\Api;
 
interface PingInterface
{
    /**
     * Returns a test message
     *
     * @api
     * @return string Pong message.
     */
    public function pong();
}

Si bien hasta ahora no hubo indicio, vamos a crear un model (la historia de los models y las interfases es una historia aparte, ya que en Magento 2 no hablamos más de, simplemente, los Modelos, sino que se trata más de la capa de persistencia que incluye más que solo un modelo de datos… pero esto es algo para ver más en detalle en otro momento).

Nuestro modelo se ubicará dentro de Model y lo llamaremos Ping.php.

<?php
 
namespace Barbanet\SampleModule\Model;
 
use Barbanet\SampleModule\Api\PingInterface;
 
class Ping implements PingInterface
{
 
    /**
     * Returns a test message
     *
     * @api
     * @return string Pong message.
     */
    public function pong()
    {
        return "Pong!";
    }
}

El paso final será definir qué Modelo invocará la Interface. Esto lo hacemos en nuestro ya amigo /etc/di.xml. Allí agreamos:

<preference for="Barbanet\SampleModule\Api\PingInterface" type="Barbanet\SampleModule\Model\Ping" />

Luego de limpiar cache, vamos a nuestro navegador e ingresamos la URL de nuestra instancia más la ruta que hemos definido.

En mi caso:

El endpoint funcionó correctamente, pero como dije al comienzo, este es el ejemplo más básico. Más adelante iremos viendo ejemplos más complejos en cuanto a los modelos, las operaciones y la autenticación.

Lo comentado en el post sobre el módulo Barbanet_SampleModule está disponible en GitHub bajo el tag 2.22.0.