Cara Membuat PRD API & Backend Service: Kontraknya Adalah Produknya

Selasa pagi, tiga toko langganan Dimas menelepon hampir bersamaan: aplikasi kasir mereka menampilkan stok 0 untuk semua barang dari gudangnya, padahal gudang lagi penuh-penuhnya. Di sisi Dimas tidak ada yang kelihatan rusak. Server hidup, API stoknya membalas 200 OK, log bersih. Setengah hari kemudian baru ketahuan: minggu sebelumnya, waktu menambah fitur baru, agent AI-nya sekalian mengganti nama field qty jadi stok_tersedia di response API. API-nya sendiri tidak pernah error. Aplikasi kasir pelanggannya yang masih mencari field qty, tidak menemukannya, lalu menganggap semua stok nol.

Kejadian seperti ini nyaris mustahil terjadi di aplikasi biasa, karena kalau tampilan berubah, kamu langsung lihat sendiri. API tidak punya tampilan. Satu-satunya yang dipegang orang lain dari API-mu adalah kontraknya: janji tertulis soal bentuk request dan response di tiap endpoint. Makanya PRD API yang bagus terasa seperti dokumentasi yang ditulis sebelum kodenya ada: kontrak itulah produknya. Kalau konsep PRD-nya sendiri masih asing buatmu, kenalan dulu lewat apa itu PRD, lalu balik ke sini.

Kenapa "bikinin API stok" saja menghasilkan API yang tidak bisa dipakai orang lain

Kalau kamu cuma bilang "bikinin API stok" ke agent, API-nya hampir pasti jadi, dan hampir pasti jalan waktu kamu coba sendiri. Masalahnya baru muncul waktu orang lain mau memakainya: programmer vendor kasir, aplikasi pihak ketiga, atau agent lain yang membangun aplikasi berikutnya. Mereka butuh tahu persis endpoint apa saja yang tersedia, method-nya apa (GET untuk membaca, POST untuk membuat, PATCH untuk mengubah), path-nya bagaimana, dan yang paling menentukan, bentuk JSON yang dikirim dan diterima, sampai ke nama tiap field dan format tanggalnya. Tanggal "03/07" itu 3 Juli atau 7 Maret? Kalau kamu tidak menuliskannya, agent memutuskan semua itu sendiri, dan keputusannya tidak bisa ditebak oleh orang yang integrasinya datang belakangan. PRD API yang baik menuliskan kontrak tiap endpoint kira-kira seperti ini:

GET /v1/produk/{sku}/stok

Respons 200:
{
  "sku": "KAOS-HITAM-L",
  "nama": "Kaos Polos Hitam L",
  "stok": 42,
  "diperbarui_pada": "2026-07-30T09:15:00+07:00"
}

Versi sejak hari pertama

Perhatikan path di contoh tadi: ada /v1 di depannya. Awalan sekecil itu yang menentukan API-mu bisa berubah dengan selamat atau tidak. Begitu satu saja klien terhubung ke API-mu, bentuk response-nya terkunci, karena kode mereka ditulis berdasarkan bentuk itu. Padahal kebutuhan pasti berubah: field perlu ganti nama, struktur perlu dirombak. Tanpa versi, satu-satunya cara berubah adalah mengubah response yang sedang dipakai orang, dan itulah yang menimpa Dimas: perubahan yang niatnya merapikan, matinya di aplikasi orang lain, tanpa error di sisimu dan tanpa peringatan di sisi mereka. Dengan versi sejak hari pertama, perubahan besar masuk ke /v2 sebagai jalur baru, sementara /v1 tetap hidup membalas dengan bentuk lama. Kasir pelanggan Dimas akan tetap tenang membaca qty di /v1 sampai vendor kasirnya siap pindah, dan tidak ada toko yang stoknya mendadak nol di Selasa pagi.

Satu format error untuk semua endpoint

Error di API datang tiap hari sebagai bagian dari pemakaian normal: stok kurang, API key salah, SKU tidak ketemu. Yang bikin integrasi menyebalkan adalah bentuk error yang beda-beda di tiap endpoint. Satu endpoint membalas teks polos, endpoint lain membalas {"message": "..."}, endpoint ketiga malah membalas 200 OK yang isinya {"success": false}. Akibatnya tiap integrasi harus menebak-nebak cara membaca kegagalan, endpoint demi endpoint. PRD-mu cukup menetapkan satu bentuk JSON error untuk seluruh API, supaya klien bisa menangani semua kegagalan dengan satu penanganan yang sama:

Semua error, dari endpoint mana pun, bentuknya selalu:
{
  "error": {
    "code": "STOK_TIDAK_CUKUP",
    "message": "Stok KAOS-HITAM-L tersisa 3, diminta 10."
  }
}

