Konvensi Penamaan REST API: Pedoman Praktis

Buka codebase mana pun yang berusia lebih dari dua tahun dan Anda akan menemukan bekas lukanya: /getUser, /user_list, `[REDACTED PATH]

{% cta https://apidog.com/?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation %} Coba Apidog hari ini {% endcta %}

Penamaan adalah keputusan desain API termurah untuk dibuat dan paling mahal untuk dibatalkan. Setelah klien bergantung pada /getOrders, Anda mungkin harus mendukungnya selama bertahun-tahun.

Panduan ini berisi aturan konkret untuk penamaan REST API, lengkap dengan contoh dan anti-contoh. Prinsipnya mengikuti panduan REST API kami untuk pengembang, tetapi berfokus pada pertanyaan yang paling sering diperdebatkan: apa nama yang tepat untuk setiap hal?

1. Gunakan kata benda jamak untuk koleksi

URL menamai sumber daya, bukan operasi. Koleksi adalah kumpulan objek, jadi gunakan kata benda jamak.

Lakukan:

http
GET /v1/products
GET /v1/products/89
GET /v1/orders


Jangan:

http
GET /v1/getProducts
GET /v1/product
GET /v1/productList


Bentuk jamak berfungsi di kedua tingkat:

• /products berarti kumpulan produk.
• /products/89 berarti produk dengan ID 89 dalam koleksi tersebut.

Penamaan tunggal menghasilkan URL yang membingungkan: /product/89 untuk satu item, tetapi /product untuk banyak item. Pedoman API REST Microsoft memilih kata benda jamak karena alasan ini, dan API publik seperti Stripe, GitHub, serta Shopify mengikuti pola yang sama.

Pengecualian berlaku untuk singleton. Jika setiap pengguna hanya memiliki satu keranjang, [REDACTED PATH]/cart masuk akal. Jangan menjamakkan sumber daya yang memang hanya punya satu instans.

2. Hindari kata kerja dalam jalur

Metode HTTP sudah berfungsi sebagai kata kerja. Menambahkan kata kerja lain ke jalur hanya menduplikasi informasi dan merusak model sumber daya.

Lakukan:

http
GET /v1/orders/42
DELETE /v1/orders/42
PATCH /v1/orders/42


Jangan:

http
GET /v1/fetchOrder/42
POST /v1/deleteOrder/42
POST /v1/updateOrderStatus


Satu sumber daya dengan empat metode HTTP lebih mudah didokumentasikan, diuji, dan di-cache daripada empat jalur berbasis operasi.

Pembatalan cache juga lebih sederhana. CDN dapat mengaitkan GET /v1/orders/42 dengan DELETE /v1/orders/42 karena keduanya menunjuk ke URL yang sama. Model ini tidak dapat menghubungkan /fetchOrder/42 dengan /deleteOrder/42 secara alami.

3. Gunakan kebab-case untuk jalur URL

Segmen jalur yang terdiri dari beberapa kata membutuhkan pemisah. Gunakan tanda hubung.

Lakukan:

text
/v1/gift-cards
/v1/shipping-addresses


Jangan:

text
/v1/giftCards
/v1/gift_cards
/v1/GiftCards


Alasannya:

1. Google memperlakukan tanda hubung sebagai pemisah kata sehingga dokumentasi lebih mudah diindeks.
2. Garis bawah dapat menghilang ketika URL digarisbawahi dalam email atau dokumen.
3. camelCase dapat menimbulkan bug sensitivitas huruf besar-kecil. /giftCards dan /giftcards biasanya merupakan URL berbeda.

Pedoman API REST Zalando menjadikan kebab-case sebagai aturan wajib untuk jalur.

4. Pilih satu casing JSON dan dokumentasikan

Untuk nama field dalam request body dan respons, camelCase maupun snake_case sama-sama valid. Yang tidak valid adalah mencampurkannya.

Lakukan salah satu secara konsisten:

json
{
"orderId": 42,
"createdAt": "2026-08-30T09:15:00Z",
"totalAmount": 4999
}


json
{
"order_id": 42,
"created_at": "2026-08-30T09:15:00Z",
"total_amount": 4999
}


Jangan:

json
{
"orderId": 42,
"created_at": "2026-08-30T09:15:00Z",
"TotalAmount": 4999
}


camelCase cocok untuk klien JavaScript dan Java. snake_case lebih mudah dipindai serta sesuai dengan nama kolom Ruby, Python, dan sebagian besar SQL. Stripe menggunakan snake_case secara konsisten.

Pilih berdasarkan konsumen utama API Anda, lalu masukkan keputusan tersebut ke panduan gaya. Dengan begitu, keputusan dibuat sekali, bukan diperdebatkan di setiap pull request.

Pencampuran casing biasanya merupakan kegagalan governance, bukan persoalan selera.

5. Batasi nesting hingga dua level

Nesting berguna untuk menyatakan kepemilikan:

text
[REDACTED PATH]


Artinya, pesanan milik pengguna 42. Namun, lebih dari dua level biasanya membuat URL sulit digunakan.

Lakukan:

http
GET /v1[REDACTED PATH]
GET /v1/orders/1337/refunds


Jangan:

http
GET /v1[REDACTED PATH]/status


Nesting yang terlalu dalam memaksa klien membawa semua ID leluhur untuk mencapai sumber daya daun, bahkan ketika sumber daya tersebut memiliki ID global yang unik.

Jika pengembalian dana memiliki ID 7, gunakan salah satu dari:

http
GET /v1/refunds/7
GET /v1/orders/1337/refunds/7


Sebagai smell test, ratakan URL yang berisi tiga ID atau lebih. Setelah pesanan dibuat, URL /orders/1337 sudah cukup; ID pengguna tidak lagi diperlukan.

6. Letakkan filter, pengurutan, dan paginasi di parameter kueri

Jalur mengidentifikasi sumber daya. Parameter kueri mengubah cara sumber daya tersebut ditampilkan.

Lakukan:

http
GET /v1/orders?status=active&sort=-created_at&limit=50&cursor=eyJpZCI6NDJ9
GET /v1/products?category=electronics&min_price=1000


Jangan:

http
GET /v1/orders/active
GET /v1/orders/sorted-by-date-desc
GET /v1/getOrdersByStatusAndDate


Notasi sort=-created_at—tanda minus berarti urutan menurun—berasal dari spesifikasi JSON:API. Dengan pola ini, Anda tidak membutuhkan parameter kedua seperti order=desc.

Filter di jalur seperti /orders/active terlihat sederhana sampai Anda perlu menggabungkan beberapa filter. Setelah itu, Anda berisiko membuat endpoint baru untuk setiap kombinasi.

Terapkan disiplin yang sama pada paginasi. Pilih satu pola, misalnya:

text
limit/cursor


atau:

text
page/per_page


Kemudian gunakan pola tersebut di semua koleksi. Lihat panduan paginasi API untuk perbandingan cursor dan offset.

7. Gunakan versi mayor di jalur

Ada dua pendekatan utama untuk versioning:

http
/v1/products


atau:

http
Accept: application/vnd.myapi.v1+json


Versioning melalui header lebih “murni” secara REST karena URL tetap menamai sumber daya yang sama. Panduan desain API Google mencatat bahwa kedua pendekatan digunakan di lapangan.

Namun, versi di jalur lebih mudah dioperasikan:

• terlihat di setiap baris log;
• dapat diuji langsung dari peramban;
• mudah di-cache tanpa pengaturan Vary;
• tidak mudah terlupakan oleh klien.

Gunakan hanya versi mayor:

http
/v1/products


Jangan menambahkan versi minor ke jalur:

http
/v1.2/products


Perubahan minor seharusnya bersifat aditif dan tidak memecahkan kompatibilitas. Untuk decision tree lengkap, termasuk negosiasi konten, lihat perbandingan strategi versioning API.

8. Perlakukan ID sebagai opaque

Hindari mengekspos bilangan bulat berurutan jika enumerasi menjadi masalah:

text
/orders/41
/orders/42
/orders/43


ID berurutan dapat membocorkan jumlah data dan memudahkan penyerang menelusuri ID untuk mencari celah otorisasi. Broken Object Level Authorization (BOLA) menempati peringkat pertama dalam OWASP API Security Top 10.

Lakukan:

http
GET /v1/orders/ord_9f8e2a71b3
GET /v1[REDACTED PATH]


Jangan gunakan ID berurutan untuk sumber daya publik yang sensitif:

http
GET /v1/orders/42
GET /v1/invoices/10883


ID acak dengan prefiks deskriptif, seperti ord_9f8e2a71b3 milik Stripe, memberikan beberapa manfaat:

• sulit ditebak;
• mudah dikenali di log;
• aman untuk diekspos.

Pemeriksaan otorisasi tetap wajib. ID opaque hanya mengurangi dampak ketika pemeriksaan terlewat; ID tersebut bukan pengganti otorisasi.

Anda tetap dapat menggunakan primary key bilangan bulat secara internal. Aturan ini berlaku untuk ID yang diekspos melalui URL.

9. Model tindakan non-CRUD sebagai sumber daya pengontrol

Beberapa tindakan tidak memiliki pemetaan CRUD yang jelas, misalnya membatalkan pesanan, mencoba kembali pembayaran, atau mengirim ulang email.

Lakukan:

http
POST /v1/orders/42/cancel
POST /v1/payments/pay_88a1/retry


Jangan:

http
PATCH /v1/orders/42
{
"status": "cancelled"
}


http
POST /v1/cancelOrder
{
"orderId": 42
}


Ini adalah pola controller. Pola tersebut merupakan satu-satunya pengecualian untuk aturan tanpa kata kerja: kata kerja berada di akhir jalur dan tetap berada di bawah sumber daya yang dikenainya.

Membatalkan pesanan mungkin memicu pengembalian dana, pelepasan inventaris, dan pengiriman notifikasi. Menyembunyikan semua maksud itu di balik perubahan status membuat server harus menebak maksud dari payload.

Endpoint /cancel lebih jelas, dapat memiliki aturan izin dan jejak audit sendiri, serta dapat menerima input khusus seperti alasan pembatalan.

10. Konsistenkan casing header dan parameter kueri

Dua permukaan API ini membutuhkan disiplin yang sama.

Header

Gunakan Hyphenated-Pascal-Case untuk custom header:

http
Idempotency-Key: 3d5f...
Request-Id: req_123


Hindari prefiks X- yang lama. Prefiks tersebut sudah tidak digunakan lagi oleh RFC 6648 sejak 2012.

Nama header tidak peka huruf besar-kecil di wire, tetapi dokumentasi dan SDK tetap harus menuliskannya dengan satu format.

Parameter kueri

Samakan casing parameter kueri dengan body JSON.

Jika body menggunakan snake_case:

http
/v1/orders?min_price=1000&created_after=2026-01-01


Jangan mencampurnya dengan:

http
/v1/orders?minPrice=1000&createdAfter=2026-01-01


Pengembang yang melihat created_at dalam respons seharusnya tidak perlu menebak bahwa parameter kuerinya bernama createdAfter.

Ringkasan aturan

#	Aturan	Lakukan	Jangan
1	Kata benda jamak untuk koleksi	/products, /products/89	/getProducts, /productList
2	Tanpa kata kerja dalam jalur	DELETE /orders/42	POST /deleteOrder/42
3	Segmen jalur kebab-case	/gift-cards	/giftCards, /gift_cards
4	Satu casing JSON	order_id di mana-mana	orderId dan order_id dicampur
5	Maksimal dua level nesting	/orders/1337/refunds	`[REDACTED PATH]
6	Filter dan paginasi di kueri	?status=active&sort=-created_at	/orders/active
7	Versi mayor di jalur	/v1/products	/v1.2/products, versi di header
8	ID sumber daya opaque	/orders/ord_9f8e2a71b3	/orders/42 untuk data publik sensitif
9	Pola controller untuk tindakan	POST /orders/42/cancel	PATCH dengan {"status":"cancelled"}
10	Casing header dan parameter konsisten	Idempotency-Key, ?min_price=	X-IDEMPOTENCY_KEY, ?minPrice= dicampur

