API ที่ดีไม่ใช่แค่ “ทำงานได้” มาดู Checklist ออกแบบ API ให้ทีมโตได้

ทำไม API ที่ “แค่ทำงานได้” ถึงไม่พอ?

สำหรับเพื่อน ๆ ที่เป็น Back-end Developer หรือทำงานเกี่ยวกับ API น่าจะเคยเจอเหตุการณ์แบบนี้กันบ้างนะคร้าบบ ตอนที่เราเขียน API ขึ้นมาตัวนึง มันก็ทำงานได้ปกติดี ส่ง request ไป ได้ response กลับมา ดูเหมือนจะจบแล้ว แต่พอทีม Front-end เอาไปใช้จริง ก็เริ่มมีคำถามเข้ามาว่า “endpoint นี้ส่ง field อะไรกลับมาบ้าง?” “error code 400 หมายความว่าอะไร?” “ถ้าข้อมูลเยอะ มี pagination ไหม?” คำถามเหล่านี้แหละครับที่เป็นสัญญาณว่า API ของเรายัง “ออกแบบ” ไม่ดีพอ

จากรายงาน Postman State of the API 2025 ที่สำรวจ Developer กว่า 5,700 คน พบว่า 93% ของทีม API ยังเจอปัญหาเรื่อง collaboration blockers โดย 55% มีปัญหาเรื่อง inconsistent documentation ซึ่งทั้งหมดนี้เริ่มต้นจาก API Design ที่ไม่ดีตั้งแต่แรก

บทความนี้แอดจะพามาดู Checklist สำหรับออกแบบ API ที่ดี ที่ไม่ใช่แค่ “ทำงานได้” แต่ทำให้ทีมโตตาม API ไปด้วยได้ พร้อมตัวอย่าง Good vs Bad ทุกหัวข้อ เอาไปใช้ได้ทันทีเลยนะคร้าบบ

Checklist ข้อ 1: ตั้งชื่อ Endpoint ให้อ่านรู้เรื่อง (API Naming Convention)

เรื่องแรกที่ต้องเช็คเลยก็คือ “ชื่อ” ของ API endpoint เพราะ Naming Convention คือสิ่งแรกที่ Developer คนอื่นจะเห็นเวลามาใช้ API ของเรา ถ้าตั้งชื่อดี คนเห็นปุ๊บเข้าใจปั๊บว่า endpoint นี้ทำอะไร แต่ถ้าตั้งชื่อไม่ดีก็จะต้องไปเปิด docs ทุกครั้ง ซึ่งเสียเวลามากเลยย

หลักการสำคัญมีดังนี้

หลักการแรก ให้ใช้ Nouns (คำนาม) ไม่ใช่ Verbs (คำกริยา) เพราะ HTTP Method อย่าง GET, POST, PUT, DELETE บอก action อยู่แล้ว ไม่ต้องซ้ำอีกใน URL หลักการที่สอง ให้ใช้พหูพจน์ (Plural) สำหรับ collection เสมอ เช่น /users ไม่ใช่ /user และหลักการที่สาม ใช้ kebab-case (ตัวพิมพ์เล็กคั่นด้วย -) ไม่ใช่ camelCase หรือ snake_case

มาดูตัวอย่าง Good vs Bad กัน:

สังเกตไหมคร้าบบ ฝั่ง Good แค่ดู URL ก็รู้แล้วว่า endpoint ทำอะไร โดยไม่ต้องเปิด docs เลย นี่แหละคือ API ที่ออกแบบมาดี

Checklist ข้อ 2: ออกแบบ Error Response ที่ช่วย Debug ได้จริง

เรื่อง Error Handling เป็นอีกจุดที่หลายคนมักมองข้าม จากข้อมูลของ Zuplo ที่วิเคราะห์ REST API Design Mistakes พบว่า Poor Error Handling เป็น 1 ใน 5 ปัญหาที่พบบ่อยที่สุด เพราะ Developer มักปล่อยให้ error response เป็นแค่ status code กับ message สั้น ๆ ที่ไม่ช่วยอะไรเลย

