Construindo e consumindo uma API RESTful no Laravel 9 (parte 1)

Neste tutorial, usaremos a versão mais recente do Laravel, versão 9, para criar uma API de back-end RESTful e disponibilizar seus endpoints. E O front-end será JavaScript puro que fará algumas requisições a nossa API.

Para tornar a didática mais atrativa vamos criar uma simples aplicação de lista de tarefas, o famoso “TODO” em inglês. Ao final termos uma API com os endpoints para consultar, alterar e incluir tarefas.

O Laravel é proeminentemente um framework PHP do lado do servidor. Este tutorial serve como uma introdução ao Laravel API. Em um aplicativo Web moderno, o servidor tem um trabalho limitado de gerenciar o back-end por meio de alguns pontos de extremidade de API (Application Programming Interface). O cliente envia solicitações para esses terminais e o servidor retorna uma resposta. No entanto, o servidor não se preocupa com como o cliente renderiza a visualização, o que se enquadra perfeitamente no princípio da Separação de Responsabilidade. Essa arquitetura permite que os desenvolvedores construam aplicativos robustos para a web e também para diferentes dispositivos.

Antes de começar com o Laravel, certifique-se de ter instalado o PHP e o Composer em sua máquina local. Usamos o Composer para gerenciar todas as dependências. Ao instalar o Composer em sua máquina, certifique-se de escolher a opção para adicioná-lo à variável de ambiente path para que o Composer seja acessível globalmente.

Vamos criar nosso projeto com o comando a baixo.

composer create-project laravel/laravel api-laravel-app

Apos o projeto criado entre na pasta do projeto e inicie a servidor para testarmos se está tudo ok.

// entrar na pasta do projeto
cd api-laravel-app

// startar o servidor
php artisan serve

Se tudo ocorreu bem iremos obter no navegador algo semelhante à tela a baixo.

OBS.: Neste momento você poderá obter alguns erros, os mais comuns são: permissão de pastas/arquivos ou alguma Lib./biblioteca necessária do PHP que não foi instalada na versão corrente. Então basta dar as permissões necessárias e instalar as dependências que falta que tudo irá ocorrer bem.

Para este exemplo estamos usando PHP v8.1 e Laravel v9.37

Artisan é uma ferramenta de linha de comando para quem trabalha com Laravel. O Artisan aceita uma grande lista de comandos que permitem gerar código para seu aplicativo. Execute php artisan list para ver todos os comandos de artesãos disponíveis.

Configurando o Ambiente

Seu aplicativo terá um arquivo (.env) dentro do diretório raiz. Todas as informações de configuração específicas do ambiente são declaradas aqui. Crie um banco de dados para seu aplicativo, caso ainda não o tenha feito, e adicione os detalhes do banco de dados ao arquivo (.env)

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=tododb
DB_USERNAME=root
DB_PASSWORD=

