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

Posted on:July 1, 2022

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

giphy

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 เราสามารถเลือกใช้ เอกพจน์ หรือ พหูพจน์ ก็ได้ แต่สิ่งที่สำคัญคือ

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

My reasoned

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

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