Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / REST API, Integrasi & Automation / Cara Mengintegrasikan Laravel...
REST API, Integrasi & Automation

Cara Mengintegrasikan Laravel dengan API Eksternal Menggunakan HTTP Client

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
13 min read
11 views

Integrasi yang tahan gangguan: class klien khusus per layanan, timeout dan retry yang tepat, penanganan error yang diterjemahkan ke bahasa domain, cache, pembatasan laju permintaan keluar, circuit breaker sederhana, log yang tidak membocorkan secret, request paralel, dan test yang tidak pernah memanggil layanan sungguhan.

Overview

Aplikasi RW bergantung pada beberapa layanan luar: API data wilayah (provinsi sampai kelurahan) untuk formulir alamat, payment gateway, dan penyedia WhatsApp. Panggilan HTTP ke layanan luar sering ditulis langsung di controller:

$res = Http::get('https://api.wilayah.contoh/kelurahan?kecamatan='.$request->kec);
return $res->json();

Kode seperti ini bermasalah ketika kondisi tidak ideal:

Kondisi Akibat pada kode naif
Layanan lambat (30 detik) Worker PHP tertahan; aplikasi ikut lambat untuk semua pengguna
Layanan error 503 sesaat Pengguna langsung melihat error, padahal percobaan ulang akan berhasil
Layanan mati berjam-jam Setiap request tetap menunggu timeout; antrean menumpuk
Struktur respons berubah Error Undefined array key jauh di dalam view
Kuota/rate limit penyedia Akun diblokir sementara
Log mencatat request lengkap Token API ikut tersimpan di log
Test memanggil layanan asli Test lambat, tidak stabil, dan bisa mengubah data sungguhan

Hasil akhir: integrasi dengan API wilayah dan pola umum untuk layanan lain:

  • konfigurasi per layanan di config/services.php,
  • class klien dengan timeout, retry selektif, dan error domain,
  • DTO untuk respons sehingga perubahan format terdeteksi di satu tempat,
  • cache untuk data yang jarang berubah,
  • pembatas laju dan circuit breaker,
  • log yang aman,
  • test dengan Http::fake() dan larangan request tak terduga.

Prerequisites

Komponen Versi
PHP 8.3+ (disarankan 8.4)
Laravel 13.x (HTTP Client berbasis Guzzle sudah termasuk)
Cache Redis (disarankan)
Testing Pest 4

Step-by-step Tutorial

Langkah 1: Konfigurasi Layanan

// config/services.php
'wilayah' => [
    'base_url'        => env('WILAYAH_BASE_URL', 'https://api.wilayah.contoh/v1'),
    'token'           => env('WILAYAH_TOKEN'),
    'timeout'         => (int) env('WILAYAH_TIMEOUT', 5),          // detik total
    'connect_timeout' => (int) env('WILAYAH_CONNECT_TIMEOUT', 2),  // detik untuk membuka koneksi
    'cache_ttl'       => 60 * 60 * 24 * 7,                          // data wilayah jarang berubah
],
# .env
WILAYAH_BASE_URL=https://api.wilayah.contoh/v1
WILAYAH_TOKEN=

Secret hanya di .env dan dibaca lewat config() (artikel Cara Mengelola Secret, API Key, dan Credential Database Laravel).

Langkah 2: Tentukan Timeout dengan Sadar

HTTP Client Laravel memiliki timeout bawaan 30 detik. Untuk request yang berjalan di dalam request pengguna, angka itu terlalu besar.

Konteks Timeout yang wajar
Dipanggil saat pengguna menunggu (formulir, halaman) 2–5 detik
Dipanggil di queue job 10–30 detik
Unduhan file besar di job Sesuai ukuran, dengan sink() ke file

Selalu atur connectTimeout terpisah. Bila server tujuan tidak bisa dihubungi sama sekali, Anda ingin tahu dalam 2 detik, bukan menunggu timeout total.

Langkah 3: Class Klien Khusus

// app/Integrations/Wilayah/WilayahClient.php
namespace App\Integrations\Wilayah;

use App\Integrations\Wilayah\Data\Kelurahan;
use App\Integrations\Wilayah\Exceptions\{WilayahTidakTersedia, WilayahTidakDitemukan};
use Illuminate\Http\Client\{ConnectionException, PendingRequest, RequestException, Response};
use Illuminate\Support\Facades\{Cache, Http, Log};
use Illuminate\Support\Collection;

