Cara Mengintegrasikan Laravel dengan API Eksternal Menggunakan HTTP Client
Admin HijrahKreativa
Penulis
Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk
Admin HijrahKreativa
Penulis
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.
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:
config/services.php,Http::fake() dan larangan request tak terduga.| Komponen | Versi |
|---|---|
| PHP | 8.3+ (disarankan 8.4) |
| Laravel | 13.x (HTTP Client berbasis Guzzle sudah termasuk) |
| Cache | Redis (disarankan) |
| Testing | Pest 4 |
// 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).
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.
// 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:
WilayahTidakTersedia, bukan RequestException Guzzle. Bila suatu hari Anda mengganti penyedia data wilayah, kode pemanggil tidak berubah.#[\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);
// 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 {}
// 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.
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).
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.
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.
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.
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.
| 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...') |
Keamanan
.env, dibaca lewat config(), tidak pernah dicatat.Performa
Http::pool untuk data independen.Maintainability
Http::fake, fakeSequence, dan larangan request tak terduga.| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| Guzzle | 7.x |
| Redis | 7.x |
| Pest | 4.x |
| Tanggal | 19 Oktober 2026 |
Sebelumnya
API Versioning di Laravel: Strategi Menjaga Kompatibilitas Saat Aplikasi Berkembang
Berikutnya
Cara Mengintegrasikan Laravel dengan API Eksternal Menggunakan HTTP Client
Dokumen ini menjelaskan prosedur konfigurasi autentikasi SSH Key antara server Ubuntu dan GitHub untuk memungkinkan server melakukan operasi Git, seperti clone, pull, dan fetch tanpa menggunakan username dan password akun GitHub.
Peta jalan arsitektur dari satu server hingga banyak server: tahapan pertumbuhan dan sinyal kapan naik tahap, prinsip yang sebaiknya diterapkan sejak awal (stateless, asinkron, data ber-tenant), read replica, pengelolaan data yang terus tumbuh, degradasi yang anggun saat layanan bermasalah, feature...
Menyiapkan lingkungan uji yang jujur, mengukur satu endpoint dengan ApacheBench, mensimulasikan perilaku pengguna sungguhan dengan k6 (skenario, threshold, autentikasi token), menelusuri penyebab request lambat dengan Telescope, memantau server selama pengujian, serta menulis laporan hasil dan angga...
Bagaimana Octane membuat Laravel lebih cepat dengan mem-boot aplikasi sekali dan menyimpannya di memori, apa yang sebenarnya dipercepat (dan yang tidak), risiko kebocoran state antar-request yang wajib dipahami, cara memeriksa kode agar aman untuk Octane, pemasangan dengan FrankenPHP di production,...
03 Nov 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
HijrahKreativa
Kami balas secepatnya
Masuk dulu untuk chat dengan tim kami. Riwayat chat Anda tersimpan di akun.
Masuk