Ada satu pertanyaan yang saya ajukan di setiap review API: kalau kamu harus menjelaskan endpoint ini kepada orang baru dalam satu kalimat, apa yang kamu katakan? Kalau jawabannya panjang, biasanya masalahnya bukan pada kata-katanya, tapi pada batas tanggung jawabnya.

API yang mudah dipakai jarang lahir dari dokumentasi yang bagus. Dokumentasi hanyalah cermin. API yang mudah dipakai lahir dari nama yang jujur, bentuk data yang jelas, dan satu endpoint yang melakukan satu hal sampai tuntas.

Mulai dari kontrak, bukan dari database

Godaan terbesar adalah meniru bentuk tabel. Tabel users jadi /users, kolomnya jadi field respons. Hasilnya cepat dibuat, tapi bocor: perubahan internal langsung menjadi perubahan publik.

Balik urutannya. Tulis dulu kontrak yang paling enak dibaca oleh pemakai, lalu petakan ke dalam sistem. Bentuk respons adalah produk, bukan efek samping dari skema database.

 type Result<T> =
   | { ok: true; value: T }
   | { ok: false; error: string };

 function parseId(raw: string): Result<number> {
   const id = Number(raw);
   if (!Number.isInteger(id) || id <= 0) {
     return { ok: false, error: "id harus bilangan bulat positif" };
   }
   return { ok: true, value: id };
 }

 export async function GET(request: Request) {
   const url = new URL(request.url);
   const parsed = parseId(url.searchParams.get("id") ?? "");
   if (!parsed.ok) {
     return Response.json({ error: parsed.error }, { status: 400 });
   }
   // satu tanggung jawab, satu hasil
 }

Error adalah bagian dari kontrak

Respons sukses biasanya didesain, respons error biasanya muncul begitu saja. Padahal pemakai API menghabiskan lebih banyak waktu membaca error daripada membaca dokumentasi sukses.

Standarkan bentuk error: selalu ada error berupa string pendek yang bisa ditampilkan langsung, plus detail terstruktur untuk mesin. Jangan campur pesan untuk manusia dengan kode untuk mesin dalam satu field.

API yang baik terasa seperti bahasa yang sudah kamu kuasai, bukan seperti sistem yang sedang kamu lawan.

Sedikit, tapi tuntas

  • Satu endpoint untuk satu operasi, jangan satu endpoint dengan sepuluh mode.
  • Nama jamak untuk koleksi, tunggal untuk satu item, dan biarkan URL bercerita.
  • Versi lewat URL atau header, tapi pilih satu dan konsisten.

Pada akhirnya, ukuran API yang baik sederhana: orang yang tidak menulisnya bisa menjelaskannya dalam satu napas.