มาดูตัวอย่าง Error Response ที่ “ไม่ช่วย” กับที่ “ช่วยได้จริง” กัน:

Bad: Error Response ที่ไม่ช่วยอะไร

// Response: 400 Bad Request
{
  "error": "Invalid request"
}
// Developer เห็นแล้วก็งง... อะไร Invalid? field ไหน?

// Response: 400 Bad Request
{
  "error": "Invalid request"
}
// Developer เห็นแล้วก็งง... อะไร Invalid? field ไหน?

Good: Error Response ที่ช่วย Debug ได้

// Response: 422 Unprocessable Entity
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "ข้อมูลที่ส่งมาไม่ผ่าน validation",
    "details": [
      {
        "field": "email",
        "issue": "รูปแบบ email ไม่ถูกต้อง",
        "received": "john@"
      },
      {
        "field": "age",
        "issue": "ต้องเป็นตัวเลขที่มากกว่า 0",
        "received": -5
      }
    ],
    "request_id": "req_abc123",
    "docs": "https://api.example.com/docs/errors#validation"
  }
}

// Response: 422 Unprocessable Entity
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "ข้อมูลที่ส่งมาไม่ผ่าน validation",
    "details": [
      {
        "field": "email",
        "issue": "รูปแบบ email ไม่ถูกต้อง",
        "received": "john@"
      },
      {
        "field": "age",
        "issue": "ต้องเป็นตัวเลขที่มากกว่า 0",
        "received": -5
      }
    ],
    "request_id": "req_abc123",
    "docs": "https://api.example.com/docs/errors#validation"
  }
}

เห็นความแตกต่างไหมคร้าบบ แบบ Good บอกทุกอย่างเลย field ไหนผิด ผิดยังไง ค่าที่ส่งมาคืออะไร มี request_id สำหรับ trace และมี link ไปดู docs เพิ่มเติม Developer เห็นแล้วแก้ได้ทันทีเลย ไม่ต้องมานั่งเดา

แอดแนะนำให้กำหนด Error Response format เป็น standard เดียวกันทั้ง API เลย ไม่ว่าจะ error อะไรก็ใช้โครงสร้างเดียวกัน จะได้ไม่ต้องเดาว่า endpoint นี้ error มาหน้าตาแบบไหน

Checklist ข้อ 3: ทำ Pagination ให้ถูกวิธี (Offset vs Cursor)

ถ้า API ของเราส่งข้อมูลเป็น list กลับมา ไม่ว่าจะเป็น list users, list orders หรือ list อะไรก็ตาม สิ่งที่ต้องมีคือ Pagination เพราะถ้าไม่มี pagination แล้ว database มีข้อมูล 100,000 records มันก็จะ query แล้วส่งกลับมาทั้งหมด ซึ่งทั้งช้าและกิน bandwidth มากเลยย

คำถามถัดมาคือ ใช้ Pagination แบบไหนดี? ปัจจุบันมี 2 แบบหลัก ๆ ที่นิยมกัน ได้แก่ Offset-based กับ Cursor-based จาก benchmark ของ AppSignal พบว่า Offset-based pagination ช้ากว่า Cursor-based ถึง 9 เท่า เมื่อข้อมูลมีขนาดใหญ่ขึ้น และ Cursor-based สามารถลด query time ได้ถึง 40% สำหรับ dataset ที่มีมากกว่า 1 ล้าน rows

Offset-based Pagination

// Request
GET /v1/users?offset=40&limit=20

// Response
{
  "data": [...],
  "pagination": {
    "total": 1250,
    "offset": 40,
    "limit": 20,
    "has_more": true
  }
}
// ข้อดี: ง่าย, กระโดดไปหน้าไหนก็ได้
// ข้อเสีย: ช้าเมื่อ offset สูง, ข้อมูลอาจซ้ำ/หายถ้ามี insert/delete ระหว่าง request

// Request
GET /v1/users?offset=40&limit=20

