La API web de Magento 2
A lo largo de los capítulos anteriores, aprendimos cómo utilizar algunos de los componentes backend para que los propietarios de las tiendas puedan administrar y manipular datos como clientes, productos, categorías, pedidos, etc. A veces esto no es suficiente, como cuando ingresamos o extraemos datos de sistemas de terceros. En casos como estos, el marco de la API web de Magento facilita la llamada a los servicios de Magento a través de REST o SOAP.
En este capítulo, cubriremos los siguientes temas:
- Tipos de usuarios
- Métodos de autenticación
- REST versus SOAP
- Práctica con autenticación basada en tokens
- Práctica con autenticación basada en OAuth
- Llamadas a API web basadas en OAuth
- Práctica con autenticación basada en sesiones
- Crear API web personalizadas
- Interfaz de criterios de búsqueda para filtrado de listas
Antes de que podamos comenzar a realizar llamadas a la API web, debemos autenticar nuestra identidad y tener los permisos (autorización) necesarios para acceder al recurso API. La autenticación permite a Magento identificar el tipo de usuario de la persona que llama. En función de los derechos de acceso del usuario (administrador, integración, cliente o invitado), se determina la accesibilidad a los recursos de las llamadas API.
Tipos de usuarios
La lista de recursos a los que podemos acceder depende de nuestro tipo de usuario y se define dentro del archivo de configuración de nuestro módulo webapi.xml.
Hay tres tipos de usuarios conocidos por API, que se enumeran a continuación:
- Administrador o integración: Recursos para los cuales están autorizados administradores o integradores. Por ejemplo, si los administradores están autorizados para el recurso Magento_Cms::page, pueden realizar una llamada POST /V1/cmsPage.
- Cliente: Recursos para los cuales los clientes están autorizados. Estos son los recursos con permiso anónimo o propio.
- Usuario invitado: Recursos para los cuales los invitados están autorizados. Estos son los recursos con permiso anónimo.
Dos archivos desempeñan un papel crucial en la definición de una API: nuestro módulo acl.xml y los archivos webapi.xml.
acl.xml es donde definimos nuestra lista de control de acceso al módulo (ACL). Define un conjunto disponible de permisos para acceder a los recursos. Los archivos acl.xml en todos los módulos de Magento se consolidan para crear un árbol de ACL que se utiliza para seleccionar recursos de función de administrador permitidos o acceso de integración de terceros (Sistema | Extensiones | Integraciones | Agregar nueva integración | API disponibles).
webapi.xml es donde definimos los recursos de la API web y sus permisos. Cuando creamos webapi.xml, se hace referencia a los permisos definidos en acl.xml para crear derechos de acceso para cada recurso API.
Echemos un vistazo al siguiente webapi.xml (truncado) del módulo principal Magento_Cms:
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
...
<route url="/V1/cmsPage" method="POST">
<service class="Magento\Cms\Api\PageRepositoryInterface" method="save" />
<resources>
<resource ref="Magento_Cms::page" />
</resources>
</route>
...
<route url="/V1/cmsBlock/search" method="GET">
<service class="Magento\Cms\Api\BlockRepositoryInterface" method="getList" />
<resources>
<resource ref="Magento_Cms::block" />
</resources>
</route>
...
</routes>En el archivo webapi.xml anterior para la API de la página CMS, solo un usuario con autorización Magento_Cms::page puede acceder a POST /V1/cmsPage o GET /V1/cmsBlock/search. Volveremos a una explicación más detallada de la ruta más adelante en nuestros ejemplos; Por el momento, nuestra atención se centra en los recursos. Podemos asignar varios elementos de recursos secundarios en recursos. En casos como estos, sería suficiente que un usuario tuviera cualquiera de esas ACL asignadas para poder realizar una llamada API.
Luego, la autorización real se otorga a un administrador o a una integración, definida en el administrador de Magento, con el grupo completo o un recurso específico seleccionado en el árbol de ACL, como se muestra en la siguiente captura de pantalla:
Dado que webapi.xml y acl.xml van de la mano, echemos un vistazo al archivo acl.xml (truncado) del módulo principal Magento_Cms:
<resources>
<resource id="Magento_Backend::admin">
<resource id="Magento_Backend::content">
<resource id="Magento_Backend::content_elements">
<resource id="Magento_Cms::page" ...>
...
</resource>
</resource>
</resource>
</resource>
</resources>Observe cómo la posición del recurso Magento_Cms::page está anidada en Magento_Backend::content_elements, que a su vez está anidada en Magento_Backend::content, que a su vez está anidada en Magento_Backend::admin. Esto le indica a Magento dónde representar la ACL en el administrador de Magento cuando se muestra el árbol de recursos de roles como se muestra en la captura de pantalla anterior. Esto no significa que el usuario autorizado contra el recurso Magento_Cms::page no podrá acceder a la API si también se le otorgan todos esos recursos principales de Magento_Backend.
Autorizar contra un recurso es algo sencillo. No hay verificación de árbol al momento de autorizar. Por lo tanto, se requiere que cada recurso tenga un valor de atributo de identificación id único en un elemento de recurso cuando se define en acl.xml.
Los recursos que acabamos de definir son los que enumeramos anteriormente como recursos para los cuales los administradores o integradores están autorizados.
Al cliente, por otro lado, se le asigna un recurso llamado anonymous o self. Si tuviéramos que hacer una búsqueda completa de cadenas <resource ref=”anonymous” /> en todos los módulos principales de Magento, aparecerían varias ocurrencias.
Echemos un vistazo al archivo vendor/magento/module-catalog/etc/webapi.xml del módulo principal (truncado):
<route url="/V1/products" method="GET">
<service class="Magento\Catalog\Api\ProductRepositoryInterface" method="getList"/>
<resources>
<resource ref="anonymous" />
</resources>
</route>