Mengapa URL REST API Sebaiknya Tidak Menggunakan Kata Kerja?

TL;DR

URL API REST sebaiknya berisi kata benda (sumber daya), bukan kata kerja (tindakan). Metode HTTP (GET, POST, PUT, DELETE) adalah kata kerjanya. Menggunakan kata kerja tindakan seperti /getUser atau /createOrder melanggar prinsip REST, menciptakan inkonsistensi, dan membuat API lebih sulit dikelola. Modern PetstoreAPI menggunakan URL berorientasi sumber daya secara menyeluruh.

Pendahuluan

Anda sedang merancang titik akhir (endpoint) API untuk mencari hewan peliharaan berdasarkan status. Insting pertama Anda mungkin: GET /findPetsByStatus?status=available. Ini deskriptif, jelas, dan memberi tahu Anda persis apa yang dilakukannya. Tapi, itu salah.

API REST harus menggunakan kata benda di URL, bukan kata kerja. Metode HTTP adalah kata kerjanya. GET /pets?status=available adalah desain yang benar. URL merepresentasikan sumber daya (hewan peliharaan), dan metode merepresentasikan tindakan (get).

Swagger Petstore lama membuat kesalahan ini dengan titik akhir seperti /pet/findByStatus dan /pet/findByTags. Kata kerja tindakan ini dalam URL melanggar prinsip REST dan menciptakan masalah pemeliharaan. Modern PetstoreAPI memperbaikinya dengan menggunakan URL berorientasi sumber daya secara konsisten.

tombol

Dalam panduan ini, Anda akan mempelajari mengapa kata kerja tidak termasuk dalam URL REST, cara merancang titik akhir berorientasi sumber daya, dan bagaimana Modern PetstoreAPI mengimplementasikan ini dengan benar.

Masalah Kata Kerja dalam API REST

Kata kerja tindakan dalam URL menunjukkan bahwa Anda berpikir dalam istilah RPC (Remote Procedure Call), bukan istilah REST.

URL Gaya RPC (Salah)

POST /createUser
GET /getUser?id=123
PUT /updateUser
DELETE /deleteUser?id=123
GET /findUsersByRole?role=admin
POST /sendEmail
GET /calculateTotal

URL ini menjelaskan tindakan. Mereka terbaca seperti panggilan fungsi: createUser(), getUser(), sendEmail().

URL Gaya REST (Benar)

POST /users
GET /users/123
PUT /users/123
DELETE /users/123
GET /users?role=admin
POST /emails
GET /orders/123/total

URL ini menjelaskan sumber daya. Metode HTTP menyediakan tindakan.

Mengapa Ini Penting

Konsistensi: URL REST mengikuti pola yang dapat diprediksi. Setelah Anda mengetahui nama sumber dayanya, Anda mengetahui semua titik akhirnya:

• GET /pets - Daftar hewan peliharaan
• POST /pets - Buat hewan peliharaan
• GET /pets/{id} - Dapatkan hewan peliharaan
• PUT /pets/{id} - Perbarui hewan peliharaan
• DELETE /pets/{id} - Hapus hewan peliharaan

Dengan URL berbasis kata kerja, setiap titik akhir bersifat unik. Tidak ada pola untuk diikuti.

Skalabilitas: Seiring pertumbuhan API Anda, URL berbasis kata kerja akan bertambah banyak:

• /findPetsByStatus
• /findPetsByTags
• /findPetsByOwner
• /findPetsByBreed
• /searchPets
• /queryPets

URL berorientasi sumber daya menggunakan parameter kueri:

• GET /pets?status=available
• GET /pets?tags=friendly
• GET /pets?owner=john
• GET /pets?breed=labrador

Satu titik akhir menangani semua penyaringan.

Mengapa Metode HTTP Adalah Kata Kerja

REST memanfaatkan kata kerja bawaan HTTP. Anda tidak perlu menciptakan sendiri.

Pemetaan Metode HTTP ke Operasi CRUD

POST   → Create
GET    → Read
PUT    → Update (replace)
PATCH  → Update (partial)
DELETE → Delete

Metode-metode ini memiliki semantik yang ditentukan. GET aman dan idempoten. POST membuat sumber daya. DELETE menghapusnya.

