จากการสอนและแนะนำเรื่องการออกแบบ API (Application Programming Interface) ที่ดี
ไม่ว่าจะเป็น code ไม่ว่าจะเป็น RESTFul API ก็ตาม
API เหล่านั้นควรมีคุณสมบัติต่าง ๆ ดังนี้
- ออกแบบในมุมมองของคนใช้งาน ไม่ใช่มุมมองขอคนสร้าง
- ง่ายต่อการเรียนรู้และใช้งาน โดยเอกสารเป็นสิ่งสุดท้ายที่ควรอ่าน
- ยากต่อการใช้งานผิด
- ง่ายต่อการดูแลรักษาในระดับ code ซึ่งทำให้พัฒนาและต่อยอดได้ง่าย
- ต้องมีความสัมพันธ์กับความต้องการต่าง ๆ
เมื่อลงไปในรายละเอียดของ API ที่ดี
ก็มีเรื่องที่คุยกันพอสมควร
ยกตัวอย่างเช่น
API หนึ่ง ๆ ควรทำงานอย่างเดียวไปเลย (Single Responsibility)
และแน่นอนว่า ต้องทำงานให้ดีไปเลย
ทำให้ขนาดของ API นั้น ๆ เล็กลงไปด้วย
พยายามให้มี parameter น้อย ๆ หรือมีเท่าที่จำเป็นก็พอ
รวมทั้งเรื่องของข้อมูลที่ return กลับมาจาก API
ก็ต้อง return ข้อมูลที่ไม่ส่งผลต่อการทำงาน
ยกตัวอย่างเช่น
ถ้าต้อง return เป็น list กลับมาแล้ว
ในกรณีที่ไม่พอข้อมูล น่าจะส่ง empty list กลับมาดีว่า null มาก ๆ เป็นต้น
ในส่วนของ API ไม่ควรมีเรื่องของ implementation ลงไป
เนื่องจากเราสร้าง interface ขึ้นมาเพื่อให้ทางผู้ใช้งาน
มิใช่บอกว่า เราสร้างด้วยอะไร
แต่มันคือการมีอะไรให้ใช้บ้าง ก็เพียงพอแล้ว
และจะทำให้เราสามารถเปลี่ยน implemnentation ได้ง่ายขึ้น
โดยส่งผลกระทบต่อผู้ใช้งานน้อยที่สุด
การตั้งชื่อก็สำคัญมาก ๆชื่อที่ดี
ย่อมทำให้ผู้ใช้เข้าใจง่าย ไม่สับสน
“เรื่องของความปลอดภัยและความเร็วในการทำงานเป็นเรื่องที่ละเลยไม่ได้เลย“
สิ่งสุดท้ายคือ เรื่องของ API documentation
ที่เข้าใจง่ายสามารถทำตามได้เลย
รวมทั้งอธิบายการแก้ไขปัญหาต่าง ๆ ได้ด้วย
รวมทั้งยังลดความผิดพลาดของการใช้งานลงไปอีกด้วย
