Nama Sumber Daya REST API: Plural atau Singular?

TL;DR

Nama sumber daya REST API harus dalam bentuk jamak. Gunakan /pets/{id} bukan /pet/{id}. Nama jamak merepresentasikan koleksi secara konsisten, selaras dengan semantik HTTP, dan sesuai dengan cara pengembang berpikir tentang sumber daya. Modern PetstoreAPI menggunakan nama jamak di seluruh desain API-nya, mengikuti praktik terbaik industri.

Pengantar

Anda sedang mendesain REST API. Anda memerlukan endpoint untuk mendapatkan pengguna berdasarkan ID. Apakah Anda menggunakan /user/123 atau /users/123? Pertanyaan ini telah memicu perdebatan tak terhitung, diskusi di Stack Overflow, dan argumen tim.

Jawabannya jelas: gunakan bentuk jamak. Namun, memahami alasannya lebih penting daripada sekadar menghafal aturan. Alasan ini berhubungan dengan cara kerja REST, bagaimana koleksi berperilaku, dan bagaimana pengembang berpikir tentang sumber daya.

Swagger Petstore lama keliru dalam hal ini, menggunakan /pet/{id} alih-alih /pets/{id}. Inkonsistensi ini mengajarkan pola yang salah kepada jutaan pengembang. Modern PetstoreAPI memperbaikinya dengan menggunakan nama jamak secara konsisten di semua endpoint.

💡

Jika Anda membangun atau menguji REST API, Apidog membantu Anda memvalidasi konvensi penamaan sumber daya, menguji konsistensi endpoint, dan memastikan API Anda mengikuti praktik terbaik REST. Anda dapat mengimpor spesifikasi OpenAPI, memeriksa pola penamaan, dan menemukan inkonsistensi sebelum mencapai produksi.

button

Dalam panduan ini, Anda akan mempelajari mengapa nama jamak adalah pilihan yang tepat, bagaimana mereka selaras dengan prinsip-prinsip REST, dan cara menerapkannya dengan benar menggunakan Modern PetstoreAPI sebagai referensi.

Perdebatan Jamak vs Tunggal

Perdebatan ini ada karena kedua pendekatan tampaknya logis pada pandangan pertama.

Argumen Tunggal

“Ketika saya meminta /user/123, saya mendapatkan satu pengguna, bukan beberapa pengguna. Bentuk tunggal masuk akal.”

Penalaran ini berfokus pada respons—Anda mendapatkan satu sumber daya, jadi URL harus dalam bentuk tunggal.

Argumen Jamak

“URL merepresentasikan koleksi. /users adalah koleksi semua pengguna. /users/123 adalah item 123 dalam koleksi tersebut.”

Penalaran ini berfokus pada struktur sumber daya—URL merepresentasikan koleksi, dan Anda mengakses item di dalam koleksi tersebut.

Mengapa Ini Penting

Pilihan Anda memengaruhi:

Konsistensi API - Penamaan campuran membingungkan pengembang
Model Mental - Bagaimana pengembang memahami struktur API Anda
Generasi Kode - Alat menghasilkan kode klien berdasarkan nama sumber daya
Kejelasan Dokumentasi - Dokumen perlu menjelaskan logika penamaan Anda

Mengapa Nama Jamak Unggul

Nama sumber daya jamak selaras dengan prinsip-prinsip REST dan semantik HTTP. Berikut alasannya.

1. Koleksi Adalah Jamak

Dalam REST, sumber daya adalah koleksi. Ketika Anda mengakses /users, Anda mengakses koleksi pengguna. Ketika Anda mengakses /users/123, Anda mengakses item 123 dalam koleksi pengguna.

GET /users          ← Koleksi pengguna
GET /users/123      ← Item 123 dalam koleksi pengguna
POST /users         ← Tambahkan ke koleksi pengguna
DELETE /users/123   ← Hapus item 123 dari koleksi pengguna

Model mental ini konsisten. Koleksinya selalu /users, baik Anda mengakses semua item maupun satu item.

Dengan nama tunggal, model mentalnya rusak:

GET /user           ← Pengguna yang mana?
GET /user/123       ← Ini masuk akal
POST /user          ← Tambahkan ke... apa?

2. Metode HTTP Beroperasi pada Koleksi

Metode HTTP menjelaskan operasi pada koleksi:

GET /users - Ambil koleksi
POST /users - Tambahkan ke koleksi
GET /users/123 - Ambil item 123 dari koleksi
PUT /users/123 - Ganti item 123 dalam koleksi
DELETE /users/123 - Hapus item 123 dari koleksi

Koleksi adalah sumber daya. Item individual adalah anggota dari koleksi tersebut.

3. Konsistensi Antar Endpoint

Nama jamak menciptakan konsistensi:

GET /pets           ← Koleksi
GET /pets/123       ← Item dalam koleksi
GET /orders         ← Koleksi
GET /orders/456     ← Item dalam koleksi

Nama tunggal memaksa Anda untuk beralih antara tunggal dan jamak:

GET /pet            ← Tidak masuk akal
GET /pet/123        ← Masuk akal
GET /pets           ← Tunggu, sekarang jadi jamak?

4. Standar Industri

API-API besar menggunakan nama jamak:

GitHub API: /repos, /users, /issues
Stripe API: /customers, /charges, /subscriptions
Twilio API: /accounts, /messages, /calls
Google APIs: /users, /groups, /files

Modern PetstoreAPI mengikuti standar ini dengan /pets, /orders, /users.

Model Mental Koleksi

Memahami koleksi membantu Anda merancang API yang lebih baik.

Koleksi dalam REST

Koleksi adalah sekumpulan sumber daya. Dalam API toko hewan peliharaan:

/pets - Koleksi semua hewan peliharaan
/orders - Koleksi semua pesanan
/users - Koleksi semua pengguna

Setiap koleksi mendukung operasi:

GET /pets           ← Daftar hewan peliharaan (dengan pemfilteran, paginasi)
POST /pets          ← Buat hewan peliharaan baru
GET /pets/{id}      ← Dapatkan hewan peliharaan tertentu
PUT /pets/{id}      ← Perbarui hewan peliharaan tertentu
DELETE /pets/{id}   ← Hapus hewan peliharaan tertentu

Sub-Koleksi

Koleksi dapat berisi sub-koleksi:

GET /pets/{id}/photos           ← Koleksi foto untuk hewan peliharaan {id}
POST /pets/{id}/photos          ← Tambahkan foto ke hewan peliharaan {id}
GET /pets/{id}/photos/{photoId} ← Foto tertentu

Polanya tetap konsisten: koleksi bersifat jamak, item diakses berdasarkan ID.

Contoh Modern PetstoreAPI

Modern PetstoreAPI mengimplementasikan ini dengan benar:

GET /pets
GET /pets/{petId}
GET /pets/{petId}/photos
POST /pets/{petId}/vaccinations
GET /orders
GET /orders/{orderId}
GET /orders/{orderId}/items

Setiap koleksi bersifat jamak. Setiap akses item menggunakan {id} di dalam koleksi tersebut.

Bagaimana Modern PetstoreAPI Menggunakan Nama Jamak

Mari kita lihat contoh nyata dari Modern PetstoreAPI.

Sumber Daya Hewan Peliharaan

GET    /pets                    ← Daftar semua hewan peliharaan
POST   /pets                    ← Buat hewan peliharaan baru
GET    /pets/{petId}            ← Dapatkan hewan peliharaan tertentu
PUT    /pets/{petId}            ← Perbarui hewan peliharaan
DELETE /pets/{petId}            ← Hapus hewan peliharaan
GET    /pets?status=AVAILABLE   ← Saring hewan peliharaan berdasarkan status

Sumber Daya Pesanan

GET    /orders                  ← Daftar semua pesanan
POST   /orders                  ← Buat pesanan
GET    /orders/{orderId}        ← Dapatkan pesanan tertentu
PUT    /orders/{orderId}        ← Perbarui pesanan
DELETE /orders/{orderId}        ← Batalkan pesanan

Sumber Daya Pengguna

GET    /users                   ← Daftar pengguna
POST   /users                   ← Buat pengguna
GET    /users/{userId}          ← Dapatkan pengguna tertentu
PUT    /users/{userId}          ← Perbarui pengguna
DELETE /users/{userId}          ← Hapus pengguna

Sumber Daya Bersarang

GET /pets/{petId}/photos                    ← Foto hewan peliharaan
POST /pets/{petId}/photos                   ← Tambahkan foto
GET /pets/{petId}/vaccinations              ← Vaksinasi hewan peliharaan
POST /pets/{petId}/vaccinations             ← Catat vaksinasi
GET /orders/{orderId}/items                 ← Item pesanan

Periksa dokumentasi REST API lengkap untuk daftar endpoint selengkapnya.

Argumen Umum untuk Bentuk Tunggal (dan Mengapa Mereka Salah)

Mari kita bahas argumen umum untuk nama tunggal.

Argumen 1: “Responsnya Tunggal”

Klaim: “Ketika saya GET /user/123, saya mendapatkan satu pengguna. Bentuk tunggal masuk akal.”

Sanggahan: URL merepresentasikan lokasi sumber daya, bukan respons. /users/123 berarti “item 123 dalam koleksi pengguna.” Respons yang tunggal tidak mengubah struktur koleksi.

Argumen 2: “Lebih Mudah Dibaca dalam Kode”

Klaim: “getUser(id) lebih mudah dibaca daripada getUsers(id).”

Sanggahan: Penamaan kode klien Anda tidak bergantung pada struktur URL. Anda bisa memiliki:

// URL: GET /users/123
function getUser(id) {
  return api.get(`/users/${id}`);
}

Nama fungsi tidak perlu sesuai dengan URL.

Argumen 3: “Bentuk Tunggal Menghindari Masalah Tata Bahasa”

Klaim: “Bagaimana dengan sumber daya seperti ‘status’ atau ‘information’ yang tidak memiliki bentuk jamak yang jelas?”

Sanggahan: Ini biasanya sumber daya singleton, bukan koleksi. Gunakan bentuk tunggal untuk singleton:

GET /status         ← Status sistem (singleton)
GET /configuration  ← Konfigurasi aplikasi (singleton)
GET /users          ← Koleksi pengguna (jamak)

Argumen 4: “ORM Saya Menggunakan Nama Tabel Tunggal”

Klaim: “Tabel database saya tunggal (user, order), jadi API saya harus sesuai.”

Sanggahan: Desain API Anda tidak boleh membocorkan detail implementasi database. REST API merepresentasikan sumber daya, bukan tabel database. Gunakan bentuk jamak untuk koleksi terlepas dari skema database Anda.

Menguji Penamaan Sumber Daya dengan Apidog

Apidog membantu Anda memvalidasi dan menguji konvensi penamaan sumber daya.

Impor Modern PetstoreAPI

Impor spesifikasi OpenAPI Modern PetstoreAPI
Apidog secara otomatis mendeteksi pola sumber daya
Tinjau penamaan endpoint untuk konsistensi

Buat Tes Konvensi Penamaan

// Skrip tes Apidog
pm.test("Resource names are plural", function() {
  const path = pm.request.url.getPath();
  const segments = path.split('/').filter(s => s);

  // Periksa apakah segmen pertama jamak
  const resource = segments[0];
  pm.expect(resource).to.match(/s$/); // Berakhir dengan 's'
});

Validasi Konsistensi

Apidog dapat memeriksa:

Semua endpoint koleksi menggunakan nama jamak
Sub-sumber daya mengikuti pola yang sama
Tidak ada pencampuran tunggal/jamak dalam API yang sama

Uji dengan Permintaan Nyata

GET https://api.petstoreapi.com/v1/pets
GET https://api.petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24
GET https://api.petstoreapi.com/v1/orders

Apidog memvalidasi respons dan membantu Anda memastikan konsistensi penamaan di seluruh API Anda.

Kasus Khusus dan Pengecualian

Beberapa sumber daya tidak sesuai dengan pola jamak.

Sumber Daya Singleton

Sumber daya yang hanya ada satu kali harus tunggal:

GET /status         ← Status sistem
GET /configuration  ← Konfigurasi aplikasi
GET /health         ← Pemeriksaan kesehatan
GET /metrics        ← Metrik sistem

Ini bukan koleksi, jadi bentuk jamak tidak berlaku.

Sumber Daya Pengontrol

Tindakan yang tidak sesuai dengan operasi CRUD:

POST /login         ← Tindakan autentikasi
POST /logout        ← Pengakhiran sesi
POST /search        ← Operasi pencarian kompleks

Ini adalah pengecualian yang dapat diterima karena mereka merepresentasikan tindakan, bukan sumber daya.

Kata Benda Tak Terhitung

Beberapa kata benda tidak memiliki bentuk jamak yang jelas:

