URI Naming

URI คือชื่อของ resource การตั้งชื่อที่สอดคล้องกันทำให้ developer เดา endpoint ตัวถัดไปได้ถูกโดยไม่ต้องเปิด docs และนั่นคือคำชมสูงสุดที่ API หนึ่งตัวจะได้รับ

แนวปฏิบัติ

คำนาม ไม่ใช่คำกริยา — /articles ไม่ใช่ /getArticles ตัว method คือคำกริยา
collection เป็นพหูพจน์ — /articles คือ collection ส่วน /articles/42 คือหนึ่ง item ในนั้น เลือกใช้พหูพจน์แล้วยึดไว้ให้ตลอด
ตัวพิมพ์เล็กคั่นด้วยขีดกลาง — /blog-posts ไม่ใช่ /blogPosts หรือ /Blog_Posts path นั้นโดยจิตวิญญาณแล้วแยกตัวพิมพ์เล็กใหญ่ จงเก็บให้เป็นตัวพิมพ์เล็กเพื่อเลี่ยงเรื่องเซอร์ไพรส์
ID อยู่ใน path ไม่ใช่ใน query — /articles/42 ไม่ใช่ /articles?id=42 query string มีไว้สำหรับ filter collection ไม่ใช่ระบุตัว item
ไม่มีนามสกุลไฟล์ — /articles/42 ไม่ใช่ /articles/42.json ให้ใช้ header Accept ในการเจรจารูปแบบ (format negotiation)
แนวปฏิบัติเรื่อง trailing slash — เลือกว่าจะมีหรือไม่มีและทำให้สอดคล้องกัน (API ส่วนใหญ่ละไว้)

ดีกับไม่ดี

GET /articles                 # collection
GET /articles/42              # one item
GET /articles/42/comments     # that item's comments
GET /articles?status=draft    # filtered collection

# Avoid:
GET /getArticles
GET /article/42               # inconsistent singular
GET /articles/42.json
GET /articles?articleId=42    # identity belongs in the path

URI Convention	ดี	ไม่ดี
Plural noun	`/users`, `/orders`	`/user`, `/getOrders`
Lowercase + hyphen	`/blog-posts`, `/line-items`	`/blogPosts`, `/Blog_Posts`
Hierarchy แสดง ownership	`/users/\{id\}/orders`	`/getUserOrders?userId=\{id\}`
ไม่มี verb ใน URI	`/orders/\{id\}/cancellation`	`/cancelOrder/\{id\}`

ข้อผิดพลาดที่พบบ่อย

ผสม Naming Convention อาการ:

GET /userProfiles และ GET /order-items ใน API เดียวกัน
developer ต้องจำว่า endpoint ไหนใช้ convention ไหน
กำหนด convention เดียวแล้วยึดตลอด — ส่วนมากใช้ plural lowercase

ใส่ Version ผิดที่ อาการ:

/users/v2 — version อยู่ตรงกลาง URI
/v1/users/v2/profile — version ซ้อนกัน
version อยู่ต้น URI เสมอ: /v1/users/\{id\}/profile

💡 ตัวอย่างจากของจริง

GitHub API:

/repos (plural), /issues, /pulls, /commits — consistent plural

/repos/\{owner\}/\{repo\}/git/refs — hierarchy ชัดเจน

Stripe API:

/payment_intents, /payment_methods, /setup_intents

ใช้ snake_case สม่ำเสมอทั้ง API