ผมเคยเขียนเส้น API แบบเข้าใจยากจนการใช้งานและกลับมาแก้นั้นปวดหัวมาก ๆ

เวลาพูดถึง API หลายคนอาจจะคิดว่า ก็แค่ endpoint ไว้ยิง request – response กลับมา จบ แต่จริง ๆ แล้ว API มันคือ “ภาษากลาง” ที่เราใช้คุยกับนักพัฒนาคนอื่น ๆ หรือแม้กระทั่งทีมตัวเองในอนาคตเลยนะ

การออกแบบ API ที่ดี ไม่ได้ช่วยแค่ตอนใช้งาน แต่ยังช่วยลดปัญหาในอนาคต เวลา scale ระบบ หรือเวลา dev ใหม่เข้ามาทำงาน

ทำไม API Design ถึงสำคัญ?

dev คนอื่นเข้าใจได้ง่าย โดยไม่ต้องนั่งงง
ถ้าวางรูปแบบให้สม่ำเสมอ จะช่วยลดเวลา debug ได้เยอะ
เวลา API มันใหญ่ขึ้น เราจะไม่เจอปัญหาเปลี่ยน endpoint ที ระบบพังทั้งแอป
ช่วยเรื่อง security ด้วย ป้องกันการเผลอปล่อยข้อมูลหลุด

หลักง่าย ๆ ในการออกแบบ API ✨

1. คิดเป็นทรัพยากร (Resource-Oriented)

เช่น เรามี users, orders, products ก็ทำแบบนี้

GET /users           -> เอาข้อมูล user ทั้งหมด
GET /users/123       -> เอาข้อมูล user คนที่ id=123
POST /users          -> สร้าง user ใหม่
PUT /users/123       -> อัปเดต user ที่มี id=123
DELETE /users/123    -> ลบ user

Status Code

การส่งเสตตัสโค้ดที่ถูกต้องช่วยให้ client รู้ว่า request สำเร็จหรือไม่ และเกิดอะไรขึ้นบ้าง เพื่อที่จะได้จัดการกับ response ได้ถูกต้อง

Status Code	ความหมาย	ใช้เมื่อ
200 OK	สำเร็จ	ใช้กับ `GET`, `PUT`, `PATCH`, `DELETE` ที่ทำงานสำเร็จ
201 Created	สร้าง resource ใหม่สำเร็จ	ใช้กับ `POST` เมื่อมีการสร้างข้อมูลใหม่
202 Accepted	คำสั่งถูกส่งไปแล้ว แต่ยังประมวลผลไม่เสร็จ	ใช้กับงาน async เช่น queue
204 No Content	สำเร็จ แต่ไม่มีข้อมูลส่งกลับ	ใช้กับ `DELETE` หรือ update ที่ไม่ต้องส่ง response
400 Bad Request	Request ไม่ถูกต้อง	ข้อมูลไม่ครบ, type ไม่ถูกต้อง
401 Unauthorized	ไม่ได้ login หรือ token ไม่ถูกต้อง	ต้องมีการยืนยันตัวตนก่อน
403 Forbidden	มี token แล้วแต่ไม่มีสิทธิ์เข้าถึง	เช่น user ธรรมดาไปเรียก API admin
404 Not Found	ไม่เจอ resource	เช่น `GET /users/9999` แล้วไม่มี
405 Method Not Allowed	ใช้ HTTP method ไม่ถูก	เช่น `DELETE /login`
409 Conflict	มีความขัดแย้ง	เช่น สร้าง user ที่ email ซ้ำ
422 Unprocessable Entity	ข้อมูลถูกส่งมาแล้วแต่ validate ไม่ผ่าน	เช่น password สั้นเกินไป
429 Too Many Requests	โดน rate limit	ส่ง request ถี่เกินไป
500 Internal Server Error	ระบบพังในฝั่ง server	bug, crash หรือ error ที่ไม่คาดคิด
502 Bad Gateway	ปัญหาจาก proxy หรือ service ข้างหลัง	เช่น upstream พัง
503 Service Unavailable	เซิร์ฟเวอร์ไม่พร้อมให้บริการ	downtime, maintenance
504 Gateway Timeout	รอ service อื่นนานเกินไป	เช่น timeout ระหว่าง API → DB

ข้อมูลที่ส่งกลับต้องมีโครงสร้างที่ชัดเจน

เช่น ถ้า API เราส่งข้อมูล user กลับมา ควรจะมีโครงสร้างแบบนี้ คือ data กับ meta แยกกันชัดเจน โดยแยก Object ออกมา ตัวอย่างเช่น data = เนื้อหาหลัก meta = ข้อมูลเสริม เช่น request_id, pagination, timestamp

ถ้า API เรามีหลาย resource ที่ส่งกลับมาใน response เดียวกัน ควรจะจัดกลุ่ม resource เหล่านั้นให้อยู่ใน Object ของตัวเองและเหมือนกันทุกเส้น เช่น

{
  "data": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com"
  },
  "meta": {
    "request_id": "abc-123",
    "timestamp": "2025-09-15T12:34:56Z"
  }
}

ข้อความ error ต้องชัดเจนและมีประโยชน์

เวลามี error เกิดขึ้น ควรส่งข้อมูลที่ช่วยให้ client เข้าใจว่าเกิดอะไรขึ้น และจะแก้ไขยังไง พร้อมกับเมื่อโค้ดมีการดักจับ error ควรส่งฟอร์มแบบเดียวกันออกมา เช่น

{
  "error": {
    "code": "OUT_OF_STOCK",
    "message": "Product with ID ..... is out of stock",
    "hint": "ลองเลือกสินค้าอื่น หรือรอสินค้าเข้าใหม่"
  }
}

และทุกอย่างนี้ควรจะมีเอกสาร (Documentation) ที่ชัดเจนและอัปเดตเสมอ

API Design - การออกแบบ API ให้ใช้งานง่ายและปลอดภัย