Aqui estamos conectando um banco de dados chamado tododb ao aplicativo. Esse banco de dados está hospedado no MySQL, que está sendo executado localmente (ou seja, http://127.0.0.1 ) na porta 3306. O nome de usuário do banco de dados é root e a senha está vazia. Este é o nome de usuário e senha padrão para bancos de dados MySQL.

Rotas da nossa aplicação.

Quando o servidor recebe uma requisição HTTP, o Laravel tenta combiná-la com uma rota registrada dentro de qualquer um dos arquivos de rota. Todos os arquivos de rotas estão localizados dentro do diretório de rotas, routes/web.php hospeda a rota para a interface da web, enquanto routes/api.php hospeda a rota para a API. As rotas registradas em api.php serão prefixadas com /api(como em localhost:3000/api). Se você precisar alterar esse comportamento, vá para a RouteServiceProviderclasse em /app/Providers/RouteServiceProvider.php e faça as alterações lá.

Como estamos construindo um aplicativo de listagem de tarefas, aqui estão os endpoints para a API e as ações HTTP associadas a esses endpoints.

• GET /tarefas/: Recupera todos as tarefas.
• GET /tarefa/{id}: Recupera a tarefa que corresponde ao id.
• POST /tarefas: Crie uma nova tarefa e insere no banco de dados.
• PUT /tarefas/{id}: Atualize uma tarefa existente que corresponda ao id.
• DELETE /tarefas/{id}: Exclui a tarefa com o dado id.

Vamos acertar a terminologia. GET, POST, PUT e DELETE são os verbos HTTP (mais conhecidos como métodos HTTP) essencialmente necessários para construir um serviço RESTful. /tarefas é o URI associado ao recurso de tarefas. Os métodos HTTP solicitam que o servidor execute a ação desejada em um determinado recurso.

O Model

O recurso de tarefas precisa de um modelo que possa interagir com o banco de dados. Modelo é a camada que fica no topo do banco de dados. O Laravel usa o Eloquent ORM para modelar o banco de dados.

“O Eloquent ORM incluído no Laravel fornece uma implementação bonita e simples do ActiveRecord para trabalhar com seu banco de dados. Cada tabela de banco de dados tem um “Modelo” correspondente que é usado para interagir com essa tabela. Os modelos permitem consultar dados em suas tabelas, bem como inserir novos registros na tabela. — Documentos Laravel“

E a definição do esquema do banco de dados? A migração do Laravel cuida disso. O Artisan possui um comando de migração que permite definir seu esquema e atualizá-lo de forma incremental em um estágio posterior. Vamos criar um modelo e uma migração para a entidade Tarefa.

$ php artisan make:model Tarefa -m

Aqui está o arquivo de migração gerado em database/migrations/timestamp_create_tarefas_table.php

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('tarefas', function (Blueprint $table) {
            $table->id();
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists('tarefas');
    }
};

O método up é chamado durante a migração de novas tabelas e colunas para o banco de dados, enquanto ometodo down é chamado durante a reversão de uma migração. Criamos um Schema para uma tabela com três linhas: id, created_at e updated_at. O $table->timestamps() método é responsável por manter as colunas created_at e updated_at Vamos adicionar mais algumas linhas à definição do esquema.

Então vamos deixar nosso método up assim:

 
public function up()
 {
     Schema::create('tarefas', function (Blueprint $table) {
         $table->increments('id');
         $table->timestamps();
         $table->text('descricao');
         $table->boolean('concluido');
     });
 }

Sendo assim, ao final nossa tabela terá os campos: chave identificadora, data de criação, data de alteração, campo de descrição e um campos de controle se a tarefa está concluída ou não.

O Model Tarefa

Por convenção, o Laravel assume que o modelo Tarefa está associado à tabela de tarefas . No entanto, se você precisar associar o modelo a um nome de tabela customizado, poderá usar a propriedade $table para declarar o nome da tabela. O modelo será então associado a uma tabela chamada nome_customizado .

Este código deve estar em app/Models/Tarefa.php:

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
 
class Tarefa extends Model
{
    use HasFactory;
     
    // caso queira mudar o nome padrão da tabela:
    protected $table = 'tarefa_lista';
}

Mas vamos manter as coisas simples e seguir a convenção. O modelo de Tarefa gerado está localizado dentro do diretório app/. Embora a classe de modelo possa parecer vazia, ela vem equipada com vários métodos de criação de consultas que você pode usar para consultar o banco de dados. Por exemplo, você pode usar Tarefa::all() para recuperar todos as tarefas ou Tarefa::find(1) para recuperar uma determinada tarefa com id 1.

Os modelos Laravel possuem um mecanismo de proteção embutido contra vulnerabilidade de atribuição em massa . A fillable propriedade é usada para declarar os nomes de atributos que podem ser atribuídos em massa com segurança.

/* Adicionar o fillable property em nosso Tarefa Model */
 
protected $fillable = ['descricao', 'concluido'];

O código acima lista os atributos descricao e concluido e os trata como atribuíveis em massa.priceavailability

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Tarefa extends Model
{
    use HasFactory;
    
    protected $fillable = ['descricao', 'concluido'];
}

Por fim, execute o comando a seguir para executar as migrações pendentes.

php artisan migrate

Este comando criará as tabelas padrão (por exemplo, usuários, migrações) e a tabela que você definiu (tarefas) dentro do banco de dados tododb que definimos anteriormente como o banco de dados do aplicativo no arquivo (.env) .

Definição da tabela tarefas

Agora podemos usar o método Tarefa::create para inserir novas linhas na tabela de tarefas.

Populando a tabela tarefas – Database Seeding

O Laravel permite preencher seu banco de dados de desenvolvimento e produção com dados fictícios que você pode usar para testar seus endpoints de API. Você pode criar uma classe seed executando o seguinte comando Artisan.

$ php artisan make:seeder TarefasTableSeeder

Os arquivos semeadores gerados serão colocados no diretório database/seeders .

Para gerar os dados fictícios, você pode usar algo assim str_random(10) que retorna uma string aleatória. Mas se você precisar de dados próximos o suficiente dos dados reais, use algo como a biblioteca faker. Faker é uma biblioteca de terceiros que é fornecida com o framework Laravel para gerar dados falsos.

Aqui está uma classe semeadora para gerar dados de semente. Deve ir em database/seeders/TarefasTableSeeder.php

<?php

namespace Database\Seeders;

use App\Models\Tarefa;
use Illuminate\Database\Seeder;

class TarefasTableSeeder extends Seeder
{
    /**
     * Run the database seeds.
     *
     * @return void
     */
    public function run()
    {
        $faker = \Faker\Factory::create();
 
        // criar 50 registros de tarefas
        for ($i = 0; $i < 50; $i++) {
            Tarefa::create([                
                'descricao' => $faker->paragraph,
                'concluido' => $faker->boolean(50)
            ]);
        }
    }
}

$ php artisan db:seed --class=TarefassTableSeeder

Aqui está o resultado:

Com nosso Model ok e com nossa tabela populada com exemplos ficticios já poderiamos fazer testes com com nossa routes/api.php maas antes vamos criar nosso controller. Mas esta vai ficar para a parte 02 para este post não ficar muito extenso.

No próximo post vamos finalizar nossa dica com o controller, rota e utilização da API, continua…