Catatan Tutorials

API dan integrasi

Memanggil sistem lain, dan dipanggil oleh sistem lain. Apa itu API, JSON, kenapa setiap request butuh timeout, cara mencoba ulang yang benar, rate limit, pagination, idempotency key supaya percobaan ulang tidak menagih dua kali, dan verifikasi webhook. Dijalankan terhadap mock API kecil, di Python dan PHP.

7 menit bacaTersedia juga dalam bahasa Inggris →

Hampir tidak ada aplikasi yang bekerja sendirian lagi. Aplikasi mengirim email lewat satu layanan, menerima pembayaran lewat layanan lain, mengecek ongkir ke kurir, sinkron dengan sistem akuntansi, dan mungkin memanggil model AI. Masing-masing adalah API. Kode integrasi adalah tempat banyak bug production yang paling sulit berada, karena sekarang Anda bergantung pada sistem yang tidak Anda kendalikan, lewat jaringan yang kadang gagal.

Bagian 18 membahas HTTP itu sendiri. Bagian ini membahas cara memakainya untuk berbicara dengan sistem lain secara andal.

API adalah kontrak

MDN: “An API (Application Programming Interface) is a set of features and rules that exist inside a software program (the application) enabling interaction with it through software - as opposed to a human user interface.” API adalah sekumpulan fitur dan aturan di dalam sebuah program yang memungkinkan program lain berinteraksi dengannya, bukan lewat antarmuka untuk manusia. Dan gagasan kuncinya: “The API can be seen as a simple contract (the interface) between the application offering it and other items”: API bisa dilihat sebagai kontrak sederhana antara aplikasi penyedia dan pihak lain.

Ini gagasan yang sama dengan fungsi di bagian 7 atau abstraksi di bagian 11: input, output, dan janji, dengan bagian dalam yang tersembunyi. Bedanya, fungsi ini berjalan di komputer orang lain, bisa lambat, bisa mati, dan bisa berubah.

Kebanyakan API web hari ini bertukar data dalam JSON: “JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.” JSON adalah format teks standar untuk data terstruktur. Isinya objek, array, string, angka, boolean, dan null. Semua bahasa bisa membaca dan menulisnya.

Contoh-contoh di bawah dijalankan terhadap mock API kecil di mesin lokal, yang sengaja dibuat bermasalah: satu endpoint lambat, satu gagal dua kali sebelum berhasil, satu membatasi jumlah request, dan satu menerima pembayaran.

Aturan 1: setiap request butuh timeout

Dokumentasi requests terus terang: “By default, requests do not time out unless a timeout value is set explicitly. Without a timeout, your code may hang for minutes or more.” Secara bawaan request tidak punya batas waktu, dan tanpa timeout kode Anda bisa menggantung selama bermenit-menit atau lebih. Dan: “Most requests to external servers should have a timeout attached, in case the server is not responding in a timely manner.”

try:
    requests.get(f"{BASE}/slow", timeout=2)
except requests.Timeout:
    print("slow: gave up after 2 s")
slow: gave up after 2 s

Tanpa timeout=2 itu, satu mitra yang lambat bisa membuat semua worker aplikasi Anda ikut menunggu. Di PHP dengan curl, pasang timeout koneksi sekaligus timeout total:

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 2,
    CURLOPT_TIMEOUT => $timeoutSeconds,
]);
GET http://127.0.0.1:8098/slow failed: Operation timed out after 2002 milliseconds with 0 bytes received
GET http://127.0.0.1:8098/nope returned HTTP 404

Perhatikan bahwa curl, seperti fetch di bagian 18, tidak menganggap 404 sebagai kegagalan dengan sendirinya. Pembungkusnya yang memeriksa status dan melempar exception, sesuai bagian 13.

Aturan 2: coba ulang hanya yang layak dicoba ulang

Sebagian kegagalan bersifat sementara: 503 saat pihak sana sedang restart, gangguan jaringan sesaat, timeout. Mencoba lagi sebentar kemudian sering berhasil. Sebagian lagi permanen: 400 karena request Anda salah, 401 karena key-nya tidak valid. Mencoba ulang yang seperti itu hanya mengulang kesalahan.

Retry sederhana dengan exponential backoff: tunggu sebentar, lalu dua kali lebih lama, lalu dua kali lebih lama lagi, supaya layanan yang sedang kewalahan tidak terus dihantam:

def get_with_retry(url, attempts=4):
    for attempt in range(1, attempts + 1):
        res = requests.get(url, timeout=5)
        if res.status_code == 429:
            wait = int(res.headers.get("Retry-After", "1"))
        elif res.status_code >= 500:
            wait = 0.2 * 2 ** (attempt - 1)
        else:
            return res
        print(f"  attempt {attempt}: {res.status_code}, waiting {wait} s")
        time.sleep(wait)
    res.raise_for_status()
  attempt 1: 503, waiting 0.2 s
  attempt 2: 503, waiting 0.4 s