Menerapkan konvensi dalam skala besar

Panduan gaya di wiki tidak cukup. Tim dengan API yang konsisten biasanya merancang terlebih dahulu dan menerapkan konvensi sebelum kode ditulis. Inilah inti tata kelola API dalam praktik.

Di sinilah Apidog dapat membantu alur kerja Anda:

• Desain schema-first: definisikan endpoint secara visual sebelum implementasi.
• Konvensi terlihat sejak awal: jalur, casing, dan nama parameter menjadi artefak desain, bukan string tersembunyi di pengontrol.
• Komponen bersama: definisikan skema Pagination, Error, dan Money sekali, lalu gunakan kembali di berbagai endpoint.
• Tinjauan tim: tangkap nama seperti /getUserOrders saat desain, ketika perubahan masih murah.
• Tooling terintegrasi: spesifikasi dapat menggerakkan dokumentasi, mock server, dan pengujian.

Unduh Apidog dan coba gratis pada endpoint berikutnya. Mengubah API lama memang sulit, tetapi menjaga konsistensi API baru tidak harus sulit.

FAQ

Haruskah URL REST berbentuk jamak atau tunggal?

Gunakan bentuk jamak untuk setiap sumber daya yang memiliki lebih dari satu instans:

/products
/orders
/users

Bentuk jamak tetap alami untuk koleksi maupun satu anggota:

/orders
/orders/42

Gunakan bentuk tunggal hanya untuk singleton sejati, seperti:

[REDACTED PATH]

Untuk dasar-dasar pemodelan sumber daya, lihat panduan apa itu REST API.

Apakah camelCase atau snake_case lebih baik untuk nama field JSON?

Tidak ada pemenang mutlak.

• camelCase cocok untuk konsumen JavaScript.
• snake_case lebih mudah dibaca dan cocok dengan ekosistem Python, Ruby, serta Stripe.

Aturan terpenting adalah memilih satu format, mendokumentasikannya dalam panduan gaya, dan menerapkannya pada tinjauan skema. Pencampuran casing lebih merugikan daripada pilihan format mana pun.

Haruskah versi API diletakkan di URL atau di header?

Gunakan versi di jalur:

/v1/orders

kecuali Anda memiliki persyaratan hypermedia yang kuat. Versi di jalur terlihat jelas di log, cache, dan pengujian peramban.

Versioning melalui header menjaga URL tetap stabil, tetapi dapat gagal secara diam-diam ketika klien lupa mengirim header. Gunakan versi mayor saja dan kirimkan perubahan minor sebagai pembaruan aditif yang tidak memecahkan kompatibilitas.

Apakah kata kerja pernah dapat diterima dalam jalur REST API?

Ya, untuk endpoint pengontrol tindakan non-CRUD:

POST /orders/42/cancel
POST /payments/pay_88a1/retry

Kata kerja harus berada di akhir jalur dan terlingkup di bawah sumber dayanya. Gunakan POST untuk tindakan tersebut.

Di tempat lain, metode HTTP membawa kata kerja dan jalur hanya berisi kata benda.