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

Struktur URL REST API: Standar Terbaik & Praktik Nyata

Struktur URL REST API yang baik harus berfokus pada hierarki resource (sumber daya) menggunakan kata benda (noun) jamak, bukan kata kerja. Sebuah endpoint REST API yang bersih mendefinisikan identitas data secara intuitif melalui kombinasi protokol, domain, namespace API, versi, nama resource, dan identifier unik.

Dalam arsitektur REST, URL bertindak sebagai pengenal unik (URI) untuk entitas data. Kepatuhan terhadap konvensi standar industri memastikan API mudah dipelihara, dipahami oleh pengembang lain, serta konsisten saat diskalakan.

Anatomi Dasar Struktur URL REST API

Format standar sebuah URL REST API mengikuti pola hirarkis yang memisahkan antara lokasi server, versi layanan, dan entitas data yang ingin dimanipulasi. Perhatikan contoh format dasar berikut:

https://api.namadomain.com/v1/users/42/orders

Berdasarkan contoh di atas, pembedahan komponennya adalah sebagai berikut:

  • https:// : Protokol keamanan yang wajib digunakan (Transport Layer Security).
  • api.namadomain.com : Subdomain khusus yang mendedikasikan trafik untuk layanan API.
  • v1 : Indikator versi API untuk mengelola perubahan struktur tanpa merusak klien lama (Versioning).
  • users : Nama resource utama (wajib menggunakan bentuk jamak/plural noun).
  • 42 : ID unik untuk spesifik resource (Identifier).
  • orders : Sub-resource yang berelasi langsung dengan user ID 42.

    • Aturan Penamaan Resource dan Endpoint

    Konsistensi penamaan adalah kunci utama dalam desain RESTful API. Kesalahan umum sering terjadi pada penggunaan kata kerja di dalam URL, padahal tindakan (action) sudah diwakili oleh metode HTTP (GET, POST, PUT, DELETE).

    Praktik Buruk (Anti-Pattern) Praktik Terbaik (RESTful Standard) Metode HTTP Keterangan
    GET /getUser?id=42 GET /users/42 GET Gunakan path parameter untuk ID, bukan query parameter.
    POST /createNewUser POST /users POST Gunakan kata benda jamak; aksi tersurat di method POST.
    POST /users/42/update PUT /users/42 atau PATCH /users/42 PUT/PATCH Hindari kata kerja 'update' di dalam URL path.
    GET /deleteUser/42 DELETE /users/42 DELETE Gunakan method DELETE untuk penghapusan data.

    Penggunaan Query Parameters untuk Filtering dan Paging

    Ketika data yang diambil memerlukan proses penyaringan (filtering), pengurutan (sorting), atau pembagian halaman (pagination), jangan membuat endpoint baru. Manfaatkan query parameters di akhir URL untuk kebutuhan tersebut agar struktur path tetap bersih.

    GET /users?status=active&sort=created_at:desc&limit=10&page=2

    Panduan penerapan query parameters yang lazim digunakan:

    • Filtering: Gunakan atribut data sebagai kunci (contoh: ?role=admin&status=active).
    • Sorting: Tentukan kolom acuan dan arah urutan (contoh: ?sort=price,asc atau ?sort=-created_at).
    • Pagination: Gunakan parameter standar seperti limit dan offset, atau page dan per_page.

    Menangani Relasi Kompleks Antar Resource

    Dalam sistem nyata, data sering kali memiliki relasi one-to-many atau many-to-many. Struktur URL harus mencerminkan kedalaman relasi tersebut secara logis maksimal hingga kedalaman 2 atau 3 level agar tidak terlalu panjang.

    GET /authors/12/books/5/reviews

    Jika kedalaman relasi melebihi tiga level, disarankan untuk memotong path dan memindahkan referensi parent ke dalam query parameter atau melakukan request secara terpisah.

    Praktik Terbaik Penulisan (Best Practices)

    Patuhi aturan penulisan huruf dan pemisah kata agar konsisten di seluruh tim pengembang:

    • Gunakan huruf kecil (lowercase) secara konsisten untuk seluruh path URL.
    • Gunakan tanda hubung (kebab-case: user-profiles) untuk memisahkan kata majemuk pada nama resource, bukan snake_case atau camelCase.
    • Jangan pernah menyertakan ekstensi file (seperti .json atau .xml) di dalam URL path; gunakan header HTTP Accept: application/json sebagai gantinya.
    • Pastikan selalu menyertakan garis miring penutup (trailing slash) atau konsisten tanpa trailing slash sesuai standar routing framework yang digunakan (biasanya tanpa trailing slash di akhir).

    🔍 Orang Lain Juga Mencari Ini