Bikin API yang Rapi Itu Gampang-Gampang Susah, Ini Ide-idenya
Kalau kamu pernah ngoprek API orang lain yang amburadul, pasti tahu rasanya: endpoint-nya nggak jelas, responnya beda-beda format, error-nya misterius. Nah, bikin API yang rapi itu bukan cuma soal kode yang jalan, tapi juga soal pengalaman developer yang pakai. Bayangkan API itu kayak pelayan restoran. Kalau pelayannya asal nyodorin menu, kamu bakal bingung mau pesan apa.
Nggak perlu sok idealis, cukup terapkan beberapa ide sederhana ini biar API-mu enak dipakai orang lain (atau dirimu sendiri di masa depan).
1. Konsisten Itu Kunci Utama
API yang rapi itu nggak harus sempurna, tapi harus konsisten. Kalau kamu sudah pakai `/users` untuk daftar user, jangan tiba-tiba pakai `/get-all-pengguna` untuk resource yang sama. Tentukan aturan main:
– Pakai kata benda, bukan kata kerja. `/orders` lebih baik daripada `/getOrders`.
– Jamak atau tunggal? Pilih satu. Konsisten memakai bentuk jamak lebih umum, misal `/products`, `/transactions`.
– Huruf kecil semua, pakai strip untuk spasi. `/user-profile` bukan `/userProfile` atau `/user_profile`.
Kalau aturannya sudah dibuat, tempel di dinding (secara metafora) dan jangan diganggu gugat.
2. Naming yang Jelas, Bukan Kode Rahasia
Nama endpoint dan parameter harus langsung menggambarkan fungsinya. Hindari singkatan yang cuma kamu yang paham. Contoh:
– ❌ `/getData?t=1&s=2`
– ✅ `/products?sort=price&page=2`
Parameter juga harus eksplisit. Gunakan `created_after` daripada `caf` (created after). Ingat, API-mu itu untuk dibaca manusia, bukan cuma untuk dieksekusi mesin.
3. Respons Selalu Terbungkus Rapi
Buat format respons yang seragam. Misalnya, setiap respons sukses berbentuk:
“`json
{
“success”: true,
“data”: { … }
}
“`
Dan untuk error:
“`json
{
“success”: false,
“error”: {
“code”: “VALIDATION_ERROR”,
“message”: “Email tidak valid”
}
}
“`
Dengan cara ini, developer tinggal cek `success` dulu, nggak perlu nebak-nebak. Jangan sampai ada satu endpoint mengembalikan array langsung, endpoint lain mengembalikan objek dengan key `result`, dan yang lain lagi bawa string polos.
4. Error Message yang Manusiawi
Error itu hal wajar, tapi cara menyampaikannya bedakan antara “bisa dipahami” dan “bikin pengguna ngomel”. Jangan cuma kirim `401` tanpa penjelasan. Berikan pesan yang jelas: “Token expired, silakan login ulang” atau “Field ‘name’ wajib diisi”.
Plus, jangan lupa sertakan HTTP status code yang tepat. `404` untuk resource nggak ketemu, `400` untuk input salah, `429` untuk rate limit. Jangan semua error pakai `500`.
5. Versioning dari Awal, Biar Nggak Sakit Hati
API itu hidup, pasti akan berubah. Kalau nggak ada versi, tiba-tiba kamu ubah format respons, semua aplikasi yang bergantung pada API-mu bisa jebol. Solusinya: pakai versioning sederhana. Bisa di URL (`/v1/users`) atau di header (`Accept: application/vnd.yourapp.v1+json`). Mulai dari sekarang, meskipun masih tahap awal. Ini seperti pakai helm sebelum naik motor—rasanya ribet, tapi menyelamatkan.
6. Dokumentasi Itu Wajib, Bukan Bonus
API yang rapi tanpa dokumentasi itu seperti buku resep tanpa takaran. Developer harus menebak-nebak. Nggak perlu buat dokumentasi mewah—cukup catat:
– Endpoint dan metodenya (GET, POST, PUT, DELETE)
– Parameter yang dibutuhkan (wajib/opsional)
– Contoh request dan response
– Kode error yang mungkin muncul
Kamu bisa pakai tools seperti Swagger/OpenAPI biar dokumentasi otomatis nyambung dengan kode. Atau kalau malas, tulis di README aja. Yang penting ada.
7. Paginasi untuk Data Banyak
Kalau endpoint-mu bisa mengembalikan ribuan data, jangan sekaligus. Implementasikan paginasi dengan pola sederhana: `?page=2&limit=20`. Dan sertakan info total data atau next page di respons, biar developer tahu masih ada data lain. Biar rapi, respons bisa berisi:
“`json
{
“data”: […],
“pagination”: {
“page”: 2,
“limit”: 20,
“total”: 150,
“next”: “/items?page=3&limit=20”
}
}
“`
8. Jangan Pelit Memberi Fitur Filtering & Sorting
Developer suka fleksibilitas. Kalau API-mu butuh data yang sudah difilter, biarkan mereka mengirim parameter query seperti `?status=active&sort=-created_at`. Tentukan juga aturan untuk sorting (misalnya tanda minus berarti descending). Ini bikin API terasa “hidup” dan adaptif.
9. Gunakan HTTP Method Sesuai Fungsinya
Ini klasik, tapi sering dilanggar:
– GET: baca data
– POST: buat data baru
– PUT/PATCH: update data
– DELETE: hapus data
Jangan pakai GET untuk menghapus data atau POST untuk membaca data. Ini bukan cuma soal estetika, tapi juga soal keamanan dan kejelasan.
10. Rate Limiting dan Keamanan
Walaupun bukan bagian dari “kerapian” secara langsung, API yang rapi juga harus punya batas. Taruh rate limit di header (`X-RateLimit-Remaining`) dan beri tahu developer kalau quota habis. Ini menunjukkan kamu peduli pada stabilitas API-mu.
Terakhir: Minta Masukan
Ini ide paling murah tapi paling ampuh: minta developer lain mencoba API-mu. Catat di mana mereka bingung, di mana mereka mengumpat, dan di mana mereka tersenyum. Dari situ kamu bisa tahu bagian mana yang belum rapi.
Intinya, API yang rapi itu bukan soal teknologi canggih, tapi soal empati pada orang yang akan memakainya. Dengan sedikit konsistensi, dokumentasi yang decent, dan error message yang ramah, API-mu sudah jauh lebih baik dari kebanyakan. Selamat merapikan!