3. Criando um Endpoint CRUD

Este guia mostra o passo a passo para criar um endpoint de API completo com todas as operações básicas: Listar, Visualizar, Criar, Atualizar e Deletar (CRUD).

Passo 1: Criando um Controller com Funções CRUD

Ao invés de criar toda a lógica do zero, nossa API utiliza a classe ApiResourceController, que já vem com as funcionalidades de CRUD prontas.

Crie seu arquivo de controller em app/controller/ com a seguinte estrutura:

// Em: app/controller/ApiCRUDController.php

class ApiCRUDController extends ApiResourceController
{
    // Configurações virão aqui
}

Configuração Essencial

Sendo uma classe-filha de ApiResourceController, no mínimo, você precisa informar ao controller qual modelo de dados e qual banco de dados ele deve usar.

• $model: O nome da sua classe de modelo (que estende TRecord). Nota: No ambiente MadBuilder, essas classes são geradas automaticamente a partir do seu banco de dados e ficam em app/model/.
• $database: O nome do arquivo de configuração da conexão (sem a extensão .php) localizado em app/config/.
• As demais configurações são opcionais e serão explicadas mais adiante.

class ApiCRUDController extends ApiResourceController
{
    protected $model = 'MeuModelo';
    protected $database = 'minha_conexao';
}

Abaixo, um exemplo de como minha_conexao.php poderia ser:

// Em: app/config/minha_conexao.php

return [
    'host' => 'localhost',
    'user' => 'meu_usuario',
    'pass' => 'minha_senha',
    'type' => 'sqlite',
    'port' => '3306',
    'name' => 'app/database/m.db',
    'fkey' => '0',
    'prep' => '1',
    'slog' => 'SystemSqlLogService'
];

---

Passo 2: Registrando as Rotas no Router

Com o controller pronto, o passo final é ligar os métodos dele (index, show, etc.) aos endereços HTTP. Volte ao arquivo app/routes/api.php e adicione as rotas para o seu recurso:

// Em: app/routes/api.php

Router::group([
    'prefix' => 'api/crud',
    // Caso necessário, adicione um middleware aqui
], function () {
    Router::get('/',    'ApiCRUDController::index');      // Listar todos os registros
    Router::get('/{id}', 'ApiCRUDController::show');      // Buscar um registro
    Router::post('/',   'ApiCRUDController::store');      // Criar novo registro
    Router::put('/{id}',  'ApiCRUDController::update');   // Atualizar registro
    Router::patch('/{id}', 'ApiCRUDController::update');  // Atualizar registro parcialmente
    Router::delete('/{id}','ApiCRUDController::destroy'); // Deletar registro
});

E pronto! Com isso, você tem um endpoint CRUD totalmente funcional.

---

Passo 3: Testando as Rotas

Assim como no anteriormente, os testes serão realizados através do Postman API com a variável de ambiente base_url definida como http://localhost/teste.

Para este exemplo, foi criado um grupo de rotas (como o presente acima) para o endpoint /api/pedido-venda.

Abaixo, veja a requisição HTTP POST realizada enviando os valores para um novo registro. O formato recomendado para enviar dados é o JSON:

Após isso, faremos uma requisição HTTP GET para buscar todos os registros:

E o resultado:

Observação: este exemplo utiliza uma base de dados com 809 registros. Como, por padrão, a ApiResourceController retorna 15 registros por página, faz-se necessário enviar o parâmetro page para acessar a 54ª, e última, página — diferentes bases de dados podem requerer configurações diferentes.

É possível alterar essa configuração, mas veremos isso mais adiante.

Digamos que, após analisar os dados retornados, tenhamos identificado que houve um erro de digitação no campo valor_total do novo registro (ID 809). Vamos então corrigir esse erro:

E o resultado:

Observação: uma requisição PUT utilizaria o mesmo endpoint (informando o ID do registro que deseja atualizar), com a exceção de que o corpo da requisição deve conter todos os dados do registro, mesmo os que não mudaram.

Aliás, da forma que configuramos as rotas, informar o ID numa requisição GET traria o registro correspondente.

O cliente cancelou o pedido? Então, vamos deletar o registro que acabamos de criar (ID 809):

Em caso de sucesso, você deve receber a seguinte resposta:

Ao realizar novamente aquela mesma requisição GET, é possível perceber que o registro foi deletado, e ao pé da resposta, as seguintes informações:

Aliás, esta chave (meta) obtida via método index é de grande importância, pois nela constam:

• total: Quantidade de registros;
• per_page: Quantidade de registros por página;
• current_page: Página atual;
• last_page: Última página;

É com essas informações que é possível, por exemplo, executar os comandos SQL LIMIT e OFFSET para retornar os registros de uma página específica, entre outros.

Por fim, podemos concluir que as operações CRUD estão funcionando corretamente.