REST API Naming Conventions
REST API Naming Conventions เป็นการทำตาม guidelines และ best practices สำหรับการตั้งชื่อของ resource URI, HTTP methods และองค์ประกอบอื่น ๆ ของ RESTful API เป็นสิ่งสำคัญสำหรับการสร้าง API ที่มีความสอดคล้องและเข้าใจง่าย ต่อการ maintain API ในอนาคต
การทำตาม REST API naming conventions จะช่วยให้ developers สามารถสร้าง API ที่ใช้งานได้ง่าย ทำงานได้ง่ายและช่วยให้ง่ายต่อการ maintain ถึงแม้ไม่เคยเจอ API นั้นมาก่อนก็จะสามารถเข้าใจได้
- ใช้ Nouns เพื่อบ่งบอกถึง resources นั้น
RESTful URI ควรอ้างอิงถึง resource เป็น noun ซึ่งเป็น best practice ที่ช่วยให้สร้าง API ที่มีโครงสร้างที่ดีและใช้งานง่าย ซึ่งจะสอดคล้องกับ core principle ของ RESTful architecture และในการตั้งชื่อ URIs ไม่ควรระบุ CRUD ใน URIs และหลีกเลี่ยงการผสมคำ verb และ noun
Bad examples:
/v1/store/CreateOrders ❌
/v1/store/getOrders/{order-id} ❌
/v1/store/updateOrders/{order-id} ❌
/v1/store/deleteOrders/{order-id} ❌Good examples:
Method: POST, URI: /v1/store/order (ใช้ singular noun สำหรับอ้างอิง resource) ✅
Method: DELETE, URI: /v1/store/orders/{order-id} (ใช้ HTTP verbs สำหรับอ้างอิง deleting ของ resources) ✅
Method: GET, URI: /v1/store/items (ใช้ plural nouns สำหรับ collections) ✅
Method: GET, URI: /v1/store/items/{order-id} (ใช้ singular nouns สำหรับ individual resources) ✅
Method: PUT or PATCH, URI: /v1/store/orders/{order-id} (ใช้ HTTP verbs สำหรับอ้างอิงการ updating ของ resources) ✅- ใช้ Pluralized Nouns เพื่อบ่งบอกถึง resources นั้น
การใช้ pluralized nouns สำหรับ resources ใน RESTFul API นั้นเป็น best practice ที่ช่วยทำให้ developers ใช้ API ได้ง่ายขึ้น ค้นหาข้อมูลง่ายขึ้น และมีประสิทธิภาพมากขึ้น เช่น /ordersเมื่อเราเห็นก็จะรู้เลยว่า resource นี้เป็นข้อมูลทั้งหมดที่ถูก response มาจาก API ไม่ใช่แค่ ข้อมูลเดียว
Bad examples:
/v1/store/item ❌ (ใช้ singular noun สำหรับ collection ของ resources)Good examples:
/v1/store/items ✅ (ใช้ plural noun สำหรับ collection ของ resources)- ใช้ hyphens (-) ในการแยก words ของ resources
จะใช้ Hyphens สำหรับแยก words ใน URI เพื่อให้อ่านง่ายขึ้นและช่วยให้เข้าใจได้รวดเร็วว่า resource นั้นคืออะไร
Bad examples:
/v1/store/order_histories ❌ (ใช้ underscore แทน hyphen สำหรับแยก words)Good examples:
/v1/store/order-histories ✅ (ใช้ hyphen สำหรับแยก words)- ใช้ forward slashes (/)
ใช้ forward slashes (/) สำหรับบอก hierarchy ของ resource ต่างๆ แต่จะต้องระวังไม่ให้ใช้ forward slash ที่ตามท้าย URI
Bad examples:
/v1/store/order-histories/ ❌Good examples:
/v1/store/order-histories ✅ - หลีกเลี่ยงการใช้ File extensions
ใน RESTful API design แนะนำให้หลีกเลี่ยงการใช้ File extensions ใน URI เนื่องจากจะให้ API นั้นไม่ยืดหยุ่น แต่ควรระบุรูปแบบของการ Response ด้วย Accept header ใน request เช่น ถ้า client ต้องการข้อมูลเป็น JSON จะต้องระบุเป็น Accept: application/jsonใน request header
Bad examples:
/v1/store/order-histories.json ❌Good examples:
/v1/store/order-histories ✅- ใช้ Version ใน APIs
เพิ่ม version number ใน URI ของ API ได้ และจะช่วยให้สามารถแก้ไข API ที่ไม่ส่งผลกระทบต่อ application ของคุณ ส่วนใหญ่จะเป็นในฝั่ง mobile ที่จะมีผลกระทบเยอะ เพราะว่าบาง application อาจจะไม่ force ให้ user update application ถ้ามีการแก้ไข API นั้นและไม่มีระบุ version ก็อาจจะส่งผลให้ application นั้นพังได้
Bad examples:
/store/order-histories ❌Good examples:
/v1/store/order-histories ✅- ใช้ query component ในการ filter URI collection
ใน RESTful API design แนะนำให้ใช้ Query component สำหรับ filter URI collections เพื่อช่วยให้ง่ายขึ้นในการค้นหาสำหรับระบุ resource และ implement pagination และมันช่วยให้แยก resource จากการ filter criteria
Query component จะใช้ key-value เพิ่มในสุดท้ายของ URI ที่อนุญาติให้ client ระบุ subset ของ resource นั้นได้
Bad examples:
/v1/store/orders/shipped ❌
/v1/store/products/electronics ❌Good examples:
/v1/store/orders?status=shipped ✅
/v1/store/products?category=electronics ✅หวังว่าจะเป็นประโยชน์ต่อผู้ที่เข้ามาอ่านไม่มากก็น้อย
ขอให้สนุกกับการเขียนโปรแกรม ^-^
เจอกันใหม่บทความถัดไป ^_^
ปล. ถ้าผิดพลาดในส่วนไหนก็ขออภัยมา ณ ที่นี้ด้วย
REF:
