Skip to main content

​
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: Requisição POST Postman API Após isso, faremos uma requisição HTTP GET para buscar todos os registros: Requisição GET Postman API E o resultado: Resposta GET Postman API
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: Requisição PATCH Postman API E o resultado: Resposta PATCH Postman API
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): Requisição DELETE Postman API Em caso de sucesso, você deve receber a seguinte resposta: Resposta DELETE Postman API 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: Resposta GET Postman API 2 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.