API yang “berfungsi” tetapi tidak konsisten membuat klien mobile dan web saling menduplikasi logika defensif. Konsistensi mengurangi pertanyaan berulang di Slack dan bug silang-platform.
Fokus tiga hal: versi atau kontrak yang jelas, bentuk kesalahan yang dapat diprediksi, dan perilaku idempoten untuk operasi sensitif — selebihnya bisa disederhanakan bertahap.
URL, versi, dan kode status
Sepakati prefiks versi (/v1)
atau header; yang penting satu sumber kebenaran. Pakai kode status HTTP secara semantik: 400 untuk input
klien, 401/403 untuk authz, 409 untuk konflik bisnis, 422 jika memakai validasi terstruktur.
- Badan error JSON dengan field stabil:
code, pesan manusia, detail opsional. - Hindari mengandalkan teks bahasa Inggris mentah sebagai “kunci” logika di klien — gunakan kode mesin.
- Dokumentasikan pagination, filter, dan batas rate di satu tempat yang mudah ditemukan.
Kontrak dan dokumentasi ringan
OpenAPI atau contoh curl
sudah cukup untuk tim kecil — yang krusial adalah contoh respons sukses dan gagal untuk setiap endpoint
publik utama.
Setelah pola dasar stabil, pertimbangkan skema validasi di sisi server dan generator tipis di klien agar perubahan kontrak terdeteksi di CI, bukan di produksi.