Modul 04Term 1 · Fondasi4 item poster

API dan Kontrak

Masuk untuk menyimpan progres Anda di semua perangkat. Sampai saat itu, progres disimpan di browser ini.

Mengapa ini penting

API adalah sebuah janji. Begitu aplikasi mobile, partner, atau agent bergantung padanya, setiap perubahan bisa merusak pihak yang tidak Anda lihat. Pembeli enterprise menilai Anda dari kualitas kontrak API Anda.

Capaian pembelajaran

  1. Merancang REST API yang konsisten dengan kontrak OpenAPI.
  2. Membuat setiap endpoint yang mengubah data menjadi idempotent.
  3. Memberi versi pada API dan library tanpa merusak client.
  4. Mengetahui kapan gRPC adalah tool yang tepat.

Materi

4.1 Desain contract-first

  • Tulis spec OpenAPI lebih dulu; generate type, client, dokumentasi, dan mock server darinya.
  • Konvensi yang konsisten: kata benda untuk resource, path jamak, status code standar, cursor pagination, timestamp ISO 8601.
  • Satu format error di semua tempat (RFC 9457 Problem Details): type, title, status, detail, ditambah request ID.
  • Validasi setiap input terhadap skema di boundary; tolak field yang tidak dikenal.
  • Jangan pernah mengembalikan field lebih banyak dari yang dibutuhkan (excessive data exposure adalah kerentanan API klasik).

4.2 Idempotency (14)

Jaringan bisa gagal setelah server menyelesaikan pekerjaannya tetapi sebelum client menerima balasan. Client lalu melakukan retry. Tanpa idempotency, pelanggan ditagih dua kali.

Pola (seperti yang dipopulerkan Stripe):

  1. Client mengirim Idempotency-Key: <uuid> pada POST.
  2. Server menyimpan key + hash request + response di tabel dengan unique constraint.
  3. Key yang sama datang lagi: kembalikan response yang tersimpan, jangan dieksekusi ulang.
  4. Key sama, body berbeda: tolak dengan 422.
  5. Key kedaluwarsa setelah 24 jam atau lebih.

GET, PUT, dan DELETE seharusnya idempotent secara alami. Rancang memang begitu.

4.3 Versioning (102, 103)

  • API versioning: lewat URL (/v1/) atau header. Perubahan yang bersifat menambah (field opsional baru) tidak breaking; menghapus atau mengganti nama field, mengubah tipe atau semantik, itu breaking.
  • Kebijakan deprecation: umumkan, tambahkan header Deprecation dan Sunset, ukur pemakaian versi lama, baru kemudian hapus.
  • Semantic versioning untuk package: MAJOR.MINOR.PATCH. MAJOR berarti breaking, MINOR menambah fitur, PATCH memperbaiki. Pin dependensi dengan lockfile; jangan percaya bahwa semua orang mengikuti semver dengan sempurna.

4.4 gRPC (100)

Bertipe, biner, cepat, mendukung streaming, di atas HTTP/2. Sangat cocok untuk traffic internal antar-service dalam skala besar. Kurang cocok untuk browser dan API publik. Founder solo jarang membutuhkannya; cukup pahami konsepnya.

4.5 Sekilas keamanan API

Otorisasi di setiap objek (BOLA adalah risiko API nomor satu), rate limit per key, batas pagination, batas ukuran request. Dibahas detail di 05 · Keamanan Aplikasi: OWASP Top 10:2025.

Lab 4: Rilis sebuah kontrak

  1. Tulis spec OpenAPI untuk resource inti Anda; generate client yang bertipe.
  2. Tambahkan idempotency key ke endpoint pembayaran atau "buat pesanan" Anda; tulis test yang mengirim request yang sama 5 kali secara bersamaan dan memastikan hanya ada satu record.
  3. Lakukan breaking change dengan cara yang benar: rilis v2 berdampingan dengan v1 beserta header deprecation.
  4. Contract test di CI gagal jika implementasi menyimpang dari spec.

Definition of Done

Paket prompt AI

  • "Generate spec OpenAPI 3.1 dari route-route ini, lalu daftarkan inkonsistensi dalam penamaan, status code, dan bentuk error."
  • "Tambahkan idempotency key ala Stripe ke endpoint ini, didukung tabel Postgres dengan unique constraint. Tangani kasus duplikat yang datang bersamaan."