Como Construir uma API RESTful com Yii2 Advanced Template

Este guia completo descreve etapas práticas para construir uma API RESTful usando o template Yii2 Advanced. Você aprenderá configuração de endpoints, criação de controladores e métodos de teste de API para exposição de dados. Este tutorial é projetado para desenvolvedores que buscam implementar uma arquitetura REST moderna e escalável.

Uma Interface de Programação de Aplicações (API) é uma interface de software que facilita a integração e troca de dados entre aplicações. Uma API RESTful é uma implementação de API que adere aos princípios da arquitetura REST (Transferência de Estado Representacional). Esta arquitetura utiliza o protocolo HTTP padrão para comunicação, tornando-a uma solução performática, escalável e fácil de desenvolver.

Construir uma API RESTful no Yii2 pode ser feito de forma eficiente. O framework fornece uma base MVC robusta e suporte integrado para desenvolvimento REST. Este artigo irá guiá-lo na criação de um endpoint de API separado, distinto da lógica típica de frontend e backend.

Leia também: Yii2: GridView avançado com GET para POST e Pjax

Usaremos um estudo de caso de exposição de dados de uma tabela user. A suposição básica é que você instalou com sucesso o template Yii2 Advanced. Caso contrário, você pode consultar a documentação oficial do Yii Framework para o guia de instalação.

Passos para Implementar uma API RESTful no Yii2

O processo de implementação consiste em três etapas principais: preparação do endpoint, configuração da aplicação e testes. Vamos discutir cada etapa em detalhes.

1. Criando a Estrutura de Diretórios da API

A primeira etapa é criar um ambiente de trabalho dedicado para a API. No template Yii2 Advanced, criaremos um novo diretório de aplicação chamado api.

1. Copie todo o conteúdo do diretório backend para o mesmo local, então renomeie a cópia para api.
2. Abra o arquivo common/config/bootstrap.php. Adicione um alias para o diretório api adicionando a seguinte linha:

   Yii::setAlias('@api', dirname(dirname(__DIR__)) . '/api');

3. Dentro do diretório environments, copie a pasta backend tanto em dev quanto em prod. Renomeie cada cópia para api.
4. Edite o arquivo environments/index.php. Adicione os caminhos de configuração para o diretório api nas seções setWritable e setCookieValidationKey.
5. Use a função “Localizar e Substituir” no seu editor de código. Substitua todas as ocorrências da string backend por api em todos os arquivos dentro da pasta api recém-criada.

2. Configurando o Controlador e as Regras de URL

Uma vez que a estrutura esteja pronta, o próximo passo é configurar o controlador que irá manipular as requisições da API.

Leia também: Remover o Frontend Web Yii2 com Apache e Nginx

1. Crie o Controlador da API. Crie um novo arquivo chamado UserController.php dentro do diretório api/controllers. Preencha com o seguinte código:

   <?php
   namespace api\controllers;
   use yii\rest\ActiveController;
   
   class UserController extends ActiveController
   {
       public $modelClass = 'common\models\User';
   }

   Este controlador herda de ActiveController, que fornece automaticamente endpoints RESTful completos (GET, POST, PUT, DELETE) para o modelo User.
2. Configure o Gerenciador de URL. Abra o arquivo api/config/main.php. Adicione ou modifique os componentes request e urlManager dentro do array components:

   'components' => [
       'request' => [
           'parsers' => [
               'application/json' => 'yii\web\JsonParser',
           ]
       ],
       'urlManager' => [
           'enablePrettyUrl' => true,
           'enableStrictParsing' => true,
           'showScriptName' => false,
           'rules' => [
               ['class' => 'yii\rest\UrlRule', 'controller' => 'user'],
           ],
       ],
   ],

   Esta configuração ativa a análise de entrada JSON e define regras de roteamento para o controlador User.
3. Configure o Servidor Web (Opcional). Para servidores Apache, crie um arquivo .htaccess dentro da pasta api/web com o seguinte conteúdo:

   RewriteEngine On
   RewriteCond %{REQUEST_FILENAME} !-f
   RewriteCond %{REQUEST_FILENAME} !-d
   RewriteRule . index.php

   Este arquivo direciona todas as requisições para o arquivo principal index.php do Yii2.

3. Testando os Endpoints da API

Uma vez que a configuração esteja completa, você pode testar os endpoints da API criados. Aqui estão alguns métodos de teste comumente usados.

1. Usando Postman. Baixe e instale o Postman. Crie uma nova requisição usando o método GET e a URL: http://localhost/[nome-do-seu-projeto]/api/web/users. Se for bem-sucedido, você receberá uma resposta JSON contendo dados do usuário.
2. Usando cURL. Execute o seguinte comando em um terminal ou prompt de comando:

   curl -H "Accept: application/json" "http://localhost/[nome-do-seu-projeto]/api/web/users"

3. Acesso via Navegador. Abra a URL do endpoint em um navegador. No entanto, este método geralmente é adequado apenas para testes simples de requisições GET.

Ao completar todos os passos acima, você construiu com sucesso uma API RESTful básica no Yii2. Para desenvolvimento posterior, considere adicionar mecanismos de autenticação (como JWT), autorização, limitação de taxa e uma boa documentação da API. Consulte sempre a documentação oficial do Yii2 para garantir que sua implementação siga as melhores práticas atuais.