flaky: {'ok': True, 'attempt': 3}

Dua kali gagal, lalu berhasil, dan pemanggilnya tidak pernah tahu. Kode sungguhan biasanya menambahkan sedikit unsur acak (“jitter”) pada waktu tunggu supaya banyak client tidak mencoba ulang bersamaan, dan membatasi total waktu yang dihabiskan.

Rate limit: 429 dan Retry-After

Kebanyakan API membatasi seberapa sering Anda boleh memanggilnya. “The HTTP 429 Too Many Requests client error response status code indicates the client has sent too many requests in a given amount of time.” Status 429 berarti client mengirim terlalu banyak request dalam rentang waktu tertentu. Dan: “A Retry-After header may be included to this response to indicate how long a client should wait before making the request again.” Header Retry-After bisa menyertainya untuk memberi tahu berapa lama harus menunggu.

Fungsi retry di atas sudah menghormatinya:

  attempt 1: 429, waiting 1 s
limited: {'ok': True}

Kalau Anda terus terkena batas, perbaikannya biasanya ada di hulu: simpan hasil di cache, kirim request secara berkelompok, atau berhenti memanggil API di dalam loop (bentuk yang sama dengan query di dalam loop dari bagian 10 dan 11).

Pagination: selalu ada lanjutannya

API jarang mengembalikan semua data sekaligus. API mengembalikan satu halaman dan memberi tahu cara mengambil halaman berikutnya, lewat nomor halaman, cursor, atau link next. Melupakan ini adalah bug klasik: integrasinya berjalan sempurna saat testing dengan 20 data, lalu diam-diam mengabaikan semua setelah halaman pertama di production.

products, page = [], 1
while page:
    body = requests.get(f"{BASE}/products", params={"page": page}, timeout=5).json()
    products += body["data"]
    page = body["next_page"]
products: 7 [1, 2, 3, 4, 5, 6, 7]

Tujuh produk di tiga halaman, masing-masing berisi tiga. Versi yang hanya membaca response pertama akan melaporkan tiga.

Idempotency: mencoba ulang tanpa membayar dua kali

Mencoba ulang GET tidak berbahaya. Mencoba ulang POST /payments berbahaya. Kalau request-nya timeout, Anda tidak tahu apakah pembayarannya sudah masuk, dan mengirimnya lagi bisa menagih pelanggan dua kali.

API pembayaran menyelesaikan ini dengan idempotency key. Dokumentasi Stripe: “The API supports idempotency for safely retrying requests without accidentally performing the same operation twice.” API mendukung idempotency supaya request bisa dicoba ulang dengan aman tanpa menjalankan operasi yang sama dua kali. Dan: “A client generates an idempotency key, which is a unique key that the server uses to recognize subsequent retries of the same request.” Client membuat key unik yang dipakai server untuk mengenali percobaan ulang dari request yang sama.

Mock API tadi mendukung header yang sama. Mengirim pembayaran yang sama dua kali, tanpa dan dengan key:

headers = {"Idempotency-Key": key} if key else {}
requests.post(f"{BASE}/payments", json={"amount": 150000}, headers=headers, timeout=5)
payments without key: sent twice → ids [1001, 1002]
payments with key: sent twice → ids [1003, 1003]

Tanpa key, dua pembayaran. Dengan key, server mengenali percobaan ulang itu dan mengembalikan hasil yang pertama. Buat key-nya sekali per operasi (UUID, atau sesuatu yang terkait dengan ID pesanan Anda), simpan bersama pesanannya, dan pakai lagi di setiap percobaan ulang. Kalau Anda membangun API yang membuat sesuatu, pertimbangkan untuk menyediakan hal yang sama.

Webhook: saat mereka yang memanggil Anda

Polling (“pembayarannya sudah selesai belum?”) membuang-buang request. Banyak layanan malah mengirim webhook: sebuah POST HTTP ke URL yang Anda sediakan saat sesuatu terjadi. Sekarang Anda yang menjadi server, dan siapa pun di internet bisa mengirim request ke URL itu. Jadi Anda wajib memastikan request itu benar-benar dari layanan tersebut.

Cara yang umum adalah tanda tangan (signature): layanan menghitung HMAC dari body request dengan rahasia yang diketahui kedua pihak, lalu mengirimnya di sebuah header. Dokumentasi GitHub: “You can use a webhook secret to verify that a webhook delivery is from GitHub.” dan “GitHub uses an HMAC hex digest to compute the hash.” Kebanyakan payment gateway dan platform SaaS memakai skema tanda tangan serupa; header, algoritma, dan bagian yang ditandatangani berbeda-beda, jadi cek dokumentasi masing-masing penyedia.