final class WilayahClient
{
    public function __construct(
        private readonly string $baseUrl,
        #[\SensitiveParameter] private readonly string $token,
        private readonly int $timeout,
        private readonly int $connectTimeout,
        private readonly int $cacheTtl,
    ) {}

    private function http(): PendingRequest
    {
        return Http::baseUrl($this->baseUrl)
            ->withToken($this->token)
            ->acceptJson()
            ->withUserAgent('RWDigital/2.3 (+https://rw.contoh.id)')
            ->timeout($this->timeout)
            ->connectTimeout($this->connectTimeout)
            ->retry(
                times: 3,
                sleepMilliseconds: fn (int $attempt) => [200, 600, 1500][$attempt - 1] ?? 1500,
                when: fn (\Throwable $e) => $this->bolehDiulang($e),
                throw: true,
            );
    }

    /** Ulangi hanya untuk gangguan sementara, bukan kesalahan permintaan */
    private function bolehDiulang(\Throwable $e): bool
    {
        if ($e instanceof ConnectionException) {
            return true;                                    // timeout, DNS, koneksi ditolak
        }

        if ($e instanceof RequestException) {
            return in_array($e->response->status(), [429, 502, 503, 504], true);
        }

        return false;
    }

    /** @return Collection<int, Kelurahan> */
    public function kelurahan(string $kodeKecamatan): Collection
    {
        if (! preg_match('/^\d{2}\.\d{2}\.\d{2}$/', $kodeKecamatan)) {
            throw new \InvalidArgumentException('Format kode kecamatan tidak valid.');
        }

        return Cache::remember(
            "wilayah:kelurahan:{$kodeKecamatan}",
            $this->cacheTtl,
            fn () => $this->ambilKelurahan($kodeKecamatan),
        );
    }

    private function ambilKelurahan(string $kodeKecamatan): Collection
    {
        try {
            $response = $this->http()->get('kelurahan', ['kecamatan' => $kodeKecamatan]);
        } catch (ConnectionException $e) {
            Log::warning('wilayah.koneksi_gagal', ['pesan' => $e->getMessage()]);
            throw new WilayahTidakTersedia('Layanan data wilayah tidak dapat dihubungi.', previous: $e);
        } catch (RequestException $e) {
            throw $this->terjemahkan($e->response, $e);
        }

        return collect($response->json('data', []))
            ->map(fn (array $row) => Kelurahan::fromApi($row));
    }

    private function terjemahkan(Response $response, \Throwable $e): \Throwable
    {
        Log::warning('wilayah.respon_gagal', [
            'status' => $response->status(),
            'body'   => mb_substr($response->body(), 0, 300),     // dipotong, tanpa header
        ]);

        return match (true) {
            $response->notFound()         => new WilayahTidakDitemukan('Kode wilayah tidak ditemukan.', previous: $e),
            $response->status() === 401   => new WilayahTidakTersedia('Kredensial layanan wilayah tidak valid.', previous: $e),
            default                       => new WilayahTidakTersedia('Layanan data wilayah sedang bermasalah.', previous: $e),
        };
    }
}

Keputusan penting di class ini:

  • Retry selektif. Percobaan ulang hanya untuk masalah koneksi dan status 429/502/503/504. Mengulang request yang ditolak karena data salah (400, 422) atau kredensial salah (401) hanya membuang waktu.
  • Backoff bertingkat (200 ms, 600 ms, 1,5 detik) agar tidak membebani layanan yang sedang kesulitan.
  • Error domain. Pemanggil menangkap WilayahTidakTersedia, bukan RequestException Guzzle. Bila suatu hari Anda mengganti penyedia data wilayah, kode pemanggil tidak berubah.
  • Validasi input sebelum dikirim. Kode kecamatan dicocokkan dengan pola sehingga input aneh tidak sampai ke layanan luar.
  • #[\SensitiveParameter] mencegah token muncul di stack trace.

Untuk request yang mengubah data di layanan luar (POST pembuatan transaksi, pengiriman pesan), berhati-hatilah dengan retry otomatis: request bisa sebenarnya berhasil di server tujuan tetapi respons terputus di jalan. Gunakan idempotency key bila penyedia mendukungnya, atau jangan ulang otomatis.

Http::withHeaders(['Idempotency-Key' => $pembayaran->uuid])->post('charges', $payload);

Langkah 4: DTO untuk Respons

// app/Integrations/Wilayah/Data/Kelurahan.php
namespace App\Integrations\Wilayah\Data;