GET /information    ← Tunggal (tak terhitung)
GET /data           ← Tunggal (tak terhitung)
GET /equipment      ← Tunggal (tak terhitung)

Gunakan bentuk tunggal untuk kata benda tak terhitung, tetapi ini jarang terjadi pada API yang umum.

Pendekatan Modern PetstoreAPI

Modern PetstoreAPI menangani kasus-kasus ini:

# Koleksi (jamak)
GET /pets
GET /orders
GET /users

# Singleton (tunggal)
GET /health
GET /metrics

# Tindakan (kata kerja tunggal)
POST /login
POST /logout

Kesimpulan

Nama sumber daya REST API harus dalam bentuk jamak. Ini selaras dengan semantik koleksi, metode HTTP, dan standar industri. Modern PetstoreAPI menunjukkan pola ini dengan benar di semua endpoint.

Poin-poin penting:

Gunakan nama jamak untuk koleksi (/pets, /orders, /users)
Item individual diakses di dalam koleksi (/pets/123)
Sumber daya singleton bisa tunggal (/status, /health)
Konsistensi lebih penting daripada kesempurnaan
Uji konvensi penamaan Anda dengan Apidog

Perdebatan jamak vs tunggal telah selesai. Ikuti standar industri, gunakan nama jamak, dan bangun API yang dipahami pengembang secara intuitif.

Langkah selanjutnya:

Tinjau endpoint API Anda untuk konsistensi penamaan
Periksa dokumentasi Modern PetstoreAPI untuk pola referensi
Gunakan Apidog untuk memvalidasi desain API Anda
Perbarui spesifikasi OpenAPI Anda dengan nama sumber daya jamak

FAQ

Haruskah saya mengubah API saya yang sudah ada dari tunggal menjadi jamak?

Jika API Anda sudah dalam produksi, mengubah nama sumber daya adalah perubahan yang merusak. Pertimbangkan:

Menambahkan endpoint v2 baru dengan nama jamak
Mempertahankan kompatibilitas mundur dengan pengalihan
Mendokumentasikan konvensi penamaan dengan jelas

Jangan merusak klien yang sudah ada hanya demi konsistensi penamaan.

Bagaimana dengan sumber daya yang sudah jamak?

Jika nama sumber daya secara alami jamak (seperti “analytics” atau “series”), biarkan apa adanya:

GET /analytics      ← Sudah jamak
GET /series         ← Sudah jamak
GET /species        ← Sudah jamak

Bagaimana cara menangani sumber daya bersarang?

Biarkan kedua tingkatan dalam bentuk jamak:

GET /users/{userId}/orders              ← Keduanya jamak
GET /pets/{petId}/vaccinations          ← Keduanya jamak
GET /orders/{orderId}/items             ← Keduanya jamak

Bagaimana jika tim saya lebih suka bentuk tunggal?

Konsistensi dalam API Anda adalah yang terpenting. Jika tim Anda sudah membakukan nama tunggal dan perubahan akan menyebabkan kebingungan, tetap gunakan bentuk tunggal. Namun, untuk API baru, gunakan bentuk jamak.

Apakah GraphQL menggunakan bentuk jamak atau tunggal?

GraphQL biasanya menggunakan bentuk tunggal untuk kueri satu item dan bentuk jamak untuk daftar:

query {
  user(id: "123") { ... }      # Tunggal
  users(limit: 10) { ... }     # Jamak
}

Ini berbeda dari REST karena kueri GraphQL eksplisit tentang mengembalikan satu atau banyak.

Bagaimana Modern PetstoreAPI menangani hal ini?

Modern PetstoreAPI menggunakan nama jamak secara konsisten di semua endpoint REST. Periksa panduan REST API untuk contoh lengkap.

Bisakah saya menguji konvensi penamaan secara otomatis?

Ya, Apidog dapat menjalankan tes otomatis untuk memeriksa pola penamaan sumber daya di seluruh API Anda. Impor spesifikasi OpenAPI Anda dan buat kasus uji untuk konvensi penamaan.

Bagaimana dengan API non-Inggris?

Aturan jamak berlaku terlepas dari bahasa. Jika API Anda menggunakan nama sumber daya Prancis, gunakan bentuk jamak Prancis. Jika menggunakan Jepang, ikuti aturan tata bahasa Jepang. Prinsipnya (koleksi bersifat jamak) tetap sama.