O Laravel facilita a interação com APIs para desenvolvedores web, sejam eles novatos ou experientes. O cliente HTTP do Laravel é construído com base no cliente HTTP Guzzle do PHP, proporcionando uma experiência mais fluida ao fazer solicitações HTTP. Suas principais funcionalidades incluem autenticação, roteamento e um mapeamento objeto-relacional (ORM) eficaz.

Este artigo vai explorar como usar o cliente HTTP do Laravel para fazer requisições, depurar respostas, criar middleware e macros, entre outros.

O Cliente HTTP do Laravel Facilita o Trabalho com APIs

O Guzzle é um cliente HTTP simples para PHP. Ele oferece funcionalidade para diferentes solicitações de formulário, incluindo GET, POST, PUT e DELETE, juntamente com os recursos de streaming e solicitações de várias partes. Com o cliente HTTP Guzzle, você pode enviar solicitações síncronas e assíncronas para o servidor. Além disso, ele também vem com um middleware decente para personalizar o comportamento do cliente.

O cliente HTTP do Laravel é um wrapper criado com base no Guzzle, mas com funcionalidades adicionais. Ele inclui suporte para novas tentativas de solicitações com falha e algumas funções auxiliares com dados JSON. A maioria das funcionalidades dos clientes HTTP do Laravel é semelhante à do Guzzle.

Pré-requisitos

Nas seções a seguir, você aprenderá mais sobre o cliente HTTP do Laravel. Para acompanhar, você precisará de:

  • Conhecimento básico de Laravel, PHP e APIs
  • PHP e Composer instalados
  • Postman

Como fazer solicitações

Para entender como usar um cliente HTTP para fazer uma solicitação, você pode aproveitar várias APIs hospedadas, como a ReqRes.

Comece importando o pacote HTTP incluído na criação do aplicativo. Dentro do arquivo App/Http/Controllers/UserController.php, adicione o seguinte código, começando com a declaração de uso no início do arquivo e o código restante dentro da função index.

use Illuminate\Support\Facades\Http;
return Http::get("https://reqres.in/api/users?page=2");

Observação: para casos de uso complexos, você também pode enviar a solicitação com cabeçalhos usando o método withHeaders.

No mesmo arquivo, crie um novo método post usando o código abaixo:

function post()
{
    $response = Http::withHeaders([
        'Content-Type' => 'application/json',
    ])->post('https://reqres.in/api/users', [
        'name' => 'morpheus',
        'job' => 'leader',
    ]);
    return $response;
}

Em seguida, adicione uma rota para ele dentro do arquivo routes/web.php:

Route::get('post',[UserController::class,'post']);

Agora, o Postman pode ser usado para testar essa rota. Abra o Postman e adicione http://127.0.0.1:8000/post como URL, com o tipo de solicitação como GET. Após clicar em enviar, você verá a seguinte resposta:

Fazendo solicitações usando o Postman.
Fazendo solicitações usando o Postman.

Solicitações simultâneas

As solicitações simultâneas melhoram significativamente o desempenho, pois você pode buscar mais dados no mesmo período. O cliente HTTP do Laravel permite que você realize solicitações simultâneas usando o método pool.

Dentro de App/Http/Controllers/UserController.php, adicione o seguinte código:

use Illuminate\Http\Client\Pool;
function concurrent()
{
    $responses = Http::pool(fn (Pool $pool) => [
        $pool->get('https://reqres.in/api/users?page=2'),
        $pool->get('https://reqres.in/api/users/2'),
        $pool->get('https://reqres.in/api/users?page=2'),
    ]);

    return $responses[0]->ok() &&
        $responses[1]->ok() &&
        $responses[2]->ok();
}

Em seguida, adicione a rota de suporte dentro do arquivo routes/web.php.

Route::get('concurrent',[UserController::class,'concurrent']);

O navegador fornece a seguinte resposta quando a rota é visitada:

Solicitações simultâneas
Solicitações simultâneas

Macros de solicitação

As macros de solicitação são úteis quando você interage com caminhos comuns de API.

Para criar a macro, você precisa definir a macro dentro do método de inicialização do arquivo app/Http/Providers/AppServiceProvider.php usando o código abaixo:

use Illuminate\Support\Facades\Http;
Http::macro('reqres', function () {
    return Http::baseUrl('https://reqres.in/api');
});

Observação: Certifique-se de adicionar a instrução de uso no início do arquivo.

Em seguida, use a macro dentro do site UserController adicionando o seguinte código:

function macro()
{
    $response = Http::reqres()->get('/users?page=2');
    return $response;
}

Como você pode ver, como a macro já está sendo criada, não é necessário adicionar a URL completa novamente.

