ตั้งชื่อ RESTful API Endpoint แบบไม่ต้องพึ่งหลวงพ่อ (Part I)

เราคงเคยคิด Endpoint แล้วมีคำถามกับตัวเองอยู่บ้างว่าต้องตั้งชื่ออะไรดี แล้วตั้ง Case sensitive ได้ไหม หรือบางครั้งเจอ Endpoint เหมือนมันเข้ารหัสมา ซึ่งใน RESTful API เองก็มีวิธีตั้งชื่อที่เป็นวิธีที่ดีวิธีหนึ่ง โดยผมจะขอยกเนื้อหาจากหนังสือที่ผมชอบเอามาอ้างอิงเวลาต้องคุยกับทีมคือหนังสือ REST API Design Rulebook วันนี้เลยอยากจะขอเอาเนื้อหาบางส่วนมาแบ่งปัน และอาจจะมีความเห็นของผมเข้าไปในบางส่วนด้วย ดังนั้นหากต้องการแม่นยำแนะนำให้อ่านเพิ่มครับ

URI (บางครั้งเรียก Endpoint)ใช้ให้สื่อโดยจะเรียงของในลักษณะที่ใหญ่ไปเล็กเช่น
http://api.example.restapi.org/france/paris/louvre/leonardo-da-vinci/mona-lisa กรณี URI นี้จะเห็นว่ามีการตั้งชื่อไปในลักษณะ france คือประเทศซึ่งเป็นส่วนใหญ่กว่า paris ที่เป็นเมืองและ louvre สถานที่ตั้งเป็นต้น แทนที่จะเป็น http://api.example.restapi.org/68dd0 ซึ่งอ่านแล้วทำความเข้าใจได้ยาก

Rule: ใช้ / (Slash) ก็ต่อเมื่อมีการอ้างถึงของที่อยู่คนละระดับ เช่น http://api.com/countries/thailand/provinces

Rule: ไม่ต้องเอา / ต่อท้าย URI
✅ http://api.com/countries/thailand/provinces
❌ http://api.com/countries/thailand/provinces/

Rule: ใช้ -(hyphen) เพื่อให้อ่านได้ง่ายแต่ไม่ใช้ _ (underscore) เพราะบาง Web browser หรือ Editor ทำลิงค์แบบขีดเส้นใช้ให้เองเช่นใน Medium.com นี้ก็เหมือนกัน
✅ http://api.restapi.org/blogs/mark-masse/entries/this-is-my-first-post
❌ http://api.restapi.org/blogs/mark_masse/entries/this_is_my_first_post

Rule: ถ้าเป็นไปได้ให้ใช้ Lower case ทั้งหมด
✅ http://api.example.restapi.org/my-folder/my-doc
✅ HTTP://API.EXAMPLE.RESTAPI.ORG/my-folder/my-doc (RFC 3986 อนุญาตให้ใช้ Scheme คือตรง HTTP และ Host คือตรง API.EXAMPLE.RESTAPI.ORG เป็นตัวใหญ่ได้)
❌ http://api.example.restapi.org/My-Folder/my-doc (พวก Resource ไม่ให้เป็นตัวใหญ่ เพราะปกติจะ Case sensitive)

Rule: ไม่ต้องใส่ File extension
✅ http://api.com/countries/thailand/provinces/bangkok
❌ http://api.com/countries/thailand/provinces/bangkok.json

คร่าว ๆ ใน Part แรกไว้ประมาณเท่านี้ก่อนครับ ไว้เจอกันใน See you yesterday ครับ