แนวทางการพัฒนา API

ออกแบบให้เข้าใจง่าย

API บน ThailandAPI จะใช้งานได้ดีเมื่อผู้ใช้สามารถเข้าใจโครงสร้างได้เร็วและเชื่อถือเอกสารประกอบได้

ออกแบบ endpoint ให้อ่านง่าย

• ใช้ชื่อ resource ที่ชัดเจนและใช้ HTTP method อย่างสม่ำเสมอ
• ตั้งชื่อให้สอดคล้องกันระหว่าง list, detail, create, update และ delete
• ทำ versioning ให้ชัดเจนใน base URL หรือโครงสร้าง route

ใส่เอกสารให้ครบทุก endpoint

• ใส่ summary ที่อธิบาย business action ไม่ใช่แค่คำกริยา
• กรอก query params, headers, request body และ response examples ให้ครบ
• จัดกลุ่ม endpoint ที่เกี่ยวข้องกันเพื่อให้ค้นหาได้ง่ายขึ้น

ใช้ตัวอย่างที่ใกล้เคียงการใช้งานจริง

• ใช้ sample value ที่สื่อความเข้าใจได้ดี โดยเฉพาะกรณีข้อมูลที่เกี่ยวข้องกับประเทศไทย
• แสดง success response ก่อน แล้วค่อยตามด้วย error case ที่พบบ่อย
• หลีกเลี่ยง placeholder ที่ทำให้มองไม่เห็น field สำคัญ

เตรียมความพร้อมด้านปฏิบัติการ

• ตั้ง credit cost และ quota ให้สะท้อนต้นทุนจริงของ endpoint
• ติดตาม log, latency และ support case หลังเปิดใช้งาน
• ถ้าจะ deprecate ควรสื่อสารล่วงหน้าและระวัง breaking change

เช็กลิสต์ก่อนเผยแพร่

• base URL ถูกต้องและเรียกใช้งานได้
• summary ของ endpoint ครบถ้วน
• มี request และ response examples
• pricing และ quota อ่านแล้วเข้าใจได้
• ผู้สมัครใช้งานรู้ว่าจะเปิด support case ได้จากตรงไหน