Struktur URL REST API terbaik adalah menggunakan kata benda (noun) jamak untuk merepresentasikan resource, menerapkan huruf kecil (kebab-case), serta menghindari penggunaan kata kerja pada endpoint karena metode HTTP (GET, POST, PUT, DELETE) sudah merepresentasikan aksi yang dilakukan.
Desain URL yang konsisten sangat krusial untuk kemudahan pemeliharaan sistem, skalabilitas, serta kenyamanan developer lain yang mengonsumsi API tersebut. Endpoint yang terstruktur dengan baik membuat dokumentasi lebih intuitif dan meminimalisir kesalahan integrasi di sisi klien.
Aturan Dasar Penamaan URL REST API
Standar industri menetapkan beberapa aturan baku dalam mendesain endpoint agar bersih dan mudah dibaca:
- Gunakan Kata Benda Jamak (Plural Nouns): Representasikan koleksi data dengan bentuk jamak, contoh
/usersatau/products, bukan bentuk tunggal/user. - Gunakan Huruf Kecil dan Pemisah Hub (kebab-case): Jika nama resource terdiri dari dua kata atau lebih, gunakan tanda hubung (-) sebagai pemisah, contoh
/order-items. - Hindari Ekstensi File: Jangan menyertakan ekstensi seperti
.jsonatau.xmlpada URL. Gunakan header HTTPAcceptuntuk menentukan format data. - Gunakan Query Parameters untuk Filtering & Paginasi: Saring data atau batasi hasil menggunakan parameter kueri, bukan menambah segmen path baru.
Tabel Standar Desain Endpoint REST API
Berikut adalah tabel acuan cepat untuk memetakan operasi CRUD ke dalam struktur URL REST API yang ideal:
| Aksi / Operasi | Metode HTTP | Struktur URL (Endpoint) | Keterangan |
|---|---|---|---|
| Mendapatkan semua data | GET | /api/v1/products |
Mengembalikan daftar seluruh produk |
| Mendapatkan satu data spesifik | GET | /api/v1/products/{id} |
Mengembalikan detail produk berdasarkan ID |
| Menambah data baru | POST | /api/v1/products |
Membuat entitas produk baru |
| Memperbarui seluruh data | PUT | /api/v1/products/{id} |
Mengganti data produk secara utuh |
| Memperbarui sebagian data | PATCH | /api/v1/products/{id} |
Mengubah beberapa atribut produk tertentu |
| Menghapus data | DELETE | /api/v1/products/{id} |
Menghapus entitas produk |
Pengelolaan Relasi dan Nested Resources
Ketika sebuah resource memiliki hubungan ketergantungan dengan resource lain (misalnya ulasan yang dimiliki oleh suatu produk tertentu), struktur URL dapat dibuat bersarang (nested). Namun, batasi maksimal kedalaman hingga dua tingkat agar URL tidak terlalu panjang dan rumit.
// Contoh Nested Resource untuk mengambil semua ulasan dari produk tertentu
GET /api/v1/products/45/reviews
// Contoh Nested Resource untuk mengambil ulasan spesifik dari produk tertentu
GET /api/v1/products/45/reviews/12Untuk relasi yang kompleks atau tidak memiliki kepemilikan langsung (hierarki longgar), lebih baik menggunakan query parameters pada endpoint utama daripada membuat URL bersarang yang dalam.
Versioning (Versi API)
Sangat disarankan untuk menyertakan nomor versi pada struktur URL untuk mengantisipasi perubahan struktur data di masa depan tanpa merusak aplikasi klien yang sudah berjalan. Penempatan versi umumnya diletakkan di awal path URL setelah domain utama.
https://api.namadomain.com/v1/users
https://api.namadomain.com/v2/usersFilter, Urutkan, dan Paginasi
Jangan membuat endpoint terpisah untuk pencarian atau pengurutan data khusus jika resource dasarnya sama. Manfaatkan query parameters agar endpoint tetap bersih.
// Contoh penggunaan filter, sorting, dan paginasi
GET /api/v1/products?category=electronics&sort=price_asc&limit=10&page=2Dengan menerapkan standar penamaan jamak, penggunaan metode HTTP yang tepat, serta pemanfaatan query parameter yang konsisten, arsitektur REST API Anda akan lebih mudah dikembangkan, dipahami oleh tim lain, serta minim kesalahan integrasi.