// Response
{
  "data": [...],
  "pagination": {
    "total": 1250,
    "offset": 40,
    "limit": 20,
    "has_more": true
  }
}
// ข้อดี: ง่าย, กระโดดไปหน้าไหนก็ได้
// ข้อเสีย: ช้าเมื่อ offset สูง, ข้อมูลอาจซ้ำ/หายถ้ามี insert/delete ระหว่าง request

Cursor-based Pagination

// Request
GET /v1/users?cursor=eyJpZCI6NDB9&limit=20


// Response
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6NjB9",
    "has_more": true
  }
}
// ข้อดี: เร็วสม่ำเสมอไม่ว่า dataset จะใหญ่แค่ไหน, ไม่มีข้อมูลซ้ำ/หาย
// ข้อเสีย: กระโดดข้ามหน้าไม่ได้, ต้อง implement ซับซ้อนกว่า

// Request
GET /v1/users?cursor=eyJpZCI6NDB9&limit=20


// Response
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6NjB9",
    "has_more": true
  }
}
// ข้อดี: เร็วสม่ำเสมอไม่ว่า dataset จะใหญ่แค่ไหน, ไม่มีข้อมูลซ้ำ/หาย
// ข้อเสีย: กระโดดข้ามหน้าไม่ได้, ต้อง implement ซับซ้อนกว่า

‎

แอดแนะนำว่าถ้า API ใช้กับ mobile app หรือ feed แบบ infinite scroll ให้ใช้ Cursor-based เลย แต่ถ้าเป็น admin dashboard ที่ต้องกระโดดไปหน้า 50 ได้ ก็ใช้ Offset-based ก็ได้ เลือกให้เหมาะกับ use case

Checklist ข้อ 4: วาง API Versioning Strategy ตั้งแต่วันแรก

เรื่อง Versioning เป็นสิ่งที่หลาย Developer มักลืมตอนเริ่มสร้าง API คิดว่า “เดี๋ยวค่อยทำทีหลังก็ได้” แต่พอ API ไป production แล้ว มี client ใช้อยู่ จะมาเพิ่ม versioning ทีหลังมันยากมากเลยย เพราะต้อง migrate client ทุกตัว

วิธี versioning ที่นิยมมี 3 แบบ:

แอดแนะนำ URI Path versioning เลยนะคร้าบบ เพราะมันชัดเจนที่สุด Developer เห็นปุ๊บรู้ทันทีว่าใช้ version ไหน แม้แต่ Microsoft Azure API Guidelines ก็แนะนำวิธีนี้เช่นกัน

// ตัวอย่าง Versioning Strategy


// v1 - version แรก
GET /v1/users/1
// Response: { "name": "สมชาย", "email": "somchai@email.com" }


// v2 - เพิ่ม field ใหม่ เปลี่ยนโครงสร้าง
GET /v2/users/1
// Response: {
//   "first_name": "สมชาย",
//   "last_name": "ใจดี",
//   "email": "somchai@email.com",
//   "profile": { "avatar_url": "..." }
// }


// สำคัญ: v1 ยังต้องทำงานได้ปกติ!
// กำหนด deprecation timeline ชัดเจน เช่น
// "v1 จะ sunset วันที่ 1 ม.ค. 2027"

// ตัวอย่าง Versioning Strategy


// v1 - version แรก
GET /v1/users/1
// Response: { "name": "สมชาย", "email": "somchai@email.com" }


// v2 - เพิ่ม field ใหม่ เปลี่ยนโครงสร้าง
GET /v2/users/1
// Response: {
//   "first_name": "สมชาย",
//   "last_name": "ใจดี",
//   "email": "somchai@email.com",
//   "profile": { "avatar_url": "..." }
// }


// สำคัญ: v1 ยังต้องทำงานได้ปกติ!
// กำหนด deprecation timeline ชัดเจน เช่น
// "v1 จะ sunset วันที่ 1 ม.ค. 2027"

‎

Checklist ข้อ 5: ออกแบบ Security และ Rate Limiting ที่เหมาะสม