def is_valid(body, header):
    expected = "sha256=" + hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)
genuine:  True
tampered: False

Ubah satu karakter di body dan tanda tangannya tidak lagi cocok. Dua detail yang penting:

  • Hitung HMAC dari byte body mentah, persis seperti yang diterima, sebelum JSON-nya diurai.
  • Bandingkan dalam waktu konstan. compare_digest “uses an approach designed to prevent timing analysis by avoiding content-based short circuiting behaviour”, tidak berhenti lebih awal berdasarkan isi sehingga tidak bisa dianalisis lewat waktu. == biasa bisa berhenti di karakter pertama yang berbeda, dan perbedaan waktunya bisa membocorkan informasi.

Di PHP, padanannya hash_equals, sebuah “Timing attack safe string comparison”:

$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
var_dump(hash_equals($expected, $header));                          // bool(true)
var_dump(hash_equals($expected, 'sha256=' . str_repeat('0', 64)));  // bool(false)

Bersiaplah juga menerima webhook yang sama lebih dari sekali; layanan akan mencoba ulang kalau Anda tidak menjawab cukup cepat. Tangani setiap event secara idempoten (cek apakah ID event itu sudah pernah diproses), jawab cepat dengan 2xx, dan kerjakan hal yang lambat sesudahnya.

Kebiasaan untuk kode integrasi

  • Jauhkan rahasia dari kode. API key dan rahasia webhook disimpan di environment variable atau secret manager, jangan pernah di repository (bagian 16).
  • Bungkus setiap API eksternal di satu tempat. Satu modul atau class per layanan, dengan timeout, retry, dan penanganan error di dalamnya. Kode lain cukup memanggil courier.shipping_rate(...), bukan HTTP mentah.
  • Validasi apa yang kembali. Data dari luar adalah input. Pastikan field-nya ada dan bertipe sesuai harapan sebelum dipakai, sama seperti input pengguna.
  • Catat request dan response di log (tanpa rahasia atau data pribadi), dengan ID yang bisa dicari. Saat mitra bilang “kami tidak pernah menerimanya”, log adalah bukti Anda.
  • Baca dokumentasi soal batas dan versi. Rate limit, ukuran halaman, tanggal penghentian. API berubah; kunci versi yang Anda pakai.
  • Tes dengan tiruan. Mock seperti di bagian ini membuat Anda bisa menguji timeout, retry, dan response yang aneh tanpa memanggil layanan sungguhan.

Kenapa ini penting sehari-hari

  • Jaringan pasti gagal. Timeout dan retry adalah pembeda antara mitra yang lambat dan aplikasi Anda sendiri yang ikut lumpuh total.
  • Uang dan duplikasi. Idempotency key yang mencegah percobaan ulang berubah jadi tagihan ganda atau pengiriman ganda.
  • Keamanan. URL webhook yang tidak diverifikasi adalah jalan bagi siapa pun untuk menandai pesanan sebagai lunas.
  • Kode integrasi hasil AI sering melewatkan timeout, mengabaikan pagination, dan membandingkan tanda tangan dengan ==. Semua itu sekarang masuk daftar periksa Anda.

Coba sendiri

  1. Cari semua panggilan HTTP keluar di proyek yang Anda kerjakan. Apakah masing-masing punya timeout?
  2. Tulis client untuk API publik yang memakai pagination, dan pastikan semua halamannya terbaca.
  3. Tambahkan idempotency key ke operasi di kode Anda yang membuat sesuatu (pesanan, pembayaran, pengiriman email).
  4. Implementasikan verifikasi tanda tangan webhook untuk layanan yang Anda pakai, lalu uji dengan body yang sudah diubah.

Ringkasan

  • API adalah kontrak antar-program; kebanyakan API web bertukar JSON lewat HTTP.
  • Selalu pasang timeout. Tanpanya, mitra yang lambat bisa membuat aplikasi Anda menggantung.
  • Coba ulang kegagalan sementara (5xx, timeout, 429) dengan backoff; jangan coba ulang kesalahan 4xx.
  • Hormati rate limit dan Retry-After; kurangi panggilan dengan cache dan pengelompokan.
  • Ikuti pagination sampai habis.
  • Pakai idempotency key supaya percobaan ulang tidak mengulang efek sampingnya.
  • Verifikasi webhook dengan HMAC dari body mentah dan perbandingan waktu konstan; tangani duplikasi.
  • Bungkus setiap API di satu tempat, jauhkan rahasia dari kode, validasi response, dan catat di log.

Referensi