• 200 atau 201 - berhasil; 201 khusus saat resource baru dibuat
• 400 - request-nya sendiri tidak valid, misal field wajib kosong atau JSON-nya rusak
• 401 - API key tidak disertakan, salah, atau sudah dicabut
• 404 - resource yang diminta tidak ada, misal SKU yang tidak terdaftar
• 422 - request valid tapi ditolak aturan bisnis, misal stok tidak cukup
• 429 - pemanggil melewati rate limit, harus menunggu sebelum mencoba lagi

Autentikasi: satu API key per pemanggil

Yang memanggil API-mu adalah program, dan program tidak bisa mengetik password di halaman login. Jadi jangan biarkan agent-mu membangun halaman login lengkap dengan session dan cookie. Yang dipakai API adalah API key: deretan karakter rahasia yang disertakan pemanggil di tiap request, biasanya lewat header. Di PRD, minta tabel kunci: satu kunci per klien, dengan catatan siapa pemiliknya, kapan dibuat, dan statusnya aktif atau dicabut, plus log pemakaian sederhana yang mencatat kunci mana memanggil endpoint apa dan kapan. Kenapa harus per klien: begitu vendor kasir A berhenti langganan, kamu mencabut kunci A tanpa mengganggu vendor B dan C. Begitu ada kunci bocor, kamu tahu persis punya siapa dan cukup mengganti satu. Kalau semua klien memakai kunci yang sama, mencabut satu klien berarti mematikan semuanya sekaligus.

Rate limit per kunci dan paginasi untuk semua endpoint daftar

Dua pengaman ini sering dianggap urusan nanti, padahal keduanya yang menentukan API-mu selamat atau tidak justru saat pemakaiannya mulai ramai. Rate limit membatasi berapa request yang boleh dikirim satu kunci per menit, misalnya 60, dan yang melewatinya dibalas 429. Tanpa ini, satu integrasi yang salah menulis loop bisa membanjiri servermu ribuan request per detik, dan API-nya tumbang untuk semua klien sekaligus, termasuk yang selama ini memanggil dengan tertib. Paginasi urusannya dengan endpoint daftar seperti GET /v1/produk. Waktu datamu masih 200 baris, mengirim semuanya sekaligus terasa baik-baik saja. Waktu datanya sudah 50 ribu baris, satu request itu memaksa server menyusun JSON puluhan megabyte, respons yang tadinya sepersekian detik molor jadi belasan detik lalu kena timeout, dan klien yang memanggil ikut tumbang saat mencoba mengurai balasan sebesar itu. Tulis di PRD: semua endpoint daftar wajib menerima parameter halaman dan limit, dengan default misalnya 50 baris dan maksimum 200, tanpa kecuali.

Dokumentasi bukan pelengkap, tapi bagian dari produknya

Orang tidak bisa membaca kode server-mu untuk tahu cara memakai API-mu. Satu-satunya pintu masuknya ya dokumen. Karena itu di PRD API, jadikan dokumentasi task tersendiri dengan kriteria selesai: file OpenAPI atau minimal README yang mendaftar semua endpoint, bentuk request dan response-nya, format error, cara memakai API key, dan satu contoh curl siap-copy untuk tiap endpoint. Contoh curl itu penting karena calon pemakai bisa membuktikan API-nya jalan dalam semenit, cukup tempel di terminal, tanpa menulis satu baris kode pun. Kalau kamu terbiasa memecah fitur jadi tugas-tugas kecil untuk agent, perlakukan dokumentasi sebagai task dengan bobot yang sama seperti endpoint-nya sendiri: endpoint yang belum terdokumentasi dianggap belum selesai. API tanpa dokumen praktis belum ada, karena tidak ada satu orang pun di luar sana yang bisa memakainya.

Webhook keluar: kalau aplikasi lain perlu dikabari

Bagian ini opsional, tapi kalau relevan buat kasusmu, tulis sejak awal. Kadang arah kebutuhannya terbalik: API-mu yang perlu mengabari aplikasi lain begitu ada perubahan, misalnya stok berubah atau pesanan masuk, tanpa menunggu mereka bertanya terus-menerus. Itu tugas webhook: servermu mengirim POST berisi data kejadian ke URL yang didaftarkan tiap klien. Kontraknya harus tertulis sama tegasnya dengan endpoint biasa: kejadian apa saja yang dikirim, bentuk payload-nya, dan yang paling sering dilupakan, aturan kirim ulangnya. Server penerima bisa saja sedang mati waktu webhook-mu datang. Tanpa aturan retry tertulis, misalnya dianggap terkirim kalau dibalas 2xx dan selain itu dicoba ulang 3 kali dengan jeda 1, 5, dan 30 menit, agent akan membangun versi kirim-sekali-lalu-lupa, dan kejadian penting hilang diam-diam, persis jenis bug yang baru ketahuan berminggu-minggu kemudian. Ujung-ujungnya, ukuran PRD API yang bagus cuma satu: orang lain bisa integrasi tanpa perlu bertanya ke kamu. Tuliskan tiap kontraknya sebagai acceptance criteria yang bisa dicek, dan biarkan PRD-mu jadi dokumentasi yang tinggal ditepati kodenya.