💡 ULASAN & REFERENSI • DIPERBARUI: 26 October 2026 • REDAKSI AZWINN

Contoh Struktur URL REST API Terbaik dan Best Practice

Struktur URL REST API yang baik menggunakan kata benda jamak untuk sumber daya (resource), menerapkan hierarki relasi yang jelas, serta menghindari kata kerja pada endpoint karena aksi HTTP (GET, POST, PUT, DELETE) telah mewakili operasi yang dilakukan.

Desain endpoint yang konsisten memudahkan pengembang front-end maupun pihak ketiga untuk memahami dan mengonsumsi layanan tanpa dokumentasi yang rumit.

Aturan Dasar Penamaan URL REST API

Sebelum melihat contoh spesifik, berikut adalah kaidah universal yang wajib diterapkan dalam merancang endpoint RESTful:

  • Gunakan huruf kecil (lowercase) sepenuhnya.
  • Gunakan tanda hubung (-) untuk memisahkan kata majemuk (kebab-case).
  • Gunakan bentuk jamak (plural nouns) untuk nama koleksi data (contoh: /users bukan /user).
  • Jangan menyertakan ekstensi file seperti .json atau .xml di dalam URL.

Tabel Contoh Struktur Endpoint REST API

Berikut adalah matriks standar pemetaan operasi CRUD ke dalam struktur URL REST API berdasarkan studi kasus entitas Users dan Orders:

Aksi / Operasi Metode HTTP Contoh Struktur URL (Endpoint) Keterangan
Mendapatkan semua data GET /api/v1/users Mengambil daftar seluruh pengguna
Mendapatkan data spesifik GET /api/v1/users/42 Mengambil detail pengguna dengan ID 42
Membuat data baru POST /api/v1/users Menambahkan pengguna baru (payload di body)
Memperbarui seluruh data PUT /api/v1/users/42 Mengganti seluruh data pengguna ID 42
Memperbarui sebagian data PATCH /api/v1/users/42 Mengubah atribut tertentu (misal: email saja)
Menghapus data DELETE /api/v1/users/42 Menghapus pengguna dengan ID 42

Contoh Penanganan Relasi Antar Sumber Daya

Ketika sebuah entitas memiliki hubungan dengan entitas lain (misalnya seorang pengguna memiliki beberapa pesanan), struktur URL harus merefleksikan hierarki tersebut secara logis.

# Mendapatkan semua pesanan milik pengguna tertentu (ID 42)
GET /api/v1/users/42/orders

# Mendapatkan detail pesanan spesifik (ID 10) milik pengguna (ID 42)
GET /api/v1/users/42/orders/10

# Membuat pesanan baru untuk pengguna (ID 42)
POST /api/v1/users/42/orders

Praktik Terbaik Penggunaan Query Parameters

Untuk proses penyaringan (filtering), pengurutan (sorting), dan pembatasan halaman (pagination), jangan membuat endpoint baru. Gunakan query parameters pada URL yang sama.

# Filtering dan Pagination
GET /api/v1/products?category=electronics&status=active&page=2&limit=10

# Sorting berdasarkan harga secara descending
GET /api/v1/products?sort=-price

Kesalahan Umum yang Harus Dihindari

Desainer API pemula sering kali terjebak pada beberapa kesalahan struktural berikut:

  • Menyertakan kata kerja: Hindari /api/v1/getUsers atau /api/v1/createUser. Biarkan metode HTTP (GET/POST) yang mendefinisikan aksinya.
  • Inkonsistensi penamaan: Mencampur penggunaan singular (/user) dan plural (/orders) dalam satu aplikasi.
  • Struktur bertingkat yang terlalu dalam: Hindari nested URL lebih dari dua level (misal: /users/42/orders/10/items/5/reviews). Lebih baik gunakan parameter ID tunggal di root jika memungkinkan.

🔍 Orang Lain Juga Mencari Ini