final readonly class Kelurahan
{
    public function __construct(
        public string $kode,
        public string $nama,
        public ?string $kodePos,
    ) {}

    public static function fromApi(array $row): self
    {
        if (! isset($row['kode'], $row['nama'])) {
            throw new \UnexpectedValueException('Format data kelurahan dari layanan wilayah berubah.');
        }

        return new self(
            kode: (string) $row['kode'],
            nama: (string) $row['nama'],
            kodePos: isset($row['kode_pos']) ? (string) $row['kode_pos'] : null,
        );
    }
}

Bila penyedia mengubah nama field, error muncul di sini dengan pesan yang jelas, bukan di view sebagai Undefined array key.

// app/Integrations/Wilayah/Exceptions/WilayahTidakTersedia.php
namespace App\Integrations\Wilayah\Exceptions;

class WilayahTidakTersedia extends \RuntimeException {}
class WilayahTidakDitemukan extends \RuntimeException {}

Langkah 5: Daftarkan Klien di Container

// app/Providers/AppServiceProvider.php
use App\Integrations\Wilayah\WilayahClient;

public function register(): void
{
    $this->app->singleton(WilayahClient::class, fn () => new WilayahClient(
        baseUrl: config('services.wilayah.base_url'),
        token: (string) config('services.wilayah.token'),
        timeout: config('services.wilayah.timeout'),
        connectTimeout: config('services.wilayah.connect_timeout'),
        cacheTtl: config('services.wilayah.cache_ttl'),
    ));
}

Pemakaian di controller, dengan degradasi yang anggun bila layanan tidak tersedia:

// app/Http/Controllers/Api/V1/WilayahController.php
public function kelurahan(Request $request, WilayahClient $wilayah)
{
    $kode = $request->validate(['kecamatan' => ['required', 'regex:/^\d{2}\.\d{2}\.\d{2}$/']])['kecamatan'];

    try {
        $data = $wilayah->kelurahan($kode);
    } catch (WilayahTidakDitemukan) {
        return response()->json(['data' => []]);
    } catch (WilayahTidakTersedia $e) {
        return response()->json([
            'message' => 'Daftar kelurahan sementara tidak tersedia. Silakan ketik nama kelurahan secara manual.',
            'code'    => 'wilayah_tidak_tersedia',
        ], 503);
    }

    return response()->json(['data' => $data->map(fn ($k) => ['kode' => $k->kode, 'nama' => $k->nama, 'kode_pos' => $k->kodePos])]);
}

Formulir alamat tetap bisa dipakai (input manual) walaupun layanan wilayah sedang mati. Fitur pendukung tidak boleh menjatuhkan fitur utama.

Langkah 6: Batasi Laju Permintaan Keluar

Banyak penyedia membatasi jumlah request per menit. Melampauinya bisa membuat akun diblokir.

use Illuminate\Support\Facades\RateLimiter;

private function denganBatasLaju(\Closure $panggil): mixed
{
    $hasil = RateLimiter::attempt(
        key: 'keluar:wilayah',
        maxAttempts: 50,              // sesuai kuota penyedia per menit
        callback: $panggil,
        decaySeconds: 60,
    );

    if ($hasil === false) {
        throw new WilayahTidakTersedia('Batas permintaan ke layanan wilayah tercapai. Coba lagi sebentar.');
    }

    return $hasil;
}
$response = $this->denganBatasLaju(fn () => $this->http()->get('kelurahan', ['kecamatan' => $kode]));

Untuk pekerjaan massal (misalnya sinkronisasi ribuan data), jalankan di queue dengan middleware job RateLimited sehingga job menunggu giliran alih-alih gagal (lihat artikel Laravel Queue dan Job).

Langkah 7: Circuit Breaker Sederhana

Bila layanan mati berjam-jam, setiap request tetap menunggu timeout dan retry. Circuit breaker menghentikan percobaan sementara setelah beberapa kegagalan beruntun.

// app/Integrations/Support/CircuitBreaker.php
namespace App\Integrations\Support;

use Illuminate\Support\Facades\Cache;

final class CircuitBreaker
{
    public function __construct(
        private readonly string $nama,
        private readonly int $batasGagal = 5,
        private readonly int $tutupDetik = 60,
    ) {}

    public function terbuka(): bool
    {
        return Cache::has("cb:{$this->nama}:open");
    }

    public function sukses(): void
    {
        Cache::forget("cb:{$this->nama}:fails");
    }