Contoh: Manajemen Pengguna

Salah (kata kerja dalam URL):

POST /createUser
GET /getUser?id=123
POST /updateUser
POST /deleteUser

Setiap operasi menggunakan URL yang berbeda. Metode HTTP tidak menyampaikan makna.

Benar (metode HTTP sebagai kata kerja):

POST /users           ← Buat pengguna
GET /users/123        ← Dapatkan pengguna
PUT /users/123        ← Perbarui pengguna
DELETE /users/123     ← Hapus pengguna

URL tetap sama. Metode berubah.

Manfaat Menggunakan Metode HTTP

1. Caching: Permintaan GET dapat di-cache. Browser dan proxy mengetahui hal ini. Jika Anda menggunakan POST /getUser, caching akan rusak.

2. Idempoten: PUT dan DELETE bersifat idempoten. Memanggilnya beberapa kali memiliki efek yang sama dengan memanggilnya sekali. Ini penting untuk logika percobaan ulang (retry logic).

3. Keamanan: GET aman—tidak mengubah status. Alat dan perayap (crawler) dapat dengan aman memanggil titik akhir GET.

4. Kepatuhan Standar: Klien HTTP, proxy, dan cache memahami metode HTTP. Mereka tidak memahami kata kerja kustom Anda.

Contoh Nyata dari Swagger Petstore

Swagger Petstore lama menyertakan beberapa titik akhir berbasis kata kerja.

Contoh 1: Mencari Hewan Peliharaan berdasarkan Status

Swagger Petstore (Salah):

GET /pet/findByStatus?status=available

Masalah:

• findByStatus adalah frasa kata kerja
• Tidak konsisten dengan titik akhir /pet/{id}
• Tidak dapat diperluas dengan mudah (bagaimana jika mencari berdasarkan kriteria lain?)

Modern PetstoreAPI (Benar):

GET /pets?status=AVAILABLE

Manfaat:

• Berorientasi sumber daya (/pets)
• Menggunakan parameter kueri untuk penyaringan
• Konsisten dengan titik akhir lainnya
• Mudah diperluas: GET /pets?status=AVAILABLE&species=dog

Lihat dokumentasi REST Modern PetstoreAPI untuk implementasi lengkapnya.

Contoh 2: Mencari Hewan Peliharaan berdasarkan Tag

Swagger Petstore (Salah):

GET /pet/findByTags?tags=tag1,tag2

Modern PetstoreAPI (Benar):

GET /pets?tags=friendly,trained

Contoh 3: Login Pengguna

Swagger Petstore (Salah):

GET /user/login?username=john&password=secret

Berbagai masalah:

• login adalah kata kerja
• Menggunakan GET untuk otentikasi (bencana keamanan)
• Kata sandi dalam parameter kueri URL

Modern PetstoreAPI (Benar):

POST /auth/login
Content-Type: application/json

{
  "username": "john",
  "password": "secret123"
}

Manfaat:

• Berorientasi sumber daya (/auth)
• Metode HTTP yang benar (POST)
• Kredensial dalam badan permintaan (request body), bukan URL
• Mengembalikan token JWT untuk permintaan selanjutnya

Bagaimana Modern PetstoreAPI Memperbaiki Ini

Modern PetstoreAPI menggunakan URL berorientasi sumber daya secara menyeluruh.

Manajemen Hewan Peliharaan

GET /pets                    ← Daftar semua hewan peliharaan
GET /pets?status=AVAILABLE   ← Filter berdasarkan status
GET /pets?species=dog        ← Filter berdasarkan spesies
GET /pets/{id}               ← Dapatkan hewan peliharaan tertentu
POST /pets                   ← Buat hewan peliharaan baru
PUT /pets/{id}               ← Perbarui hewan peliharaan
PATCH /pets/{id}             ← Perbarui sebagian
DELETE /pets/{id}            ← Hapus hewan peliharaan

Tidak ada kata kerja. Hanya sumber daya dan metode HTTP.

Manajemen Pesanan

GET /orders                  ← Daftar pesanan
GET /orders/{id}             ← Dapatkan pesanan
POST /orders                 ← Buat pesanan
PUT /orders/{id}             ← Perbarui pesanan
DELETE /orders/{id}          ← Batalkan pesanan
GET /orders/{id}/items       ← Dapatkan item pesanan

