Kako da koristite ugrađen Laravel-ov klijent za interakciju sa eksternim API-jima

Laravel omogućava laku integraciju API-ja, zahvaljujući svom HTTP klijentu koji je izgrađen na PHP-ovom Guzzle HTTP klijentu. Neke od glavnih funkcionalnosti ovog klijenta uključuju autentifikaciju, rutiranje i efektivno objektno-relaciono mapiranje (ORM).

U ovom tekstu ćemo objasniti kako da koristite Laravelov HTTP klijent za pravljenje zahteva (request), debagovanje odgovora, kreiranje middleware-a i makroa i još mnogo toga.

Guzzle je jednostavan HTTP klijent za PHP. Dolazi sa funkcionalnostima za različite zahteve poput get, post, put i delete, zajedno sa mogućnostima za streaming i višedelne zahteve.

Takođe, sa Guzzle HTTP klijentom moguće je i slanje sinhronih i asinhronih zahteva ka serveru.

Kako smo pomenuli, Laravelov HTTP klijent je izgrađen na Guzzle klijentu, ali ima i neke dodatne funkcionalnosti. Između ostalog to su podrška za ponovno slanje neuspešnih zahteva i neke helper funkcije sa JSON podacima.

Ipak, većina funkcionalnosti koje postoje u okviru Laravelovog HTTP klijenta su slične onima koje dolaze sa Guzzle klijentom.

Kako da napravite zahtev (request)

Da biste razumeli kako da koristite HTTP klijent da napravite zahtev, možete da iskoristite neki od hostovanih API-ja, poput ReqRes.

Započnite sa importom HTTP paketa uključenog prilikom kreiranja aplikacije.

Otvorite App/Http/Controllers/UserController.php fajl i dodajte kod ispod, ali obratite pažnju da statement use treba da ide na početku fajla, a ostatak koda unutar funkcije index.

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

Napomena: Za složenije slučajeve, možete takođe poslati zahtev sa header-ima korišćenjem withHeaders metode.

U istom fajlu kreirajte novi post metod korišćenjem sledećeg koda

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

Zatim dodajte rutu unutar routes/web.php fajla:

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

Sada možete da upotrebite Postman da testirate navedenu rutu. Otvorite Postman i kao URL unesite https://127.0.0.1:8000/post, sa tipom zahteva Get. Kada kliknete send videćete sledeći odgovor:

Konkurentni zahtevi

Paralelni zahtevi značajno unapređuju performanse s obzirom da istovremeno možete fetch-ovati više podataka. Laravelov HTTP klijent omogućava izvršavanje konkurentnih zahteva, korišćenjem pool metoda.

Unutar App/Http/Controllers/UserController.php fajla dodajte sledeći kod:

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();
}

Zatim unutar routes/web.php fajla dodajte rutu:

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

Browser će vratiti sledeći odgovor kada je ruta otvorena:

Request makroi

Request makroi su korisni kada je potrebno da imate interakciju sa API putanjama

Da biste kreirali makro, potrebno je da definišete makro unutar boot metoda app/Http/Providers/AppServiceProvider.php fajla, korišćenjem sledećeg koda:

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

Napomena: Obratite pažnju da statement use dodate na početak fajla. Zatim iskoristite makro unutar userController dodavanjem sledećeg koda:

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

Kao što možete da vidite, pošto je makro već kreiran, nema potrebe da ponovo dodajete punu URL adresu. Na kraju u routes/web.php fajl dodajte rutu pomoću sledećeg koda:

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

U browser-u ćete dobiti sledeći odgovor:

Kako da dekodirate odgovore

Da biste dekodirali odgovor (response) i uverili se da je API zahtev uspešan, potrebno je da koristite status metod koji se nalazi u klijentu.

Ovaj metod dobija i prikazuje status kod koji je poslat sa servera.

Da biste ovo testirali, zamenite prethodni makro kod sa kodom ispod (unutar App/Http/Controllers/UserController.php fajla).

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

U ovom slučaju status kod 200 znači da je zahtev uspešan.

Kako da testirate JSON API-je

Laravel ima nekoliko helpera za testiranje JSON API-ja i njihovih odgovora. Helper funkcije uključuju json, getJson, postJson, patchJson, deleteJson … itd.

Da biste bolje razumeli testiranje, kreirajte scenario za get korisničke rute. Kada pokrenete Laravel aplikaciju, Example Test je već kreiran. Unutar tests/Feature/ExampleTest.php fajla zamenite postojeći kod sa sledećim kodom:

<?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);
    }
}

Dodat kod fetch-uje JSON podatke u korisničkoj ruti i proverava da li je status kod 200. Kada ste dodali testni kod, startujte sledeću komandu u svom terminalu da biste pokrenuli test:

./vendor/bin/phpunit

Kada se test završi, videćete da je pokrenuo dva testa, od kojih su oba bila uspešna:

Slično ovome možete probati i drugačije tipove zahteva i uključiti druge helper metode za sofisticiranije testove.

Kako da upravljate event-ima

Laravel nudi tri event-a koja mogu biti pokrenuta kada radite sa HTTP zahtevima:

RequestSending – pre nego što se zahtev pošalje
ResponseReceived – kada je odgovor primljen
ConnectionFailed – kada odgovor nije primljen

Sva tri event-a uključuju svojstvo (property) $request za proveru Illuminate\Http\Client\Request instance, a ResponseReceived dodatno ima $response property. Oni su posebno korisni za izvođenje akcija nakon event-a. Na primer, možda želite da pošaljete email nakon uspešnog odgovora.

Da biste kreirali event i listener, idite u app/Providers/EventServiceProvider.php fajl i zamenite niz pod nazivom listen sa sledećim kodom:

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

Zatim pokrenite sledeću komandu u svom terminalu:

php artisan event:generate

Ova komanda će kreirati app/Listeners/LogResponseReceived.php listener. Zamenite kod iz tog fajla sa sledećim kodom:

<?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)
    {
        
    }
}

Info log status koda je print-an u terminalu:

Zaključak

Bez obzira da li se web aplikacija razvija od strane neke kompanije ili od strane pojedinca, API je važan faktor koji će znatno unaprediti razvoj i funkcionalnost svake aplikacije.

Za to mogu poslužiti mnogi framework-ovi i biblioteke, ali Laravel se izdvaja zbog lakoće i bogatih funkcionalnosti koje čine ovaj popularan framework. Između ostalog, ugrađeni klijent podržava pozivanja API-ja, konkurentne API pozive, API makroe, helper metode za API-je bazirane na JSON-u i još mnogo toga.