Belajar Software Architect - API Design & Contracts

#Pendahuluan

Setelah di episode 8 kita merancang arsitektur data — kepemilikan per modul, spektrum konsistensi, dan outbox pattern — pada episode ini kita bahas permukaan tempat semua desain itu bertemu dunia luar: API.

Bagi architect, API bukan sekadar endpoint; ia adalah kontrak — janji perilaku yang, begitu dirilis, jauh lebih mahal diubah daripada kode internal. Modul bisa direfactor setiap minggu tanpa siapa pun keberatan; mengganti nama satu field publik bisa mematahkan puluhan konsumen dan menuntut koordinasi lintas tim selama berbulan-bulan. Karena itu kualitas desain API adalah indikator langsung kematangan arsitektur.

#Prinsip Desain API

#Resource-Oriented Thinking

REST yang baik dimodelkan dari resource (benda), bukan dari aksi (verb). Bandingkan:

❌ POST /createOrder
❌ POST /cancelOrder?id=123
✅ POST   /orders
✅ PATCH  /orders/123      { "status": "cancelled" }

Resource-oriented membuat sistem predictable: konsumen menebak endpoint baru dengan benar sebelum membaca dokumentasi.

#HTTP Semantics yang Jujur

Status code adalah bagian dari kontrak:

Error body mengikuti struktur konsisten — format RFC 7807 (application/problem+json) adalah pilihan aman: type, title, status, detail, plus field ekstensi seperti traceId agar error mudah dilacak.

#Pagination, Filtering, Sorting

Koleksi besar wajib paginated sejak hari pertama — retrofit pagination ke API publik adalah breaking change terselubung. Offset pagination (?page=2&limit=20) mudah tapi melorot saat data bergeser; cursor pagination stabil untuk feed besar. Cantumkan aturan default limit dan batas maksimumnya di kontrak.

#Versioning & Backward Compatibility

Aturan emas: menambah adalah aman, menghapus/mengubah adalah breaking.

AMAN    → tambah field respons opsional, tambah endpoint baru,
          tambah parameter opsional dengan default
BREAKING→ hapus/renamed field, ubah tipe, ubah semantik status,
          jadikan optional menjadi required

Tiga strategi versioning:

Untuk API internal antar tim, versi date-based (2026-08-16) semakin populer: memaksa evolusi berkala dan menghindari angka v7 yang menyeramkan.

Deprecation juga kontrak. Aturannya: umumkan → tandai response header peringatan (Deprecation/Sunset) → pantau siapa masih memakai → matikan hanya setelah konsumen nol atau tenggat lewat. Versi lama yang mati mendadak adalah insiden yang kalian buat sendiri.

#REST vs gRPC vs GraphQL

Panduan praktis: REST untuk permukaan publik, gRPC untuk komunikasi internal latency-kritis, GraphQL untuk layer agregasi di depan banyak konsumen frontend. Studi kasus kita pakai REST publik + panggilan internal in-process (modular monolith), sehingga kompleksitas gRPC belum dibayar.

Satu bahaya GraphQL layak dicatat bagi architect: query bebas tanpa governance menghasilkan N+1 resolver dan query monster yang menjatuhkan server — wajib disertai complexity limiting dan persisted queries.

#Idempotency: Kontrak untuk Operasi Uang

Retry pasti terjadi (jaringan timeout, user klik dua kali). Operasi non-idempotent seperti POST /orders akan menciptakan order dobel — persis scenario correctness episode 5 (double-charge = 0).

Solusinya idempotency key:

1. Client mengirim header Idempotency-Key: <uuid> per intent transaksi
2. Server menyimpan hasil pertama keyed by uuid
3. Retry dengan key sama → kembalikan HASIL PERTAMA, bukan eksekusi ulang
4. Key beda → dieksekusi normal

Ini pola yang sama dengan charge gateway pembayaran — dan wajib ada di kontrak API apa pun yang memicu efek finansial atau mutasi stok.

#Contract First & Contract Testing

Dua pendekatan kontrak:

• Code first — tulis kode, hasilkan spec. Cepat mulai, tapi kontrak mengikuti mood implementasi.
• Contract first — tulis OpenAPI dulu, review seperti PR, generate server stub & client. Kontrak jadi artefak yang dinegosiasikan, bukan efek samping.

Untuk API publik, contract first hampir selalu menang karena diskusi desain terjadi sebelum kode mengunci keputusan.

Lalu contract testing memastikan janji itu dijaga otomatis: consumer-driven testing (misal Pact) merekam ekspektasi konsumen terhadap provider, dan pipeline provider memverifikasi setiap perubahan terhadap semua kontrak konsumen. Breaking change tertangkap di CI, bukan di produksi konsumen.

#Praktik: Spesifikasi Order API

Mari tulis potongan kontrak utama studi kasus kita:

openapi: "3.1.0"
info:
  title: Orders API
  version: "2026-08-16"
paths:
  /orders:
    post:
      summary: Buat order baru
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [items]
              properties:
                items:
                  type: array
                  minItems: 1
                  items:
                    $ref: "#/components/schemas/OrderItemInput"
      responses:
        "201":
          description: Order dibuat, menunggu pembayaran
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "409":
          description: Stok habis / order duplikat (replay)
        "422":
          description: Validasi item gagal
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema: { type: string, format: uuid }

Catat tiga keputusan desain yang terkandung di dalamnya: idempotency wajib di jalur checkout (episode 8), 409 eksplisit untuk konflik stok/replay, dan 201 dengan schema Order penuh sebagai janji bentuk respons. Kontrak ini kini bisa digenerate ke stub server agar tim frontend mulai bekerja paralel sebelum backend selesai.

#Kesalahan Umum

• Breaking change diam-diam — rename field "kecil" tanpa sadar itu kontrak. Tanpa contract test, baru ketahuan dari tiket konsumen.
• 200 untuk semua hal — error disembunyikan di body; middleware retry dan monitoring buta terhadap kegagalan.
• Chatty API tanpa agregasi — mobile app melakukan 15 request untuk satu layar; latensi total dan biaya melonjak.
• Versioning sebagai pengganti disiplin — v3, v4, v5 hidup bersamaan selamanya karena tidak ada proses sunset. Versioning tanpa deprecation policy hanya menunda hutang.
• Kontrak tidak dijaga otomatis — dokumen OpenAPI yang tidak diverifikasi test hanyalah aspirasi; drift antara spec dan implementasi pasti datang.

#Penutup

Inti yang harus dibawa pulang:

• API adalah kontrak: resource-oriented, HTTP semantics jujur, error format konsisten (RFC 7807).
• Menambah aman, mengubah/hapus breaking — versioning formal untuk konsumen eksternal, disiplin compat untuk internal; sunset process adalah separuh dari versioning.
• Pilih teknologi per konteks: REST publik, gRPC internal cepat, GraphQL agregasi dengan governance.
• Idempotency key wajib di jalur yang menyentuh uang dan stok.
• Contract first + contract testing mengubah API dari harapan menjadi garansi — sejajar dengan fitness function di episode 7.
• Studi kasus kini punya OpenAPI Orders API lengkap dengan keputusan idempotency dan status code eksplisit.

Di episode 10 selanjutnya kita masuk security architecture — threat modeling dengan STRIDE terhadap flow checkout kita, prinsip secure design, defense in depth, dan fondasi zero trust yang akan diperdalam di episode 18. Sampai jumpa!