    public function gagal(): void
    {
        Cache::add("cb:{$this->nama}:fails", 0, $this->tutupDetik * 2);
        $jumlah = Cache::increment("cb:{$this->nama}:fails");

        if ($jumlah >= $this->batasGagal) {
            Cache::put("cb:{$this->nama}:open", true, $this->tutupDetik);
            Cache::forget("cb:{$this->nama}:fails");
        }
    }

    public function jalankan(\Closure $panggil, \Closure $saatTerbuka): mixed
    {
        if ($this->terbuka()) {
            return $saatTerbuka();
        }

        try {
            $hasil = $panggil();
            $this->sukses();
            return $hasil;
        } catch (\Throwable $e) {
            $this->gagal();
            throw $e;
        }
    }
}
// di WilayahClient::kelurahan(): bungkus pemanggilan ambilKelurahan() dengan circuit breaker
return (new CircuitBreaker('wilayah'))->jalankan(
    fn () => $this->ambilKelurahan($kodeKecamatan),
    fn () => throw new WilayahTidakTersedia('Layanan wilayah sedang dinonaktifkan sementara.'),
);

Setelah 5 kegagalan beruntun, request berikutnya langsung gagal selama 60 detik tanpa menunggu timeout. Setelah itu, satu request dicoba lagi; bila berhasil, sirkuit kembali normal. Hanya kesalahan gangguan (koneksi/5xx) yang sebaiknya dihitung sebagai kegagalan, bukan 404.

Langkah 8: Request Paralel

Saat membutuhkan beberapa data independen sekaligus, kirim secara paralel:

use Illuminate\Http\Client\Pool;

$respons = Http::pool(fn (Pool $pool) => [
    $pool->as('provinsi')->withToken($token)->timeout(5)->get("{$base}/provinsi"),
    $pool->as('kabupaten')->withToken($token)->timeout(5)->get("{$base}/kabupaten", ['provinsi' => '32']),
]);

$provinsi = $respons['provinsi']->successful() ? $respons['provinsi']->json('data') : [];

Total waktu menjadi sekitar waktu request terlama, bukan jumlah semuanya. Periksa setiap respons secara terpisah karena sebagian bisa gagal.

Langkah 9: Log yang Berguna dan Aman

Gunakan event HTTP Client untuk mencatat metadata semua request keluar di satu tempat:

// app/Providers/AppServiceProvider.php
use Illuminate\Http\Client\Events\{ResponseReceived, ConnectionFailed};

Event::listen(ResponseReceived::class, function (ResponseReceived $e) {
    Log::channel('integrasi')->info('http.keluar', [
        'metode' => $e->request->method(),
        'host'   => parse_url($e->request->url(), PHP_URL_HOST),
        'path'   => parse_url($e->request->url(), PHP_URL_PATH),   // tanpa query string (bisa berisi kunci)
        'status' => $e->response->status(),
        'durasi_ms' => (int) (($e->response->handlerStats()['total_time'] ?? 0) * 1000),
    ]);
});

Event::listen(ConnectionFailed::class, fn (ConnectionFailed $e) =>
    Log::channel('integrasi')->warning('http.keluar.gagal', ['host' => parse_url($e->request->url(), PHP_URL_HOST)]));

Jangan pernah mencatat header Authorization, query string yang berisi api_key, atau body lengkap yang berisi data pribadi.

Jangan pernah menonaktifkan verifikasi SSL (withoutVerifying()) di production untuk "mengatasi" error sertifikat. Perbaiki penyebabnya: CA bundle server, tanggal sistem, atau sertifikat penyedia.

Langkah 10: Test Tanpa Menyentuh Layanan Asli

Larang semua request HTTP yang tidak dipalsukan di seluruh test:

// tests/Pest.php
uses()->beforeEach(fn () => \Illuminate\Support\Facades\Http::preventStrayRequests())->in('Feature', 'Unit');
// tests/Feature/Integrations/WilayahClientTest.php
use App\Integrations\Wilayah\WilayahClient;
use App\Integrations\Wilayah\Exceptions\WilayahTidakTersedia;
use Illuminate\Support\Facades\{Cache, Http};

beforeEach(fn () => Cache::flush());

