Guia passo a passo para construir uma API RESTful com Laravel

Nessa série de artigos veja como construir uma API RESTful para consulta de usuários em uma base de dados com ajuda do frawework Laravel. Mostrei como montar toda estrutura necessária, da instalação e banco de dados aos controllers e autenticação por token com JWT.

Vamos entender primeiro alguns conceitos, antes de começarmos o desenvolvimento, começando pelo que é API.

API’s

API significa “Application Programming Interface”, que em tradução para o português significa “Interface de Programação de Aplicações”, ou seja, uma API é simplesmente uma interface de comunicação entre aplicações, ela serve para prover dados para outras aplicações, sejam elas internas ou externas.

Através das APIs, os aplicativos podem se comunicar uns com os outros sem conhecimento ou intervenção dos usuários. Elas funcionam através da comunicação de diversos códigos, definindo comportamentos específicos de determinado objeto em uma interface. A API liga as diversas funções em um site de maneira que possam ser utilizadas em outras aplicações.

Sobre o REST

REST significa Representational State Transfer que em português significa, Transferência de Estado Representacional, trata-se de uma abstração da arquitetura World Wide Web.

O REST consiste em um conjunto de regras que, quando seguidas, permitem a criação de um projeto com interfaces bem definidas que possibilita a comunicação previsível entre que aplicações. Ele usa integralmente mensagens HTTP para se comunicar através do que já é definido no protocolo sem precisar “inventar” novos protocolos específicos para aquela aplicação.

RESTful, é somente a capacidade de determinado sistema, de implementar o REST.

As transações RESTful são identificadas através de métodos: GET. POST, PUT, DELETE e etc

Em https://http.cat/ , existe uma lista completa dos métodos, e suas aplicações.

E para quem gosta mais de dogs tem também https://httpstatusdogs.com/

Sobre o Laravel

O Laravel é um Framework, com sintaxe elegante e expressiva, que tem como principal característica ajudar a desenvolver aplicações seguras e robustas de forma ágil e eficiente, com uma documentação vasta e acessível, tornando fácil e rápido o desenvolvimento.

É um framework PHP open source que segue o padrão de arquitetura MVC (model-view-controller), com o objetivo de permitir que você trabalhe de forma rápida e estruturada. Entre suas principais características estão, documentação intuitiva, curva de aprendizado baixa, modularidade e um conjunto muito rico em recurso, dentre muitas para a segurança da aplicação .

Instalação do Laravel

Vamos utilizar o Composer para criar nosso novo projeto.

É possível instalar o Laravel através de clone do projeto no github, mas você irá precisar rodar o comando composer update para que ele faça toda a instalação das dependências.

composer create-project laravel/laravel apiLaravel

Com esse comando ele baixa a última versão estável do framework, conforme a versão do php instalada na máquina. No momento da escrita deste post a versão é 5.4 para o php 5.6 e a versão 5.5 do Laravel para o php 7.

Quando a instalação terminar abra o arquivo criado com seu editor de preferência.

Antes de começarmos a desenvolver nossa API será preciso fazer uma pequena alteração para evitar problemas com as requisições.

Por padrão a versão 5 do Laravel vem com um middleware para prevenção de CSRF, o VerifyCsrfToken. Precisamos removê-lo e para fazer isso precisamos acessar o arquivo Kernel.php em App/Http/Kernel.php e remover a seguinte linha App\Http\Middleware\VerifyCsrfToken::class.

protected $middlewareGroups = [
 'web' => [

   \App\Http\Middleware\EncryptCookies::class,
   \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
   \Illuminate\Session\Middleware\StartSession::class,
// \Illuminate\Session\Middleware\AuthenticateSession::class,
   \Illuminate\View\Middleware\ShareErrorsFromSession::class,
   \App\Http\Middleware\VerifyCsrfToken::class,
   \Illuminate\Routing\Middleware\SubstituteBindings::class,
 ],

Banco de Dados

Agora já estamos prontos para criar nosso banco de dados. Eu utilizo Postgresql, mas você pode usar o Mysql ou até mesmo o sqlite se preferir, pois o Laravel suporta eles. 

Criar o banco:

create database api;

Criar usuário e senha

 create user api password 'api';  

Atribui o usuário ao banco:

alter database api owner to api;

Não vou detalhar muito a parte de criação de bancos, pois, como falei acima, você pode escolher outro para trabalhar.

Com o nosso banco criado, iremos mudar o arquivo de configuração. Para isso renomeie o arquivo .env.example para .env e nele iremos adicionar nossas configurações de banco.

DB_CONNECTION=pgsql
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=api
DB_USERNAME=api
DB_PASSWORD=api

O Laravel por padrão utiliza o Mysql, como estou utilizando postgres, preciso  informá-lo disso no arquivo config/database.php, precisando somente alterar a linha abaixo:

'default' => env('DB_CONNECTION', 'pgsql')

Migrations

Migrações são controles de versão para o seu banco de dados, permitindo que sua equipe modifique facilmente e compartilhe a estrutura do banco de dados com todos envolvidos no projeto, com as migrations iremos desenvolver todas as tabelas do nosso banco de dados no código, podendo assim versioná-los e manter o histórico de todas as alterações feitas no banco.

Criando Migrations:

php artisan make:migration create_users_table

Ao executar o comando acima, um arquivo é criado em database/migration. Vamos acessar esse arquivo pela IDE, e alterá-lo para criar a nossa tabela Users.

<?php
use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class CreateUsersTable extends Migration
{
   /**
    * Run the migrations.
    * @return void
    */
   public function up()
   {
       Schema::create('users', function (Blueprint $table) {
           $table->increments('id');
           $table->string('name', 100);
           $table->string('email', 60);
           $table->integer('phone');
           $table->integer('cel');
           $table->string('gender', 10);
           $table->date('dob');
           $table->timestamps();
           $table->softDeletes();
       });
   }
  /**
    * Reverse the migrations.
    * @return void
    */
   public function down()
   {
       Schema::dropIfExists('users');
   }
}

Agora é só rodar o comando abaixo, para que nossa tabela seja criada:

 php artisan migrate

Model

As models são responsáveis pela leitura e escrita de dados, com suas validações.

Criando a Model:

 php artisan make:model Users

Após isso iremos proteger nossas colunas no arquivo criado em App/Users.php.

<?php
namespace App;

use Illuminate\Database\Eloquent\SoftDeletes;
use Illuminate\Database\Eloquent\Model;

class Users extends Model
{
   use SoftDeletes;
 
   protected $fillable = ['name','email','phone','cel','gender','dob'];

   protected $dates = ['deleted_at'];

}

Vamos entender o código acima:

use Illuminate\Database\Eloquent\SoftDeletes;

Na linha acima faço a importação do SoftDeletes. O softDeletes é super interessante, pois,ele não deixa que nenhum registro seja realmente deletado no nosso banco, o que ele fará é colocar a data que o registro foi deletado, assim, qualquer exclusão errada será facilmente revertida.

use SoftDeletes;

Na linha acima, informo que a minha model irá utilizar o softDeletes.

protected $dates = ['deleted_at'];

E finalmente passo qual das colunas ele deve popular, quando o registro for deletado.

SEEDS

Seeds são sementes, com ele você  “semeia” o banco de dados, ou seja você popula as suas tabelas para que não inicie em branco, nós precisaremos testar as requisições da API e para isso precisaremos de dados, com os seeds, não precisamos inserir esses dados diretamente no banco.  

 php artisan make:seeder UsersTableSeeder

Abra o arquivo database/seeds/UserTableSeeder e vamos criar os nossos usuários fake.

<?php
use Illuminate\Database\Seeder;
class UsersTableSeeder extends Seeder
{
   /**
    * Run the database seeds.
    *
    * @return void
    */
   public function run()
   {
      DB::table('users')->insert([
           'name'  =>  'Maria da Silva',
           'email' => 'mariasilva1830@gmail.com',
           'phone' => '1144445555',
           'cel'   => '1199998888',
           'gender'=> 'feminino',
           'dob'   => '1830-01-01',
      ]);
      DB::table('users')->insert([
           'name'  =>  'Luiza da Silva',
           'email' => 'luizadasilva1930@gmail.com',
           'phone' => '1144445555',
           'cel'   => '1199998888',
           'gender'=> 'feminino',
           'dob'   => '1930-01-01',
      ]);
   }
}

Para inserirmos esses dados no banco, temos primeiro que modificar o arquivo database/seeds/DatabaseSeeder.php e incluir uma chamada a nossa Seeder criada

<?php
use Illuminate\Database\Seeder;
class DatabaseSeeder extends Seeder
{
   /**
    * Run the database seeds.
    *
    * @return void
    */
   public function run()
   {
       $this->call(UsersTableSeeder::class);
   }

}

E rodar o comando:   

php artisan db:seed 

Que os nossos registros fake, serão criados. Faça um select no seu banco, para verificar, caso queira.

Obs: Criei dois usuários apenas, como exemplo, mas aqui podemos criar vários usuários, ele não tem um limite.

Obs2: Para quem já conhece seeds, e já tem alguma familiaridade com o Laravel pode utilizar o package Faker:https://github.com/fzaninotto/Faker que faz o mesmo processo acima, de popular a base de dados.

No próximo post iremos ver Controller, Rotas, Status code, retorno de erro e nossa API começando a funcionar. Até o próximo post…