จาก Postman Report เดียวกัน พบว่า 50.8% ของ Developer กังวลเรื่อง unauthorized API calls มากที่สุด โดยเฉพาะในยุคที่ AI Agent เริ่มเรียกใช้ API มากขึ้น การออกแบบ API Security ที่ดีจึงสำคัญมาก

Authentication: ใช้ Standard ที่เป็นที่ยอมรับ

สำหรับ Authentication แอดแนะนำให้ใช้ OAuth 2.0 หรือ JWT (JSON Web Token) เป็น standard ไม่ต้องคิดเอง ไม่ต้องประดิษฐ์ auth scheme ใหม่ เพราะทำยังไงก็ไม่ปลอดภัยเท่า standard ที่ผ่านการทดสอบมาแล้ว

// Good: ใช้ Bearer Token (JWT)
// Request Header
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...


// Bad: ส่ง credentials ใน query string
GET /v1/users?api_key=sk_live_abc123  // อย่าทำ! api_key จะโผล่ใน server log

// Good: ใช้ Bearer Token (JWT)
// Request Header
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...


// Bad: ส่ง credentials ใน query string
GET /v1/users?api_key=sk_live_abc123  // อย่าทำ! api_key จะโผล่ใน server log

Rate Limiting: ปกป้อง API ไม่ให้โดนถล่ม

Rate Limiting ไม่ใช่แค่ป้องกัน abuse แต่ยังช่วยให้ API ทำงานได้เสถียรสำหรับทุกคน วิธีที่ดีคือส่ง rate limit info กลับไปใน response header ให้ client รู้ว่าเหลือ quota เท่าไหร่

// Response Headers สำหรับ Rate Limiting
X-RateLimit-Limit: 100          // จำนวน request สูงสุดต่อ window
X-RateLimit-Remaining: 73       // จำนวนที่เหลือ
X-RateLimit-Reset: 1711324800   // เวลาที่ reset (Unix timestamp)


// เมื่อเกิน rate limit
// Response: 429 Too Many Requests
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "คุณส่ง request เกินกำหนด กรุณารอ 45 วินาที",
    "retry_after": 45
  }
}

// Response Headers สำหรับ Rate Limiting
X-RateLimit-Limit: 100          // จำนวน request สูงสุดต่อ window
X-RateLimit-Remaining: 73       // จำนวนที่เหลือ
X-RateLimit-Reset: 1711324800   // เวลาที่ reset (Unix timestamp)


// เมื่อเกิน rate limit
// Response: 429 Too Many Requests
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "คุณส่ง request เกินกำหนด กรุณารอ 45 วินาที",
    "retry_after": 45
  }
}

‎

รวม Checklist ทั้งหมด: ออกแบบ API สำหรับระบบ E-Commerce

มาลองดูตัวอย่างจริงกัน สมมติว่าเราต้องออกแบบ API สำหรับระบบ E-Commerce ง่าย ๆ ที่มี users, products, orders มาดูว่าถ้าเอา checklist ทั้ง 5 ข้อมาใช้ API จะหน้าตาเป็นยังไง

Endpoint Design (ตาม Checklist ข้อ 1)

// Users
GET    /v1/users              // ดึง list users
POST   /v1/users              // สร้าง user ใหม่
GET    /v1/users/:id          // ดึง user คนเดียว
PUT    /v1/users/:id          // อัปเดต user
DELETE /v1/users/:id          // ลบ user


// Products
GET    /v1/products           // ดึง list products
GET    /v1/products/:id       // ดึง product ตัวเดียว
POST   /v1/products           // สร้าง product (admin only)


// Orders - nested resource
GET    /v1/users/:id/orders   // ดึง orders ของ user
POST   /v1/orders             // สร้าง order ใหม่
GET    /v1/orders/:id         // ดึง order ตัวเดียว

// Users
GET    /v1/users              // ดึง list users
POST   /v1/users              // สร้าง user ใหม่
GET    /v1/users/:id          // ดึง user คนเดียว
PUT    /v1/users/:id          // อัปเดต user
DELETE /v1/users/:id          // ลบ user