Operasi Kompleks

Untuk operasi yang tidak terpetakan dengan rapi ke CRUD, Modern PetstoreAPI menggunakan sub-sumber daya:

POST /orders/{id}/payment    ← Proses pembayaran untuk pesanan
POST /orders/{id}/shipment   ← Buat pengiriman untuk pesanan
POST /pets/{id}/adoption     ← Mulai proses adopsi

Ini masih berorientasi sumber daya. /orders/{id}/payment merepresentasikan sumber daya pembayaran untuk suatu pesanan.

Kapan Kata Kerja Tampak Diperlukan

Beberapa operasi tidak sesuai dengan model CRUD. Berikut cara menanganinya tanpa kata kerja dalam URL.

Operasi Pencarian

Salah:

GET /searchPets?query=labrador

Opsi Benar 1 (Parameter Kueri):

GET /pets?search=labrador

Opsi Benar 2 (Sumber Daya Pencarian):

GET /pets/search?q=labrador

Opsi Benar 3 (Metode QUERY):

QUERY /pets
Content-Type: application/json

{
  "query": "labrador",
  "filters": {
    "status": "AVAILABLE"
  }
}

Modern PetstoreAPI mendukung ketiga pola ini tergantung pada kompleksitasnya.

Perhitungan

Salah:

GET /calculateShipping?weight=10&destination=NY

Benar:

GET /shipping-estimates?weight=10&destination=NY

Sumber dayanya adalah "estimasi pengiriman," bukan tindakan perhitungan.

Operasi Batch

Salah:

POST /batchDeletePets

Benar:

DELETE /pets?ids=1,2,3

Atau gunakan sumber daya batch:

POST /pets/batch-operations
Content-Type: application/json

{
  "operation": "delete",
  "ids": [1, 2, 3]
}

Tindakan yang Mengubah Status

Salah:

POST /activateUser
POST /deactivateUser

Benar:

PATCH /users/{id}
Content-Type: application/json

{
  "status": "ACTIVE"
}

Perubahan status adalah pembaruan pada sumber daya.

Menguji Desain URL dengan Apidog

Apidog membantu Anda memvalidasi desain API REST dan mendeteksi penggunaan kata kerja di URL.

Impor Modern PetstoreAPI

1. Impor spesifikasi OpenAPI Modern PetstoreAPI
2. Apidog secara otomatis menghasilkan kasus uji
3. Tinjau struktur dan penamaan titik akhir

Periksa Kata Kerja dalam URL

Buat aturan validasi kustom di Apidog:

// Check if URL contains common action verbs
const verbs = ['get', 'create', 'update', 'delete', 'find', 'search',
               'calculate', 'process', 'send', 'fetch'];
const url = request.url.toLowerCase();

for (const verb of verbs) {
  if (url.includes(`/${verb}`)) {
    throw new Error(`URL contains verb: ${verb}. Use resource-oriented URLs instead.`);
  }
}

Uji Konsistensi Titik Akhir

Apidog dapat memverifikasi bahwa titik akhir yang terkait mengikuti pola yang konsisten:

✓ GET /pets
✓ POST /pets
✓ GET /pets/{id}
✓ PUT /pets/{id}
✓ DELETE /pets/{id}

Semua menggunakan sumber daya dasar yang sama (/pets).

Bandingkan dengan Modern PetstoreAPI

1. Impor API Anda dan Modern PetstoreAPI ke Apidog
2. Bandingkan struktur titik akhir secara berdampingan
3. Identifikasi inkonsistensi dan penggunaan kata kerja
4. Refaktor API Anda agar sesuai dengan prinsip REST

Strategi Migrasi

Jika Anda memiliki API yang sudah ada dengan kata kerja dalam URL, berikut adalah cara untuk bermigrasi.

Strategi 1: Pemversian

Buat versi API baru dengan URL yang benar:

# Old API (v1)
GET /api/v1/findPetsByStatus?status=available

# New API (v2)
GET /api/v2/pets?status=available

Pertahankan v1 untuk kompatibilitas mundur, anjurkan migrasi ke v2.

Strategi 2: Aliasing

Dukung URL lama dan baru untuk sementara:

# Old URL (deprecated)
GET /pet/findByStatus?status=available

# New URL (preferred)
GET /pets?status=available

Kembalikan peringatan pengabaian (deprecation warnings) dalam respons:

{
  "data": [...],
  "warnings": [
    {
      "code": "DEPRECATED_ENDPOINT",
      "message": "This endpoint is deprecated. Use GET /pets?status=available instead.",
      "sunset": "2027-01-01"
    }
  ]
}

Strategi 3: Pengalihan (Redirects)

Gunakan pengalihan HTTP 301 untuk migrasi sederhana:

GET /pet/findByStatus?status=available
→ 301 Moved Permanently
Location: /pets?status=available

Ini berfungsi untuk permintaan GET tetapi tidak untuk POST, PUT, atau DELETE.

Kesimpulan

URL API REST sebaiknya berisi kata benda (sumber daya), bukan kata kerja (tindakan). Metode HTTP menyediakan kata kerja. Prinsip ini menciptakan API yang konsisten, skalabel, dan mudah dikelola.

Swagger Petstore lama melanggar prinsip ini dengan titik akhir seperti /pet/findByStatus. Modern PetstoreAPI memperbaikinya dengan menggunakan URL berorientasi sumber daya secara menyeluruh: /pets?status=AVAILABLE.

Poin-poin penting:

• Gunakan kata benda dalam URL: /pets, /orders, /users
• Biarkan metode HTTP menjadi kata kerja: GET, POST, PUT, DELETE
• Gunakan parameter kueri untuk penyaringan: /pets?status=available
• Untuk operasi kompleks, gunakan sub-sumber daya: /orders/{id}/payment
• Uji desain API Anda dengan Apidog untuk mendeteksi penggunaan kata kerja sejak dini

Lihat dokumentasi Modern PetstoreAPI untuk contoh lengkap desain URL berorientasi sumber daya.

FAQ

Bisakah saya menggunakan kata kerja dalam URL REST?

Jarang sekali. Jika suatu operasi benar-benar tidak sesuai dengan model sumber daya (seperti /search atau /login), kata kerja mungkin dapat diterima. Namun 95% dari waktu, Anda dapat memodelkannya sebagai sumber daya.

Bagaimana dengan /login dan /logout?

Ini adalah pengecualian umum. Banyak API menggunakan /auth/login dan /auth/logout. Alternatifnya, modelkan mereka sebagai sumber daya: POST /sessions (login) dan DELETE /sessions/{id} (logout).

Bagaimana cara menangani kueri kompleks?

Gunakan parameter kueri untuk penyaringan sederhana: /pets?status=available&species=dog. Untuk kueri kompleks, gunakan metode HTTP QUERY atau sumber daya pencarian: POST /pets/search.

Bagaimana jika operasi saya tidak memetakan ke CRUD?

Modelkan sebagai sub-sumber daya. Alih-alih POST /processPayment, gunakan POST /orders/{id}/payment. Pembayaran adalah sumber daya yang terkait dengan pesanan.

Bagaimana cara menguji apakah URL saya berorientasi sumber daya?

Gunakan Apidog untuk mengimpor spesifikasi OpenAPI Anda dan memeriksa kata kerja dalam URL. Bandingkan struktur API Anda dengan Modern PetstoreAPI sebagai referensi.

Haruskah saya menggunakan /pets/search atau /pets?search=query?

Keduanya dapat diterima. /pets?search=query lebih sederhana untuk pencarian dasar. /pets/search atau QUERY /pets bekerja lebih baik untuk pencarian kompleks dengan banyak parameter.

Bagaimana cara bermigrasi dari URL berbasis kata kerja?

Gunakan pemversian API (/v2/pets daripada /v1/findPets), tambahkan peringatan pengabaian, dan berikan waktu kepada klien untuk bermigrasi. Lihat bagian Strategi Migrasi untuk detailnya.

Apakah Modern PetstoreAPI menggunakan kata kerja dalam URL?

Modern PetstoreAPI menghindari kata kerja dalam URL. Operasi seperti pencarian, penyaringan, dan otentikasi dimodelkan sebagai sumber daya atau menggunakan parameter kueri. Periksa dokumentasi API REST untuk contohnya.