it('memetakan respons ke DTO dan menyimpan di cache', function () {
    Http::fake([
        'api.wilayah.contoh/v1/kelurahan*' => Http::response(['data' => [
            ['kode' => '32.76.01.1001', 'nama' => 'Pancoran Mas', 'kode_pos' => '16431'],
        ]]),
    ]);

    $client = app(WilayahClient::class);
    $client->kelurahan('32.76.01');
    $hasil = $client->kelurahan('32.76.01');                  // dari cache

    expect($hasil->first()->nama)->toBe('Pancoran Mas');
    Http::assertSentCount(1);
    Http::assertSent(fn ($r) => $r->hasHeader('Authorization') && $r['kecamatan'] === '32.76.01');
});

it('mengulang saat 503 lalu berhasil', function () {
    Http::fakeSequence('api.wilayah.contoh/*')
        ->push([], 503)
        ->push(['data' => [['kode' => '1', 'nama' => 'A']]], 200);

    expect(app(WilayahClient::class)->kelurahan('32.76.01'))->toHaveCount(1);
    Http::assertSentCount(2);
});

it('tidak mengulang saat 401 dan melempar error domain', function () {
    Http::fake(['api.wilayah.contoh/*' => Http::response(['message' => 'Unauthorized'], 401)]);

    expect(fn () => app(WilayahClient::class)->kelurahan('32.76.01'))->toThrow(WilayahTidakTersedia::class);
    Http::assertSentCount(1);
});

it('mendeteksi perubahan format respons', function () {
    Http::fake(['api.wilayah.contoh/*' => Http::response(['data' => [['id' => '1', 'name' => 'A']]])]);

    expect(fn () => app(WilayahClient::class)->kelurahan('32.76.01'))->toThrow(\UnexpectedValueException::class);
});

it('endpoint tetap merespons rapi saat layanan mati', function () {
    Http::fake(['api.wilayah.contoh/*' => Http::failedConnection()]);   // simulasi koneksi gagal
    Sanctum::actingAs(User::factory()->create());

    $this->getJson('/api/v1/wilayah/kelurahan?kecamatan=32.76.01')
        ->assertStatus(503)
        ->assertJsonPath('code', 'wilayah_tidak_tersedia');
});

retry() di test akan benar-benar menunggu jeda backoff. Untuk mempercepat test, buat jeda bergantung pada konfigurasi (misalnya nol di lingkungan testing), atau gunakan Sleep::fake() bila jeda diimplementasikan dengan helper Sleep.

Troubleshooting

Error / Gejala Penyebab Solusi
cURL error 28: Operation timed out Layanan lambat atau timeout terlalu pendek Sesuaikan timeout per konteks; pindahkan ke queue bila memang lama
cURL error 6: Could not resolve host DNS server bermasalah atau URL salah Periksa base_url, DNS server, dan firewall keluar
cURL error 60: SSL certificate problem CA bundle usang atau sertifikat penyedia bermasalah Perbarui ca-certificates; jangan pakai withoutVerifying()
Request diulang padahal datanya salah Retry untuk semua status Batasi when ke error koneksi dan 429/5xx
Data ganda di layanan luar POST diulang otomatis setelah timeout Gunakan idempotency key atau hilangkan retry untuk request yang mengubah data
Test memanggil API sungguhan Ada request yang tidak di-fake Http::preventStrayRequests()
Token muncul di log Mencatat request/header lengkap Catat metadata saja; pakai #[\SensitiveParameter]
Akun penyedia diblokir Melampaui rate limit RateLimiter::attempt atau job RateLimited
Konfigurasi null di production env() dipanggil di luar config Baca lewat config('services.wilayah...')

Best Practices

Keamanan

  • Secret di .env, dibaca lewat config(), tidak pernah dicatat.
  • Verifikasi SSL selalu aktif.
  • Validasi input sebelum dikirim ke layanan luar, dan validasi respons sebelum dipakai.
  • Hanya kirim data pribadi yang benar-benar diperlukan penyedia.

Performa

  • Timeout pendek untuk panggilan sinkron; pekerjaan lambat di queue.
  • Cache data referensi yang jarang berubah.
  • Request paralel dengan Http::pool untuk data independen.
  • Circuit breaker agar layanan yang mati tidak memperlambat seluruh aplikasi.

Maintainability

  • Satu class klien per layanan, dengan DTO dan exception domain sendiri.
  • Retry selektif dan idempotency yang disengaja, bukan bawaan untuk semua.
  • Log metadata semua request keluar di satu tempat.
  • Test dengan Http::fake, fakeSequence, dan larangan request tak terduga.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
Guzzle 7.x
Redis 7.x
Pest 4.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya