Should Use: เอกพจน์ or พหูพจน์ ? - REST API

REST หรือ Representational State Transfer ได้รับการพัฒนาเป็นวิทยานิพนธ์ โดย Roy Fielding หนึ่งในผู้เขียน HTTP protocol โดย Mr. Fielding เสนอให้ใช้ HTTP เพื่อสื่อสารระหว่าง inter-computer ดังนั่น REST จึง based on HTTP standard การเข้าถึง Resource ใน HTTP จะอ้างอิงผ่าน Namespace สิ่งนี้เรียกว่า URI paths โดยที่แต่ละ URI จะต้องที่ไม่ซ้ำกัน

URI paths

การตั้ง URI Paths ควรใช้คำ Nouns ไม่ควรใช้ Verbs เพราะว่ามันคือสิ่งที่เอาไว้อ้างอิงถึง Resource ไม่ใช้เอาไว้บอกว่าจะทำอะไรกับ Resource

ใช้ Nouns

API /cats หรือ /cat ถ้าเราต้องการทำ Action ใดๆ กับ Resource เราจะใช้สิ่งที่เรียกว่า Http Method คือ POST, GET, PUT and DELETE หรือที่เราคุ้นเคยกัน CRUD (Create-Read-Update-Delete)

ใช้ Verbs

/getAllCats
/getCat
/newCat
/createCat
/updateAllCats
/updateCat
/deleteCat
/deleteAllCats

Singular or

Roy Fielding ได้อธิบายในวิทยานิพนธ์ Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures

The definition of resource in REST is based on a simple premise: identifiers should change as infrequently as possible. Because the Web uses embedded identifiers rather than link servers, authors need an identifier that closely matches the semantics they intend by a hypermedia reference, allowing the reference to remain static even though the result of accessing that reference may change over time. REST accomplishes this by defining a resource to be the semantics of what the author intends to identify, rather than the value corresponding to those semantics at the time the reference is created. It is then left to the author to ensure that the identifier chosen for a reference does indeed identify the intended semantics.

สรุป การตั้ง Resource Names (หรือ PATH) ควรเปลี่ยนไม่บ่อย ถ้าเปลี่ยน ต้องเปลี่ยนเท่าที่จำเป็น และการกำหนดขึ้นอยู่กับผู้ออกแบบ ไม่มีอะไรเกี่ยวกับเอกพจน์หรือพหูพจน์ ดังนั่น เราสามารถตั้ง Resource Names แบบไหนก็ได้ ขอแค่ Resource Names นั่นหมายถึง Resource ที่ต้องการเข้าถึงจริงๆ

ตามหลักการ REST เราสามารถเลือกใช้ เอกพจน์ หรือ พหูพจน์ ก็ได้ แต่สิ่งที่สำคัญคือ

• ไม่ควรเปลี่ยนบ่อย ถ้า Resource ที่เราต้องการเข้าถึงคือตัวเดิม Resource Names ก็ควรเป็นตัวอ้างอิงตัวเดิม ถึงแม้ว่า Resource ที่ได้จะเปลี่ยนแปลงไปภายหลังก็ตาม
• Resource Names ต้องหมายถึง Resource ไม่ใช่คำที่เกี่ยวข้อง หรือคำที่ใกล้เคียง จะต้องเฉพาะเจาะจง ถึง Resource นั่นจริงๆ

ในวิทยานิพนธ์มีพูดถึง hypermedia ถ้าใครสนใจลองไปอ่านเกี่ยวกับ REST Architectural Constraints

Popular APIs

• Google

• Github

• Twitter

My reasoned

• ไม่เปลี่ยนบ่อย มันไม่ควรเปลี่ยนบ่อยถึงแม้ Resource ที่ได้จะเปลี่ยนไป ตัวอย่างเช่น /cats กับ /cats/catId ถึงแม้ Resource ที่ได้จะเปลี่ยนไปแต่ Resource Names ยังเป็นตัวเดิม
• ตรงไปตรงมา ถ้าใช้เอกพจน์ Get /cat ได้ข้อมูล list ของ cat มันดูไม่ Make Sense
• keep simple things simple ควรจะออกแบบให้ง่ายและคาดเดาได้ ตัวอย่าง สมมุติ developer เคยใช้ API /cats/catId ได้รับข้อมูลของ cat 1 ตัว ถ้าเขาต้องการข้อมูล list ของ cat เขาควรจะคาดเดาได้ว่าควรเรียก API /cats ไม่ใช่ /cat-all หรือ /cat-get-all หรือ /cat-list หรือ Ctrl + F to PDF

Use verbs

การใช้ Verbs ในการตั้ง Resource Names ไม่ใช่เรื่องแปลกถ้า API เส้นนั่นไม่ได้ Response ข้อมูลที่เกี่ยวข้องกับ Resource โดยตรง เช่น

- Calculate เอาค่าจาก Resource มาคำนวณแต่ไม่ได้ Response กลับไป

- Translate แปลจากภาษา A To ฮ ห

- Convert ค่า THB To BTC ตัวอย่างที่ยกมาไม่ได้ส่งคืน Resource จากระบบโดยตรง ดังนั่น ไม่แปลกที่จะตั้ง Verbs เพื่อบอกว่า API เส้นนี้ทำ Action อะไร

For example

/translate?q=โสด&source=th&target=en
/convert?from=THB&to=BTC&amount=10000000

กรณีนี้ เราจะใช้ Verbs เพราะการทำงานของ API เส้นนี้มีการทำบางอย่างกับ Resource และค่าที่ Response ที่ได้รับ ไม่ใช่ Resource จากระบบโดยตรง

Conclusion

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