หลักเกณฑ์การตั้งชื่อ REST API: แนวทางปฏิบัติ

เปิดโค้ดเบสใดๆ ที่มีอายุเกินสองปี คุณจะพบร่องรอยเหล่านี้: /getUser, /user_list, /Users/fetchAll, รูปแบบการแบ่งหน้าสามแบบที่แตกต่างกัน, และฟิลด์ customerID ที่อยู่ข้าง order_id ในการตอบกลับเดียวกัน ไม่มีสิ่งใดที่ทำให้ระบบพัง แต่ทั้งหมดทำให้ทุกคนทำงานช้าลง

การตั้งชื่อเป็นการตัดสินใจออกแบบ API ที่ถูกที่สุดที่คุณเคยทำ และเป็นสิ่งที่แพงที่สุดที่จะแก้ไข เมื่อไคลเอนต์ขึ้นอยู่กับ /getOrders แล้ว คุณจะต้องสนับสนุนมันไปอีกหลายปี คู่มือนี้จะให้กฎที่ชัดเจนสำหรับการตัดสินใจตั้งชื่อทุกครั้งที่ REST API บังคับใช้กับคุณ พร้อมตัวอย่างและตัวอย่างที่ไม่ดีสำหรับแต่ละข้อ ซึ่งเป็นแนวคิดเดียวกับ แนวทางปฏิบัติที่ดีที่สุดสำหรับนักพัฒนา REST API ที่กว้างขึ้นของเรา แต่จะเน้นไปที่ส่วนที่ทีมมักจะถกเถียงกันมากที่สุด: จะเรียกสิ่งต่างๆ ว่าอย่างไร

หากคุณต้องการบังคับใช้กฎเหล่านี้ด้วยเครื่องมือมากกว่าการคอมเมนต์รีวิวโค้ด Apidog ช่วยให้คุณกำหนดเอนด์พอยต์ทุกตัวด้วยภาพตามสคีมาที่แชร์ไว้ก่อนที่ใครจะเขียนโค้ดเพิ่มเติม เราจะกล่าวถึงเรื่องนี้เพิ่มเติมในตอนท้าย

ใช้คำนามพหูพจน์สำหรับคอลเล็กชัน

URL จะระบุชื่อทรัพยากร ไม่ใช่การดำเนินการ คอลเล็กชันคือชุดของสิ่งต่างๆ ดังนั้นควรตั้งชื่อเป็นคำนามพหูพจน์

ทำ:

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

ไม่ควรทำ:

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

รูปแบบพหูพจน์ใช้งานได้ทั้งสองระดับ /products หมายถึง “คอลเล็กชันของผลิตภัณฑ์” และ /products/89 หมายถึง “ผลิตภัณฑ์หมายเลข 89 ภายในคอลเล็กชัน” การตั้งชื่อแบบเอกพจน์ทำให้ URL ดูไม่เป็นธรรมชาติ เช่น /product/89 สำหรับหนึ่งรายการ แต่เป็น /product สำหรับหลายรายการ ซึ่งอ่านแล้วไม่ถูกต้อง แนวทางปฏิบัติของ Microsoft REST API ได้เลือกใช้คำนามพหูพจน์ด้วยเหตุผลนี้ และ API สาธารณะส่วนใหญ่ (Stripe, GitHub, Shopify) ก็ใช้แนวทางเดียวกัน

มีข้อยกเว้นหนึ่งอย่าง: ทรัพยากรแบบซิงเกิลตัน (singleton resources) หากผู้ใช้มีตะกร้าสินค้าเพียงหนึ่งเดียว /users/42/cart ก็ใช้ได้ อย่าทำให้สิ่งที่มีจำนวนเดียวเป็นพหูพจน์

หลีกเลี่ยงการใช้คำกริยาในพาธ

เมธอด HTTP คือคำกริยา การใส่คำกริยาอื่นลงในพาธจะซ้ำซ้อนข้อมูลและทำลายโมเดลทรัพยากร

ทำ:

GET    /v1/orders/42      (read it)
DELETE /v1/orders/42      (delete it)
PATCH  /v1/orders/42      (update it)

ไม่ควรทำ:

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

พาธที่อิงคำกริยายังเพิ่มพื้นที่การทำงานของคุณ ทรัพยากรหนึ่งที่มีสี่เมธอดจะกลายเป็นสี่เอนด์พอยต์ที่ต้องทำเอกสาร ทดสอบ และแคชแยกกัน การทำให้แคชเป็นโมฆะก็แย่ลงด้วย: CDN สามารถแคช GET /v1/orders/42 และทำให้เป็นโมฆะเมื่อ DELETE /v1/orders/42 เนื่องจากทั้งสองชี้ไปที่ URL เดียวกัน ไม่สามารถเชื่อมต่อ /fetchOrder/42 กับ /deleteOrder/42 ได้

ใช้ kebab-case ในพาธ URL

ส่วนของพาธที่มีหลายคำต้องมีตัวคั่น และเครื่องหมายขีดกลาง (- หรือ hyphen) คือตัวที่เหมาะสม

ทำ:

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

ไม่ควรทำ:

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

มีสามเหตุผล Google ถือว่าเครื่องหมายขีดกลางเป็นตัวคั่นคำสำหรับการจัดทำดัชนี ดังนั้นเอกสาร API สาธารณะจึงมีอันดับที่ดีกว่าด้วย kebab-case เครื่องหมายขีดล่างจะหายไปเมื่อ URL ถูกขีดเส้นใต้ในอีเมลหรือเอกสาร และ camelCase ใน URL เชิญชวนให้เกิดข้อผิดพลาดในการแยกแยะตัวพิมพ์ใหญ่-เล็ก: /giftCards และ /giftcards เป็น URL ที่แตกต่างกันบนเซิร์ฟเวอร์ส่วนใหญ่ และจะมีคนพิมพ์ผิดแน่นอน แนวทางปฏิบัติของ Zalando RESTful API กำหนดให้ kebab-case เป็นกฎที่ต้องทำ และพวกเขาได้นำแนวทางนี้ไปใช้กับบริการภายในหลายร้อยรายการ

เลือกรูปแบบการตั้งชื่อ JSON แบบเดียวและบันทึกไว้

สำหรับชื่อฟิลด์ภายในเนื้อหาคำขอและการตอบกลับ คำตอบที่ตรงไปตรงมาคือ: camelCase และ snake_case ใช้งานได้ทั้งคู่ สิ่งที่ไม่ควรทำคือการนำมาผสมกัน

ทำ (เลือกอย่างใดอย่างหนึ่งอย่างสม่ำเสมอ):

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

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

ไม่ควรทำ:

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

camelCase สามารถจับคู่กับไคลเอนต์ JavaScript และ Java ได้อย่างสะอาดตา ส่วน snake_case อ่านง่ายกว่าและเข้ากับ Ruby, Python รวมถึงชื่อคอลัมน์ SQL ส่วนใหญ่; Stripe ใช้มันทุกที่ เลือกตามว่าใครใช้ API ของคุณมากที่สุด จากนั้นระบุทางเลือกนี้ไว้ในสไตล์ไกด์ของคุณ เพื่อให้การถกเถียงเกิดขึ้นเพียงครั้งเดียว แทนที่จะเกิดขึ้นกับทุก pull request การใช้รูปแบบผสมกันเป็นความไม่สอดคล้องกันที่พบบ่อยที่สุดใน API จริง เนื่องจากทีมต่างๆ ส่งมอบเอนด์พอยต์ที่แตกต่างกัน นี่คือความล้มเหลวในการกำกับดูแล ไม่ใช่ความล้มเหลวของรสนิยม

จำกัดการซ้อนกันไม่เกินสองระดับ

การซ้อนกันแสดงถึงความเป็นเจ้าของ: /users/42/orders หมายถึง “คำสั่งซื้อที่เป็นของผู้ใช้ 42” ซึ่งมีประโยชน์ แต่เมื่อเกินสองระดับขึ้นไปก็จะไม่เป็นประโยชน์แล้ว

ทำ:

GET /v1/users/42/orders
GET /v1/orders/1337/refunds

ไม่ควรทำ:

GET /v1/users/42/orders/1337/refunds/7/status

การซ้อนกันลึกๆ บังคับให้ไคลเอนต์ต้องพก ID ของบรรพบุรุษทุกตัวเพื่อเข้าถึงทรัพยากรปลายทาง แม้ว่าทรัพยากรปลายทางนั้นจะมี ID ที่ไม่ซ้ำกันทั่วโลกของตัวเองก็ตาม หากการคืนเงินมี ID 7 ให้เปิดเผยที่ /refunds/7 หรือ /orders/1337/refunds/7 และหยุดแค่นั้น การทดสอบกลิ่นที่ดี: หาก URL มี ID สามตัวขึ้นไป ให้ทำให้มันแบนราบ เมื่อคำสั่งซื้อมีอยู่แล้ว ไม่จำเป็นต้องมีผู้ใช้ในพาธอีกต่อไป; /orders/1337 สามารถยืนอยู่ได้ด้วยตัวเอง

ใส่การกรอง การเรียงลำดับ และการแบ่งหน้าในพารามิเตอร์คิวรี

พาธระบุทรัพยากร พารามิเตอร์คิวรีแก้ไขวิธีที่คุณดูทรัพยากรเหล่านั้น อย่าเข้ารหัสตัวกรองลงในพาธเด็ดขาด

ทำ:

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

ไม่ควรทำ:

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

รูปแบบ sort=-created_at (มีเครื่องหมายลบนำหน้าสำหรับการเรียงลำดับจากมากไปน้อย) มาจากข้อกำหนด JSON:API และช่วยให้คุณไม่ต้องใช้พารามิเตอร์ order=desc ตัวที่สอง พาธตัวกรองเช่น /orders/active ดูไม่เป็นอันตรายจนกว่าคุณจะต้องรวมตัวกรองหลายตัวเข้าด้วยกัน จากนั้นคุณจะต้องสร้างเอนด์พอยต์ใหม่สำหรับการรวมกันแต่ละแบบ ชื่อพารามิเตอร์การแบ่งหน้าก็ควรมีระเบียบวินัยเช่นเดียวกัน: เลือก limit/cursor หรือ page/per_page เพียงครั้งเดียวและนำกลับมาใช้ใหม่กับทุกคอลเล็กชัน คู่มือการแบ่งหน้า API ของเราครอบคลุมข้อดีข้อเสียระหว่าง cursor กับ offset อย่างละเอียด; กฎการตั้งชื่อในที่นี้เพียงแค่บอกให้คุณใช้มันอย่างสม่ำเสมอ

การกำหนดเวอร์ชันในพาธ

คุณมีสองทางเลือกหลัก: การระบุเวอร์ชันในส่วนของพาธ (/v1/products) หรือในเฮดเดอร์ (Accept: application/vnd.myapi.v1+json) การระบุเวอร์ชันในเฮดเดอร์เป็นแนวทาง REST ที่ “บริสุทธิ์” กว่า เนื่องจาก URL ยังคงระบุชื่อทรัพยากรเดิมในทุกเวอร์ชัน และ แนวทางการออกแบบ API ของ Google ระบุว่าทั้งสองวิธีมีอยู่จริง แต่การระบุเวอร์ชันในพาธมีข้อดีในเชิงปฏิบัติมากกว่า: มันมองเห็นได้ในทุกบรรทัดของล็อก สามารถทดสอบได้จากเบราว์เซอร์ สามารถแคชได้โดยไม่ต้องใช้ Vary ที่ซับซ้อน และไคลเอนต์ไม่สามารถลืมได้ นักพัฒนาทุกคนที่เคยแก้ไขข้อผิดพลาด “ใช้งานได้ใน curl แต่ล้มเหลวใน prod” ที่เกิดจากเฮดเดอร์เวอร์ชันที่หายไป ย่อมรู้ถึงค่าใช้จ่ายของทางเลือกนี้ ใช้ /v1/ กับเวอร์ชันหลักเท่านั้น ห้ามใช้ /v1.2/; การเปลี่ยนแปลงเล็กน้อยควรเป็นการเพิ่มเติมและไม่กระทบต่อการทำงาน สำหรับแผนผังการตัดสินใจทั้งหมด รวมถึงการเจรจาเนื้อหา โปรดดูการเปรียบเทียบ กลยุทธ์การกำหนดเวอร์ชัน API ของเรา

ถือว่า ID ทรัพยากรเป็นแบบทึบ และอย่าเปิดเผยตัวเลขลำดับอย่างไม่ระมัดระวัง

/orders/41, /orders/42, /orders/43: ID ที่เป็นตัวเลขลำดับบอกให้ทุกคนที่มองเห็นรู้ว่าคุณประมวลผลคำสั่งซื้อไปแล้วกี่รายการ และยังเปิดช่องให้เกิดการโจมตีแบบ enumeration attacks ซึ่งผู้โจมตีจะไล่สำรวจพื้นที่ ID เพื่อหาช่องโหว่ด้านการอนุญาต ข้อผิดพลาดประเภทนี้ ซึ่งคือ Broken Object Level Authorization อยู่ในอันดับหนึ่งของ OWASP API Security Top 10

ทำ:

GET /v1/orders/ord_9f8e2a71b3
GET /v1/users/550e8400-e29b-41d4-a716-446655440000

ไม่ควรทำ (เมื่อการแจกแจงมีความสำคัญ):

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

ID สุ่มที่มีคำนำหน้า เช่น ord_9f8e2a71b3 ของ Stripe เป็นรูปแบบที่แข็งแกร่งที่สุด: เดาไม่ได้ อธิบายตัวเองได้ในบันทึก และปลอดภัยที่จะเปิดเผย การตรวจสอบการอนุญาตยังคงเป็นสิ่งจำเป็นไม่ว่าจะใช้วิธีใด ID แบบทึบลดขนาดของผลกระทบจากการขาดการตรวจสอบ แต่ไม่ได้มาแทนที่ ภายในคุณสามารถเก็บ Primary Key ที่เป็นตัวเลขได้; กฎนี้เกี่ยวกับสิ่งที่คุณเปิดเผยใน URL

จำลองการกระทำที่ไม่ใช่ CRUD เป็นทรัพยากรตัวควบคุม

ไม่ช้าก็เร็วคุณจะต้องมีการดำเนินการที่ไม่มีการจับคู่ CRUD ที่ชัดเจน เช่น การยกเลิกคำสั่งซื้อ การลองชำระเงินใหม่ การส่งอีเมลซ้ำ อย่าส่งผ่าน PATCH บนฟิลด์สถานะ และอย่าวางคำกริยาไว้ในระดับบนสุด

ทำ:

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

ไม่ควรทำ:

PATCH /v1/orders/42        { "status": "cancelled" }
POST  /v1/cancelOrder      { "orderId": 42 }

นี่คือรูปแบบของตัวควบคุม และเป็นข้อยกเว้นเดียวที่ได้รับอนุญาตสำหรับกฎห้ามใช้คำกริยา: คำกริยาจะอยู่ท้ายพาธ ภายใต้ทรัพยากรที่เกี่ยวข้อง วิธีการ PATCH ดูเหมือน RESTful แต่ซ่อนสถานะการทำงานไว้ภายในการอัปเดตฟิลด์ การยกเลิกคำสั่งซื้อจะกระตุ้นการคืนเงิน การปล่อยสินค้าคงคลัง และการส่งการแจ้งเตือน; การแสร้งทำว่าเป็นเพียงการเขียนฟิลด์จะบังคับให้เซิร์ฟเวอร์ของคุณต้องเปรียบเทียบ payloads เพื่อตรวจจับเจตนา เอนด์พอยต์ /cancel จะระบุเจตนา ให้สิทธิ์และการตรวจสอบเฉพาะสำหรับการกระทำนั้น และเปิดพื้นที่สำหรับข้อมูลเฉพาะการกระทำ เช่น เหตุผลในการยกเลิก

รักษาความสอดคล้องของรูปแบบตัวอักษรสำหรับส่วนหัวและพารามิเตอร์คิวรี

สองส่วนเล็กๆ ที่มีระเบียบวินัยเดียวกัน ส่วนหัวแบบกำหนดเองใช้ Hyphenated-Pascal-Case เพื่อให้ตรงตามข้อกำหนดของ HTTP: Idempotency-Key, Request-Id ละทิ้งคำนำหน้า X- เก่า; เนื่องจากถูกยกเลิกการใช้งานโดย RFC 6648 ในปี 2012 ชื่อส่วนหัวไม่คำนึงถึงตัวพิมพ์ใหญ่-เล็กเมื่อส่งข้อมูล แต่เอกสารและ SDK ของคุณยังคงควรกำหนดวิธีการเขียนเพียงแบบเดียว

พารามิเตอร์คิวรีควรตรงกับรูปแบบตัวอักษรของเนื้อหา JSON ของคุณ หากเนื้อหาของคุณใช้ snake_case ให้เขียน ?min_price=1000&created_after=2026-01-01 ไม่ใช่ ?minPrice=1000 นักพัฒนาที่อ่าน created_at ในการตอบกลับและต้องพิมพ์ createdAfter ในคิวรีจะพิมพ์ผิดตั้งแต่ครั้งแรก และคนอื่นๆ หลังจากนั้นก็จะพิมพ์ผิดเช่นกัน

ชุดกฎฉบับเต็มโดยสรุป

การบังคับใช้ข้อตกลงในวงกว้าง

คู่มือสไตล์ในวิกิไม่ได้เปลี่ยนแปลงอะไรเลย ทีมที่ API ของพวกเขายังคงสอดคล้องกันมีนิสัยหนึ่งที่เหมือนกัน: พวกเขาออกแบบก่อนและบังคับใช้ข้อตกลงก่อนที่จะมีโค้ด ซึ่งเป็นแกนหลักของการ กำกับดูแล API ในทางปฏิบัติ

นี่คือจุดที่ Apidog เข้ามามีบทบาทในเวิร์กโฟลว์ เอนด์พอยต์ถูกกำหนดในตัวออกแบบภาพแบบ schema-first ดังนั้นพาธ รูปแบบตัวอักษร และชื่อพารามิเตอร์จึงเป็นส่วนประกอบการออกแบบที่ชัดเจน แทนที่จะเป็นสตริงที่ฝังอยู่ในโค้ดคอนโทรลเลอร์ คอมโพเนนต์ที่ใช้ร่วมกันหมายความว่า สคีมาของ Pagination, Error และ Money ถูกกำหนดเพียงครั้งเดียวและนำกลับมาใช้ใหม่ในทุกเอนด์พอยต์; ไม่มีใครสร้าง per_page ขึ้นมาใหม่เป็น pageSize ในบริการใหม่ และเนื่องจากการออกแบบอยู่ในพื้นที่ทำงานของทีมพร้อมการรีวิวในตัว หัวหน้าทีมสามารถตรวจจับ /getUserOrders ได้ตั้งแต่ขั้นตอนการออกแบบ เมื่อการเปลี่ยนชื่อใช้เพียงคลิกเดียว แทนที่จะเป็นหลังจากมีไคลเอนต์สามรายเชื่อมต่อใช้งานไปแล้ว จากนั้นสเปคก็จะขับเคลื่อนเอกสาร เซิร์ฟเวอร์จำลอง และการทดสอบ ดังนั้นชื่อที่คุณอนุมัติจึงเป็นชื่อที่ทุกคนใช้งาน ดาวน์โหลด Apidog และทดลองใช้ฟรีกับเอนด์พอยต์ใหม่ของคุณ; การปรับปรุง API เก่าเป็นเรื่องยาก แต่การรักษามาตรฐานสำหรับ API ใหม่ไม่ใช่เรื่องยาก

คำถามที่พบบ่อย

URL ของ REST ควรเป็นพหูพจน์หรือเอกพจน์?

พหูพจน์ สำหรับทรัพยากรใดๆ ที่มีมากกว่าหนึ่งอินสแตนซ์: /products, /orders, /users รูปแบบพหูพจน์ยังคงเป็นธรรมชาติทั้งสำหรับคอลเล็กชัน (/orders) และสมาชิกหนึ่งตัว (/orders/42) สงวนชื่อเอกพจน์ไว้สำหรับ singletons จริงๆ เช่น /users/42/cart หากคุณต้องการเหตุผลที่ลึกซึ้งเบื้องหลังการสร้างแบบจำลองทรัพยากร คู่มือของเราเกี่ยวกับ REST API คืออะไร จะอธิบายตั้งแต่หลักการพื้นฐาน

camelCase หรือ snake_case แบบไหนดีกว่าสำหรับชื่อฟิลด์ JSON?

ไม่มีรูปแบบใดที่ดีกว่าโดยสมบูรณ์ camelCase เหมาะสำหรับผู้ใช้งานที่เน้น JavaScript; snake_case อ่านง่ายกว่าและเข้ากับ Python, Ruby และ Stripe’s public API กฎที่สำคัญคือ: เลือกแบบใดแบบหนึ่ง เขียนลงในคู่มือสไตล์ของคุณ และบังคับใช้ในการรีวิวสคีมา การใช้รูปแบบผสมกันในเอนด์พอยต์ต่างๆ สร้างปัญหามากกว่าการเลือกแบบใดแบบหนึ่ง

ฉันควรใส่เวอร์ชัน API ใน URL หรือในส่วนหัว (header)?

ใช้พาธ (/v1/orders) เว้นแต่คุณมีความต้องการ hypermedia ที่แข็งแกร่ง เวอร์ชันในพาธจะปรากฏในล็อก แคช และการทดสอบในเบราว์เซอร์โดยที่ไคลเอนต์ไม่ต้องทำอะไร การระบุเวอร์ชันในเฮดเดอร์ช่วยให้ URL เสถียรในทุกเวอร์ชัน แต่จะล้มเหลวเงียบๆ เมื่อไคลเอนต์ลืมใส่เฮดเดอร์ ใช้เฉพาะเวอร์ชันหลักเท่านั้น; การเปลี่ยนแปลงเล็กน้อยควรกระทำเป็นการอัปเดตเพิ่มเติมที่ไม่กระทบต่อการทำงาน

คำกริยาสามารถยอมรับได้ในพาธ REST API หรือไม่?

ได้ ในที่เดียว: เอนด์พอยต์ตัวควบคุมสำหรับการกระทำที่ไม่ใช่ CRUD เช่น POST /orders/42/cancel หรือ POST /payments/pay_88a1/retry คำกริยาจะอยู่ท้ายพาธ ภายใต้ทรัพยากรที่เกี่ยวข้อง และเมธอดจะเป็น POST เสมอ ในส่วนอื่นๆ เมธอด HTTP จะทำหน้าที่เป็นคำกริยา และพาธจะประกอบด้วยคำนามเท่านั้น