Configurar Servicios web API en Magento 2

¿Es claro el concepto? ¿cuando se lee se entenderá? o más bien se relaciona con un servicio web, no se como lo vean los demás pero en mí opinión cuando veo Servicio Web sé que estamos hablando de WebServices, pero ¿como puedo llevar eso a Magento? y lo que siempre he pensado como empiezo y por donde, en este articulo intentare explicarlo con mis palabras y como es clásico de mí mostrar la parte sencilla y fácil de entender, la explicación con manzanas para lograr no aprender a hacer estos componentes sino más bien a entender su importancia, por que deberíamos aprender a crearlos y al final sera sencillo.

Bien ahora comentare un poco cual es la importancia de este concepto en Magento, y es algo muy sencillo de entender, que pasa si necesito comunicarme con una tabla interna de Magento para obtener datos que necesito para generar algún reporte más sofisticado hablando de alguna tabla personalizada de algún componente o plugin, o que pasa si lo que necesito no me lo brinda al API nativa de Magento, pues es aquí en donde entraría este concepto la flexibilidad que tiene Magento para lograr ampliar la gama de posibilidades, y pues bueno para lograrlo hay que saber como hacerlo y aquí es donde entro yo, voy a mostrar como hacerlo.

Para que esto se pueda digerir de la forma más sencilla voy a enfocarme en una receta como si hablara de una receta para cocinar algo, así se me hace más sencillo para mí expresarlo y creo que sé podra entender muy bien, lo que voy a listar a continuación son lo que necesitamos saber y conocer cada elemento para lograr crear algo:

• Realizar una configuración XML
• Ingredientes del Archivo de configuración XML
• Preparando el Archivo de configuración XML
• Sazonando el Archivo de configuración XML
• Los toques finales y el componente está listo

Realizar una configuración XML

como podrá notarse a simple vista siempre hablamos de un archivo XML y basta recordar que en Magento 2 cuando hablamos de archivos de configuración nos estamos refiero a archivos XML, así que esta no es la excepción y para lo cual aquí es donde explicara de que va este archivo cual es su funciona ante todo esto, a donde y como es que deberíamos crearlo.

Lo primero es, muy sencillo y es basta con entender que para poder realizar un componente de WebService en Magento 2, se requiere de crear un archivo XML que crearemos y colocaremos en una ruta especifica de un módulo, este archivo XML es el que le indicara a Magento que existe un llamado externo a través de esta configuración, cuales son los métodos que estarán disponibles al llamado, así como los elementos que se le puedan enviar y la URL de invocación.

Ingredientes del Archivo de configuración XML

Ahora necesitamos los ingredientes para empezar a preparar el Web Services, aquí lo explicare como yo lo entendió, bien tengo la necesidad de comunicarme con datos internos en Magento que la API no me da lo que estoy buscando, así que requiero hacer algo más, pues bien como podría comunicarme con el alma de Magento con lo que tiene dentro con los datos de sus tablas pues puede haber muchas formas pero la más segura y flexible es a través de una comunicación que por un lado me permita indicarle que quiero hacer a donde me quiero comunica con que datos exactamente y lo mejor aún que tenga una llave de acceso un nivel de seguridad que sin esa llama no pueda conectarme por ningún motivo y eso lo hace muy Robusto y Flexible, así que en este punto los ingredientes que necesito es:

1. Crear un archivo XML llamado webapi.xml
2. Crear una llave de comunicación con Magento mediante el XML
3. Crear un par de script en PHP

Aquí lo que sucederá es que se debe dejar el archivo XML en algún lugar donde me lo pida Magento y segundo cuando él tome ese archivo lo cargue a sus sistemas en cuanto yo empiece a realizar peticiones de la información el me preguntara si tengo la llave de acceso y si la tengo y es valida podre entrara y obtener la información que estoy esperando encontrar, suena muy sencillo no.

Preparando el Archivo de configuración XML

