Como adicionar métodos na API do Magento

No artigo de hoje, mostrarei um exemplo básico de como podemos publicar o método de uma classe nas APIs REST e SOAP do Magento 2.

As APIs REST do Magento estão disponíveis em /rest/V1 em qualquer loja Magento 2. Boa parte destas APIs são expostas por módulos do próprio Magento e consumidas em diversas áreas da plataforma.

Porém, nada impede você de consumir estas APIs nas suas integrações.

Como os métodos são expostos à API

De forma resumida, o Magento espera que métodos e classes expostos na API implementem classes do tipo interface e sejam declarados em um arquivo webapi.xml.

Estes métodos ter blocos de comentário que definem @param e @return a fim de informar o Magento os tipos de parâmetros e retornos esperados.

Quer ver um exemplo?

Mão na massa em 5 minutos

No exemplo abaixo, criarei uma API simples que espera receber uma string qualquer. Ela será responsável por devolver o valor reverso desta mesma string. Ou seja, se passarmos abc como parâmetro, espero receber cba como retorno. O objetivo aqui é apenas mostrar como podemos expor um método personalizado.

O nome do módulo que criaremos é Magenteiro_StringApi. Não mostrarei abaixo a estrutura básica do módulo, mas você pode conferir no link ao lado.

Criando a interface (contrato de serviço)

<?php
declare(strict_types=1);

namespace Magenteiro\StringApi\Api;
/**
 * String API Interface
 */
interface StringApiInterface {
    /**
     * Reverse a string
     * @param string $string
     *
     * @return string
     */
    public function reverse(string $string): string;
}

A primeira classe que criei, define o método que será exposto à API (reverse). Os parâmetros de entrada e saída são informados nos comentários. Note que no meu exemplo, o tipo de parâmetro de entrada e saída é do tipo string e o nome do parâmetro também foi definido como $string. Bem criativo, não é mesmo?

Criando a classe e o método que vamos expor na API

<?php
declare(strict_types=1);

namespace Magenteiro\StringApi\Model;

use Magenteiro\StringApi\Api\StringApiInterface;

class StringApi implements StringApiInterface
{
    /**
     * @inheritdoc
     */
    public function reverse(string $string): string
    {
        return strrev($string);
    }
}

Note que ela implementa nossa interface, e consequentemente é obrigada a declarar o método reverse. A reversão da string de entrada é feita com o método strrev do próprio PHP e dispensa maiores explicações.

Declarando a preferência da nossa interface

Agora devemos definir uma Preference para nossa Interface. Preferences não são usadas apenas para sobrescrever classes – como você viu no meu curso de criação de módulos para Magento 2. Elas também são usadas para definir a classe principal a ser instanciada quando uma interface é injetada.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <preference for="Magenteiro\StringApi\Api\StringApiInterface" type="Magenteiro\StringApi\Model\StringApi"/>
</config>

Definindo endpoint do nosso método personalizado

Por fim, vamos criar o webapi.xml e declarar o método e serviço que está sendo exposto. Além disso, também vamos especificar em qual URL ele será servido e quem terá acesso à ele.

<?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 method="GET" url="/V1/string/reverse">
        <service class="Magenteiro\StringApi\Api\StringApiInterface" method="reverse"/>
        <resources>
            <resource ref="anonymous"/>
        </resources>
    </route>
</routes>

A propriedade resource definirá o tipo de recurso que o cliente que está chamando precisa ter acesso. Os valores podem ser self, anonymous, ou um resource específico como Magento_Customer::group. Veja a aula “Controllers e Permissões (ACL) na área administrativa” do Magento 2: O Curso para mais detalhes.

No nosso exemplo, informei o valor anonymous. Ele permitirá que qualquer pessoa, mesmo sem estar logada, tenha acesso ao nosso novo endpoint.

Testando nosso novo endpoint

Após recompilar as classes (bin/magento s:d:c), podemos acessar nossaloja.com/rest/V1/string/reverse e passar nosso parâmetro string.

Veja no vídeo abaixo como ficou.

Como pode ver, o Magento se encarrega de devolver e converter a resposta no formato esperado.

Conclusão e Download do módulo de exemplo

Ao trabalhar com a mente aberta para APIs tornamos nossos módulos e projetos mais fáceis de serem integrados com outras aplicações. Além disso, o Magento nos força a melhorar nosso padrão de desenvolvimento ao criar interfaces para as classes que queremos expor.

O Magento 2 nasceu focado em APIs. Uma nova geração de APIs GraphQl vem ganhando cada vez mais espaço e sendo suportada cada vez mais em novas versões. No entanto, para a boa maioria das nossas necessidades e integrações, a API REST ainda é mais completa e simples de ser implementada e estendida.

Caso queira fazer download do módulo de exemplo mostrado neste artigo, utilize o formulário abaixo.

Referências e leitura recomendada: Documentação Oficial e Artigo da Webkul (ambos em Inglês)

• Sobre
• Últimos Posts

Ricardo Martins

É desenvolvedor web há 16 anos e um dos primeiros certificados pela Magento no Brasil. Instrutor de mais de 11 cursos Magento (os principais no magenteiro.com/cursos) com mais de 14 mil alunos de 105 países, é também criador do módulo PagSeguro Transparente, usado em mais de 12 mil lojas.

Últimos posts por Ricardo Martins (exibir todos)

• PagSeguro (PagBank) para Magento 1 recebe a Nova Geração - 9 de abril de 2024
• Recorrência no WooCommerce Sem Plugins Pagos - 28 de janeiro de 2024
• Chargeback. O que é, e como se livrar deles. - 19 de dezembro de 2023