จากการสอนและแนะนำเรื่องการออกแบบ 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
ที่เข้าใจง่ายสามารถทำตามได้เลย
รวมทั้งอธิบายการแก้ไขปัญหาต่าง ๆ ได้ด้วย
รวมทั้งยังลดความผิดพลาดของการใช้งานลงไปอีกด้วย

Tags:,