Por fim, adicione uma rota no arquivo routes/web.php usando o código abaixo:

Route::get('macro',[UserController::class,'macro']);
Solicitação de macro
Solicitação de macro

Como decodificar respostas

Para decodificar uma resposta e garantir que uma solicitação de API seja bem-sucedida, você usa o método de status incluído no cliente. Esse método obtém o código de status enviado pelo servidor e o exibe.

Para testar isso, substitua o código de macro anterior pelo código abaixo dentro do arquivo App/Http/Controllers/UserController.php:

function macro()
{
    $response = Http::reqres()->get('/users?page=2');
    return $response->status();
}

Aqui, o código de status 200 significa que a solicitação foi bem-sucedida.

Resposta de decodificação bem-sucedida
Resposta de decodificação bem-sucedida

Como testar APIs JSON

O Laravel tem vários auxiliares para você testar as APIs JSON e suas respostas. As funções auxiliares incluem json, getJson, postJson, putJson, patchJson, deleteJson e assim por diante.

Para entender melhor o teste, crie um cenário de teste para a rota do usuário GET. Quando você inicializa o aplicativo Laravel, o teste de exemplo já está criado. Dentro do arquivo tests/Feature/ExampleTest.php, substitua o código existente pelo seguinte:

<?php
namespace Tests\Feature;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
class ExampleTest extends TestCase
{
    /**
     * A basic test example.
     *
     * @return void
     */
    public function test_example()
    {
        $response = $this->getJson('/users');

        $response->assertStatus(200);
    }
}

O código adicionado busca os dados JSON na rota do usuário e verifica se o código de status é 200 ou não.

Depois que você tiver adicionado o código de teste, execute o seguinte comando em seu terminal para executar os testes:

./vendor/bin/phpunit

Quando os testes forem concluídos, você verá que ele executou dois testes, ambos bem-sucedidos.

Teste de APIs JSON
Teste de APIs JSON

Da mesma forma, você pode verificar diferentes tipos de solicitações e utilizar outros métodos auxiliares para testes mais sofisticados.

Como lidar com eventos

O Laravel oferece três eventos a serem disparados quando você lida com solicitações HTTP.

  • RequestSending, que ocorre antes da solicitação ser enviada.
  • ResponseReceived, que ocorre quando uma resposta é recebida.
  • ConnectionFailed, que ocorre quando uma resposta é recebida.

Todos os três eventos incluem a propriedade $request para inspecionar a instância Illuminate\Http\Client\Request, e o ResponseReceived tem um $response property adicional. Esses eventos são particularmente úteis para a execução de ações após um evento. Por exemplo, você pode querer enviar um e-mail após obter uma resposta bem-sucedida.

Para criar um evento e um ouvinte, navegue até o arquivo app/Providers/EventServiceProvider.php e substitua a array listen pelo seguinte código.

protected $listen = [
    Registered::class => [
        SendEmailVerificationNotification::class,
    ],
    'Illuminate\Http\Client\Events\ResponseReceived' => [
        'App\Listeners\LogResponseReceived',
    ],
];

Em seguida, execute o seguinte comando em seu terminal:

php artisan event:generate

O comando acima criará o listener app/Listeners/LogResponseReceived.php. Substitua o código desse arquivo pelo código abaixo:

<?php
namespace App\Listeners;
use Illuminate\Http\Client\Events\ResponseReceived;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Log;
class LogResponseReceived
{
    /**
     * Create the event listener.
     *
     * @return void
     */
    public function __construct(Request $request, Response $response)
    {
        Log::channel('stderr')->info($response->status());
    }

    /**
     * Handle the event.
     *
     * @param  \Illuminate\Http\Client\Events\ResponseReceived  $event
     * @return void
     */
    public function handle(ResponseReceived $event)
    {
        
    }
}

O registro de informações do código de status é impresso no terminal.

Registros do terminal mostrando o código de status.
Registros do terminal mostrando o código de status.

 

Resumo

Seja um site ou aplicativo web criado por uma organização, ou um desenvolvedor independente, as APIs são essenciais para o seu sucesso. No entanto, utilizá-las pode ser difícil.

Muitas frameworks e bibliotecas prometem simplificar esse processo, mas o Laravel se destaca por seu foco na simplicidade e facilidade de uso. Seu cliente integrado oferece suporte a chamadas de API fáceis, chamadas de API simultâneas, macros de API, métodos auxiliares para APIs baseadas em JSON e muito mais.

Steve Bonisteel Kinsta

Steve Bonisteel é um Editor Técnico na Kinsta que começou sua carreira de escritor como jornalista impresso, cobrindo ambulâncias e caminhões de bombeiros. Ele tem coberto tecnologia relacionada à Internet desde o final dos anos 1990.