Hay algo importante antes de pasar a desarrollar nuestra receta o en este caso la construcción de los archivos necesarios para el servicio web, hay que entender una parte muy importante si estas aquí leyendo este texto es por que eres programador Magento tal vez no avanzado pero si tienes las nociones y lo digo por que lo que empezaré a mencionar a continuación son las cosas básicas de realizar un modulo en Magento, sin ir tan legos el simple echo de entender que es una clase, que es un XML como hacer una función etc, son todos conceptos que ya deberías conocer por que si no es así claramente no estas en el lugar correcto.

webapi.xml

Bien lo primero vamos al archivo importante en todo esto y no quiero decir que el resto no lo sean, sino que más bien empezaremos por lo más básico que de este dependerá el buen funcionamiento, este archivo es el encargado de decirle a Magento a través de elementos y atributos de configuración en XML, recordemos que los archivos XML representa la forma de realizar configuraciones e indicaciones a un módulo en Magento 2.

El archivo que debería estar ubicado en el directorio de un módulo  dentro de etc/webapi va a representar un esquema de validación. Realmente cuando leo esto de inicio, no lo entiendo, es mejor que te lo diga con mis propias palabras, que es el esquema de validación, todos los archivos XML tienen definido una URL de un archivo con extensión. XSD, dentro de este archivo se encuentra una serie de reglas que definen los nodos y estructuras a las que hace referencia una configuración, en pocas palabras si hablamos de desarrollar un módulo para un servicio web, ahí estará definido como se estructuraría un XML para un servicio Web. Solo nos toca usar esos nodos y aplicarlos.

Cuáles son esas URL:  app/code/Magento/Webapi/etc/webapi.xsd o  vendor/magento/module-webapi/etc/webapi.xsd y tiene algún sentido aprenderlas, en realidad desde mi punto de vista no, pero si somos un poco curiosos podríamos revisar estos archivos y nos daríamos cuenta de que tipo de nodos están disponibles y descubrir algunos aspectos que probablemente desconocíamos.

En mi caso descubrí que podía utilizar el archivo XSD nativo o bien podía crear un XSD personalizado con mis propios atributos y características, pero este podría ser un tema para otra publicación.

Entender la comunicación y definición del archivo webapi.xml

Para que entendamos un poco más por qué definimos Clases en PHP en un directorio API y dentro en un directorio Data y porque esas clases contienen elementos en comentarios como @param y @return, lo primero es que te mostraré un pedazo de código de un archivo nativo para el módulo de Customer ubicado en vendor/magento/module-customer/etc/webapi.xml que sería exactamente lo mismo si creamos un módulo personal, esto es para que logres entenderlo y te des cuenta de que al final es algo mu sencillo.

Esto es el archivo webapi.xml:

Esta es la clase PHP de la que hablo:

Si vemos la clase contiene un método getById($id) que en nuestro archivo webapi.xml ya está definido en el atributo method, ahora si recordamos un poco la teoría de los WebServices en general, hablamos de un sistema de comunicación entre diferentes tecnologías y que estas podrían comunicar información de un extremo a otro en diferentes plataformas e incluso con diferentes lenguajes de programación, en medio recordamos que existen los Webservices ya sea por SOAP o REST esto último son los formatos en los cuales podemos identificar la creación de WebService que para relacionarlo un poco si hablamos de SOAP pensamos en un archivo XML y si hablamos de REST pensamos en un archivo JSON.

Cuando trabajamos con Magento debemos entender que la comunicación también existe y una parte de forma dinámica y la otra nosotros la tenemos que definir, pero déjame decirte que la parte que nos toca definir es la más sencilla, tan solo necesitas entender como y te darás cuenta de que es muy sencillo.

 ¿Que es lo que tenemos que notificar? 

Entendiendo esto un poco más si la lógica que se debe cumplir entre la comunicación de un WebServices es el envío de información de un extremo al otro puede recibir como respuesta un Objeto o una clase en un formato específico sería un poco complejo adivinarlo así que para esto Magento construye de forma dinámica a través de clases en PHP, esta notificación y la respuesta esperada de forma dinámica, para esto de nuestro lado solo nos tocaría informarle a esta comunicación a través de una clase y mediante un segmento de comentarios con elementos definidos por un @, aquí lo que informamos son los parámetros que espera el método del servicio en este ejemplo getById($id) así como también el resultado que espera el mismo.