// Products
GET    /v1/products           // ดึง list products
GET    /v1/products/:id       // ดึง product ตัวเดียว
POST   /v1/products           // สร้าง product (admin only)


// Orders - nested resource
GET    /v1/users/:id/orders   // ดึง orders ของ user
POST   /v1/orders             // สร้าง order ใหม่
GET    /v1/orders/:id         // ดึง order ตัวเดียว

Response Format มาตรฐาน

// Success Response
{
  "data": {
    "id": 1,
    "name": "iPhone 16 Pro",
    "price": 48900,
    "currency": "THB",
    "created_at": "2026-03-24T10:30:00Z"
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}


// List Response (with Cursor Pagination)
{
  "data": [
    { "id": 1, "name": "iPhone 16 Pro", ... },
    { "id": 2, "name": "MacBook Air M4", ... }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MjB9",
    "has_more": true
  },
  "meta": {
    "request_id": "req_abc456",
    "total_count": 1250
  }
}

// Success Response
{
  "data": {
    "id": 1,
    "name": "iPhone 16 Pro",
    "price": 48900,
    "currency": "THB",
    "created_at": "2026-03-24T10:30:00Z"
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}


// List Response (with Cursor Pagination)
{
  "data": [
    { "id": 1, "name": "iPhone 16 Pro", ... },
    { "id": 2, "name": "MacBook Air M4", ... }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MjB9",
    "has_more": true
  },
  "meta": {
    "request_id": "req_abc456",
    "total_count": 1250
  }
}

สังเกตว่าทุก response มีโครงสร้างเดียวกัน data wrapper สำหรับข้อมูลหลัก pagination สำหรับ list และ meta สำหรับข้อมูลเสริม Developer เห็นครั้งเดียวก็ใช้ได้ทุก endpoint เลย

สรุป: API Design Checklist ฉบับเต็ม

สรุปท้ายจากแอด

จะเห็นว่าการออกแบบ API ที่ดีไม่ได้ยากเลยนะคร้าบบ แค่มี checklist ไว้เช็คก่อน implement ทุกครั้ง ก็ช่วยให้ API ของเราดีขึ้นมากแล้ว สิ่งที่แอดอยากให้เพื่อน ๆ จำไว้คือ API ไม่ได้ออกแบบเพื่อแค่ “ให้มันทำงานได้” แต่ออกแบบเพื่อให้คนอื่นใช้แล้ว “มีความสุข” ด้วย

ถ้าทีม Front-end ใช้ API ของเราแล้วไม่ต้องถามคำถามเลย นั่นแหละคือ API ที่ออกแบบมาดี ถ้าเอา API ไป integrate กับระบบอื่นได้ง่าย ๆ โดยไม่ต้องอ่าน docs 100 หน้า นั่นแหละคือ API ที่ทีมโตตามได้

สำหรับเพื่อน ๆ ที่อยากเรียนรู้เรื่อง API Design แบบเจาะลึก พร้อมทำ project จริง สามารถลองดู Road to Back-End Developer Bootcamp 2026 ของ borntoDev ได้เลยนะคร้าบบ ครอบคลุมตั้งแต่ Node.js, Express, Database ไปจนถึง API Design และ Deployment เรียนจบมาสร้าง API ที่ทีมรักได้แน่นอนเลยย

References

– Postman State of the API Report 2025

– Microsoft Azure – Web API Design Best Practices

– Swagger – Best Practices in API Design

– Zuplo – Common Pitfalls in RESTful API Design (2025)

– REST API URI Naming Conventions and Best Practices

Related Articles จาก borntoDev:

– Docker + CI/CD แบบง่าย: ทำให้ Deploy ไม่พังทุกครั้งที่แก้โค้ด

– Roadmap Full Stack 2026: จาก HTML สู่ Deploy ขึ้นจริง ใน 7 เดือน– Front-end vs Back-end: สายไหนเหมาะกับเรา?