API Restful, conceitos e exemplo prático.

30/06/2022 root

Olá, mundo!Tudo bem?

Nos dias atuais existem uma enxurrada de informações, vídeos, até mesmo cursos voltados para este conceito. Que nada mais é de uma forma de comunicação, nada moderna, já idealizada com o Modelo OSI (Open System Interconnection) em 1971.

Afinal, o que é uma API (Application Programming Interface) e o termo Restful? Vejamos a tabela do modelo proposto pelo Modelo OSI:

CAMADA	FUNÇÃO
7 – Aplicação	Funções especialistas (transferência de arquivos, envio de e-mail, terminal virtual).
6 – Apresentação	Formatação dos dados, conversão de códigos e caracteres (compressão e criptografia).
5 – Sessão	Negociação e conexão com outros nós, analogia.
4 – Transporte	Oferece métodos para a entrega de dados ponto-a-ponto.
3 – Rede	Roteamento de pacotes em uma ou várias redes.
2 – Enlace	Detecção de erros.
1 – Física	Transmissão e recepção dos bits brutos através do meio físico de transmissão.

Fonte: Tabela obtida no Wikipedia, acesso em https://pt.wikipedia.org/wiki/Modelo_OSI .

Quando falamos sobre API, nos remete a interoperabilidade, ou seja, queremos que Sistemas de linguagens, Sistema Operacionais distintos, até mesmo Banco de Dados e/ou informações, cuja as fontes de dados são divergentes, tenham a devida comunicação. Esta é a real importância e significado de uma API. Não é raro vermos Sistemas em que você realiza a pesquisa de um CEP e retorna, de maneira automática, o preenchimento de seu endereço. Esta função é exercida com o uso de uma API.

E o que seria o Restful?A comunicação em Sistema Web se faz através da representatividade de estado (REST – Representational state transfer), calma! Eu explico, sem melindres e charlatanismo!

Toda requisição Web se faz através de protocolo, correto?Para tal, utilizamos o protocolo HTTP. (Tá bom, vão falar que usam o HTTPS, que apenas tem uma funcionalidade de proteger o cabeçalho, o payload da mensagem com segurança). Desfeito estes mitos, vamos em frente!

Utilizamos os verbos: GET, PUT, POST, PATCH, DELETE, HEAD, nossa aplicação de exemplo, será uma base de cliente, e fará o famoso CRUD (Create, Read, Update e Delete), em português: Criação, Leitura, Atualização e Apagar. Munido destes preceitos básicos, vejamos abaixo os verbos HTTP, especificado e suas respectivas funções na aplicação:

VERBO HTTP	CRUD	ENDPOINTS (/cLIENTEs)
POST	Create	Nosso endpoint direcionará no Controller Clientes /clientes o qual irá gerar um novo registro
GET	Read	Neste endpoint iremos pegar uma coleção completa com o método All() do Eloquent e também um outro endpoint /clientes/{id}, que retornará o registro que quisermos filtrar, baseando-se na chave primária do registro.
PUT	Update	Este endpoint terá a incumbência de alterar o registro, baseado na rota /clientes/{id}
DELETE	Delete	Este endpoint apagará o registro no banco, baseado na rota /clientes/{id}

Vamos dar início aos trabalhos, criando uma aplicação Laravel! ; )

composer create-project laravel/laravel laravel_api

entramos na pasta do projeto /laravel_api

criamos nosso banco de Dados:

mysql -u root -p

CREATE DATABASE laravel_api;

Voltamos para nossa pasta do projeto e façamos a edição do arquivo .env do Laravel.

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_api
DB_USERNAME=root
DB_PASSWORD=<senha do banco de dados>

Vamos criar a classe de Modelo e com a flag -m para a criação da migração para o banco de dados.

php artisan make:model Cliente -m

Vamos até a pasta /app/Models/Cliente.php

<?php

namespace App\Models;

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

class Cliente extends Model
{
    protected $table = 'clientes';

    protected $fillable  = ['nome', 'telefone'];

}

Agora iremos alterar nossa migração na pasta /laravel_api/database/migrations/2022_06_30_170531_create_clientes_table.php

<?php

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

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

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

Vamos rodar a migração para criação da tabela no banco de dados:

php artisan migrate

Com o banco devidamente criado, vamos agora criar o Controller que atenderá as requisições.

php artisan make:controller ClientesApiController

Vamos incluir os seguintes métodos em nosso Controller, vamos até a pasta /laravel_api/app/Http/Controllers/ClientesApiController.php

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Models\Cliente;


class ClientesApiController extends Controller
{
    public function getAllClientes() {
        // iremos pegar a coleção de todos os clientes aqui
        $clientes = Cliente::get()->toJson(JSON_PRETTY_PRINT);
        return response($clientes, 200);
      }
  
      public function createCliente(Request $request) {
        // Criação do Cliente com Active Record Pattern
        $cliente = new Cliente;
        $cliente->nome = $request->nome;
        $cliente->telefone = $request->telefone;
        $cliente->save();

        //Retorna em JSON a resposta e a mensagem de "Registro de cliente criado"
        return response()->json([
            "mensagem" => "Registro de Cliente criado"
        ], 201);
      }
  
      public function getCliente($id) {
        // Verifica se o registro existe, caso exista, pega a coleção e tranforma em JSON, caso não encontre
        // retorna com "Cliente não encontrado!"
        if (Cliente::where('id', $id)->exists()) {
            $cliente = Cliente::where('id', $id)->get()->toJson(JSON_PRETTY_PRINT);
            return response($cliente, 200);
          } else {
            return response()->json([
              "mensagem" => "Cliente não encontrado!"
            ], 404);
          }
      }
      
  
      public function updateCliente(Request $request, $id) {
        // Verifica se o cliente existe, caso exista pega as informações, trata se for valor nulo com o ternário (ambos os valores cliente,telefone)
        // ao final salva com o método Active Record Pattern e mostra a mensagem "Registros atualizados com sucesso!"
        // Caso não há registro retorna a mensagem "Cliente não encontrado!"
        if (Cliente::where('id', $id)->exists()) {
            $cliente = Cliente::find($id);
            $cliente->nome = is_null($request->nome) ? $cliente->nome : $request->nome;
            $cliente->telefone = is_null($request->telefone) ? $cliente->telefone : $request->telefone;
            $cliente->save();
    
            return response()->json([
                "mensagem" => "Registros atualizados com sucesso!"
            ], 200);
            } else {
            return response()->json([
                "mensagem" => "Cliente não encontrado!"
            ], 404);
            
        }
      }
  
      public function deleteCliente ($id) {
        // método para apagar um cliente, verifica se o registro existe. Caso exista efetua a remoção com método delete().
        // Caso não exista, retorna a mensagem "Cliente não encontrado!"
        if(Cliente::where('id', $id)->exists()) {
            $cliente = Cliente::find($id);
            $cliente->delete();
    
            return response()->json([
              "mensagem" => "Registros apagados!"
            ], 202);
          } else {
            return response()->json([
              "mensagem" => "Cliente não encontrado!"
            ], 404);
          }
        
      }
}

Agora vamos colocar no arquivo de rotas do Laravel, nossas endpoints que iremos consumir. /laravel_api/routes/api.php

<?php

use App\Http\Controllers\ClientesApiController;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

/*
|--------------------------------------------------------------------------
| API Routes
|--------------------------------------------------------------------------
|
| Here is where you can register API routes for your application. These
| routes are loaded by the RouteServiceProvider within a group which
| is assigned the "api" middleware group. Enjoy building your API!
|
*/

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});


Route::get('clientes', [ClientesApiController::class, 'getAllClientes']);
Route::get('clientes/{id}',  [ClientesApiController::class, 'getCliente']);
Route::post('clientes', [ClientesApiController::class],'createCliente');
Route::put('clientes/{id}', [ClientesApiController::class],'updateCliente');
Route::delete('clientes/{id}', [ClientesApiController::class, 'deleteCliente']);

Antes de testar nossa aplicação, vamos criar alguns clientes para nossa base experimental:

php artisan make:seed ClienteSeeder

Vamos até a pasta de nossa Seeder criada /laravel_api/database/seeders/ClienteSeeder.php

<?php

namespace Database\Seeders;

use Illuminate\Database\Console\Seeds\WithoutModelEvents;
use Illuminate\Database\Seeder;
use App\Models\Cliente;

class ClienteSeeder extends Seeder
{
    /**
     * Run the database seeds.
     *
     * @return void
     */
    public function run()
    {
        $clientes = [ ["nome" => "Thiago Cantero",
                      "telefone" => "1199999999"], 
                      ["nome" => "Mario Bros",
                      "telefone" => "1122222222"],
                      ["nome" => "ElePHant",
                      "telefone" => "11233232"],
                      ["nome" => "Yoshi",
                      "telefone" => "11222212"]          
                ];

                foreach ($clientes as $key => $value) { 
                    Cliente::create($value);        
                    }
    }
}

agora vamos executar o comando para popular nossa seeder no banco:

php artisan db:seed --class=ClienteSeeder

Os dados estão na base:

Por fim, vamos testar nossa aplicação. No meu ambiente utilizo o insomnia

Façamos o comando:

php artisan serve

Abrimos o Isomnia, e façamos a rota de acesso a coleção, que em nosso Controller está no método getAllClientes().

Nossa API já está funcionando, ela retorna toda as coleções que fizemos na seed. Vamos pegar um registro apenas, informando o id “4”, este método é o getCliente() de nosso Controller.

Pegamos o registro Yoshi do nosso banco de dados.

Agora vamos apagar o primeiro registro de nossa base de dados. No caso o Id “1”. Que chamará o método deleteCliente() de nosso Controller.

Façamos o chamado de todas nossa coleções novamente.

Perfeito, nossa API está funcional e pronta para ser consumida. É óbvio que este exemplo tem apenas o intuito de demonstrar para que serve uma API e o tais termos REST e RESTFul.
Espero que tenha ajudado.

Código fonte no github.

Sofrer, é só uma vez; vencer, é para a eternidade.

Soren Kierkegaard

VERBO

HTTP

CRUD

ENDPOINTS (/cLIENTEs)