Mediante los elementos @param y @return se debe indicar el tipo de parámetro a enviar, así como el tipo de repuesta a recibir, si esto se define de forma correcta a Magento a través de su lenguaje PHP no tendrá ningún problema en realizar la conversión correcta.

Antes de continuar es importante que sepas a qué se le conoce como Bloque de documentación, es una sección dentro del código fuente que por lo regular representa el encabezado de una variable o una función  y está dentro de comentarios como se muestra a continuación:

Dentro del bloque de documentación se deben definir los elemento @param, @return y @throws y todos los elementos definidos en el bloque de documentación deberán seguir estas reglas:

• Los parámetros deben definirse como @param Tipo $NombredeParametro por ejemplo: @param int $id
• El tipo de retorno se debe definir como @return type por ejemplo: @return \Magento\Customer\Api\Data\GroupSearchResultsInterface
• Los tipos de parámetros que se pueden utilizar en @param son:
  • mixed o anyType
  • bool o boolean
  • str o string
  • integer o int
  • float
  • double
• Los tipos de objetos también permitidos pueden ser clases completamente calificadas y clases de interface completamente calificadas
• Para poder definir un tipo de retorno de tipo matriz  solo se deben asignar corches [] como se muestra en la imagen

Como por ejemplo vamos a ver como se definiría un parámetro de tipo array con valores string

@param string[] $types

Veamos otro ejemplo como se definiría un parámetro de tipo entero $id:

@param int $id

Así como también un parámetro $customer que es un objeto de clase \Magento\Customer\Api\Data\CustomerInterface

@param \Magento\Customer\Api\Data\CustomerInterface $customer

Es importante comentar que cuando utilizamos un parámetro de tipo objeto que apunta a una clase en específico se debe colocar la ruta completa de la clase, ya que de lo contrario marcar una excepción.

Ahora, para definir un retorno de tipo objeto de la clase \Magento\Customer\Api\Data\CustomerInterface sería de la siguiente manera

@return \Magento\Customer\Api\Data\CustomerInterface[]

Estructura del archivo principal webapi.xml

Nodo <routes> : Este es un nodo obligatorio y es donde se definiría la ruta al XSD, donde está la validación del esquema que contiene dos atributos xmlns:xsi que define la URL de la instancia de esquema, así como el atributo xsi:noNamespaceSchemaLocation para definir el nombre del archivo de esquema para validar la API web.

Nodo <route> : Este es un nodo obligatorio y es donde se definiría la ruta al XSD, donde está la validación del esquema que contiene dos atributos xmlns:xsi que define la URL de la instancia de esquema, así como el atributo xsi:noNamespaceSchemaLocation para definir el nombre del archivo de esquema para validar la API web.

Nodo <route> : Mediante este nodo se definen 4 atributos,
* url que definirá el endpoint del webservices la cual es una cadena que debe comenzar con /V1 el cual indica el número de versión, y si se requiere pasar un parámetro por URL se define a través de dos puntos como por ejemplo el siguiente endpoint que pasa por parámetro el SKU /V1/products/:sku.
* method, mediante este atributo se define como será la comunicación con el servicio web a través de GET, POST, PUT y DELETE.
* secure este atributo es opcional y define si la petición forzosamente es a través de HTTPS.
* SoapOperation mediante este atributo se define el nombre de la operación SOAP si fuera el caso y estaría reemplazado la definición del método de interfaz.

Nodo <service> : Mediante este nodo se implementa la interfaz y el nombre del método que será invocado desde el servicio, esto mediante dos atributos.
* class en el cual se define la ruta de la clase que implementará la interfaz. 
* method que definirá el nombre del método de la API web

Nodo <resources> Solo es un nodo contenedor del nodo de resource.

Nodo <resource> Desde este nodo se definirán los permisos de grupo a los cual tendrá acceso la petición del servicio web mediante el atributo ref el cual acepta los valores self, anonymous o un recurso en particular como por ejemplo Magento_Customer::group 

Nodo <data> Solo es un nodo contenedor del nodo parameter.