Programming

REST API Design Best Practices

📅 2026-02-10 | โดย อ.บอม กิตติทัศน์ เจริญพนาสิทธิ์ — SiamCafe.net Since 1997

REST API Design Best Practices: สร้าง API ที่ดี ชีวิตแฮปปี้

REST API Design เนี่ย สำคัญกว่าที่คิดนะน้อง สมัยผมทำร้านเน็ตนี่ เว็บไซต์ยังไม่ซับซ้อนเท่าสมัยนี้ แต่พอเริ่มมี API ให้เว็บอื่นมาดึงข้อมูลไปใช้ได้ ชีวิตก็ง่ายขึ้นเยอะ แต่ถ้าออกแบบไม่ดีนี่…ปวดหัวกว่าเดิมอีก

API ที่ดีคือ API ที่เข้าใจง่าย ใช้งานง่าย และเปลี่ยนแปลงได้ง่ายในอนาคต ลองนึกภาพว่าถ้า API มันเหมือนเมนูอาหาร ถ้าเมนูมันเขียนงงๆ สั่งอะไรก็ไม่รู้เรื่อง ลูกค้า (หรือ developer ที่มาใช้ API เรา) ก็หนีหมด

ทำไมต้อง Best Practices? เพราะมันช่วยให้เราสร้าง API ที่:

• สอดคล้อง: ทุก endpoint ทำงานเหมือนกัน ไม่ใช่ endpoint นึง GET อีก endpoint นึง POST มั่วไปหมด
• คาดเดาได้: เห็น URL ก็พอเดาได้ว่ามันทำอะไร ไม่ต้องเปิด documentation อ่านทุกครั้ง
• บำรุงรักษาง่าย: แก้ไขโค้ดง่าย เพิ่ม feature ใหม่ๆ ได้โดยไม่กระทบของเก่า

อะไรคือ REST?

REST หรือ Representational State Transfer มันเป็นแค่แนวคิด (architectural style) ไม่ใช่ standard ตายตัว แต่มี principles ที่เราควรยึดไว้:

• Client-Server: Client กับ Server ทำงานแยกกัน ไม่พึ่งพากัน
• Stateless: Server ไม่เก็บ state ของ client แต่ละคน แต่ละ request คือ unique
• Cacheable: Responses ควร cache ได้ เพื่อลด load บน server
• Layered System: Client ไม่จำเป็นต้องรู้ว่า server ทำงานเบื้องหลังยังไง (เช่น มี load balancer หรือเปล่า)
• Uniform Interface: อันนี้สำคัญสุด เดี๋ยวจะอธิบายละเอียดด้านล่าง

Uniform Interface: หัวใจของ REST

Uniform Interface คือกฎที่บอกว่า API เราต้อง consistent และ predictable มี 4 ข้อหลักๆ:

• Resource Identification: ใช้ URI (Uniform Resource Identifier) เพื่อระบุ resource แต่ละตัว เช่น /users/123 คือ user ที่มี ID เป็น 123
• Manipulation of Resources Through Representations: Client แก้ไข resource ผ่าน representation (เช่น JSON) ไม่ใช่ผ่าน function call
• Self-Descriptive Messages: Message (request/response) ต้องมีข้อมูลเพียงพอให้ client/server เข้าใจได้ เช่น Content-Type header บอกว่าเป็น JSON
• Hypermedia as the Engine of Application State (HATEOAS): Response ควรมี links ไปยัง resource อื่นๆ ที่เกี่ยวข้อง เพื่อให้ client "discover" API ได้ (อันนี้ advance หน่อย ไม่ค่อยมีคนทำ)

HTTP Methods: GET, POST, PUT, DELETE... ใช้ให้ถูก

HTTP methods ไม่ได้มีไว้ให้เลือกใช้ตามใจชอบนะน้อง แต่ละ method มีความหมายของมันอยู่ ต้องใช้ให้ถูกตามหลักการ:

HTTP Method	ความหมาย	Idempotent?	ตัวอย่าง
GET	ดึงข้อมูล	Yes	GET /users/123
POST	สร้าง resource ใหม่	No	POST /users (พร้อม body ที่มีข้อมูล user)
PUT	แก้ไข resource ทั้งหมด (replace)	Yes	PUT /users/123 (พร้อม body ที่มีข้อมูล user ทั้งหมด)
PATCH	แก้ไข resource บางส่วน (update)	No	PATCH /users/123 (พร้อม body ที่มีข้อมูล user เฉพาะส่วนที่ต้องการแก้)
DELETE	ลบ resource	Yes	DELETE /users/123

Idempotent หมายถึง ถ้าเรียก method นั้นซ้ำๆ ผลลัพธ์สุดท้ายจะต้องเหมือนเดิม เช่น DELETE /users/123 จะลบ user ID 123 ถ้าเรียกซ้ำ user ก็ยังคงถูกลบไปแล้ว

Naming Conventions: ตั้งชื่อให้ดี มีชัยไปกว่าครึ่ง

การตั้งชื่อ endpoint ก็สำคัญนะน้อง ตั้งให้คนอื่นอ่านแล้วเข้าใจได้ง่าย:

• ใช้คำนาม: Endpoint ควรเป็น noun ไม่ใช่ verb เช่น /users ไม่ใช่ /getUsers
• ใช้ plural: Endpoint ควรเป็น plural เสมอ แม้ว่าจะดึงข้อมูลแค่ item เดียว เช่น /users ไม่ใช่ /user
• ใช้ lowercase: Endpoint ควรเป็น lowercase เพื่อความ consistent เช่น /users ไม่ใช่ /Users
• ใช้ hyphens (-): ใช้ hyphens เพื่อคั่นคำใน endpoint เช่น /user-profiles
• หลีกเลี่ยง underscores (_): ไม่ควรใช้ underscores เพราะอาจจะทำให้เกิดปัญหาในบางภาษา
• ใช้ versioning: ถ้า API มีการเปลี่ยนแปลงครั้งใหญ่ ควรใช้ versioning เพื่อให้ client เก่าใช้งานได้ต่อไป เช่น /v1/users หรือ /api/v1/users

ตัวอย่าง:

• ถูก: /users
• ผิด: /getUser
• ถูก: /users/123
• ผิด: /user/123
• ถูก: /user-profiles
• ผิด: /user_profiles

HTTP Status Codes: บอกสถานะให้ชัดเจน

HTTP status codes มีไว้บอกว่า request สำเร็จหรือไม่ และถ้าไม่สำเร็จเพราะอะไร ใช้ให้ถูกก็จะช่วยให้ client เข้าใจปัญหาได้ง่าย:

• 200 OK: Request สำเร็จ
• 201 Created: Resource ถูกสร้างสำเร็จ (มักใช้กับ POST)
• 204 No Content: Request สำเร็จ แต่ไม่มี content ให้ return (มักใช้กับ DELETE)
• 400 Bad Request: Request ไม่ถูกต้อง (เช่น ข้อมูลไม่ครบ)
• 401 Unauthorized: Client ไม่ได้ authenticated
• 403 Forbidden: Client ไม่มีสิทธิ์เข้าถึง resource
• 404 Not Found: Resource ไม่พบ
• 500 Internal Server Error: Server error

อย่า return 200 OK ทุกกรณีนะน้อง! ต้องบอกสถานะให้ชัดเจน จะได้ debug ง่ายๆ

Data Formats: JSON is King

สมัยผมทำร้านเน็ต XML ยังฮิตอยู่เลย แต่สมัยนี้ JSON คือพระราชาของการแลกเปลี่ยนข้อมูล เพราะมันอ่านง่าย เขียนง่าย และ parse ง่าย

ตัวอย่าง JSON response:

{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com"
}

นอกจาก JSON แล้ว ก็ยังมี data format อื่นๆ ที่ใช้ได้ เช่น XML, CSV, YAML แต่ JSON คือตัวเลือกที่ดีที่สุดในเกือบทุกกรณี

Pagination: จัดการข้อมูลเยอะๆ ให้เป็นระเบียบ

ถ้า endpoint คืนข้อมูลเยอะมากๆ (เช่น รายชื่อ user ทั้งหมด) ควรใช้ pagination เพื่อแบ่งข้อมูลออกเป็นหน้าๆ จะได้ไม่โหลดนานเกินไป

วิธีทำ pagination:

1. เพิ่ม query parameters: เช่น /users?page=2&per_page=20
2. Return metadata: Return ข้อมูลเกี่ยวกับ pagination ใน response เช่น จำนวนหน้าทั้งหมด, หน้าปัจจุบัน
3. Use links: Return links ไปยังหน้าก่อนหน้าและหน้าถัดไป

ตัวอย่าง JSON response with pagination:

{
  "data": [
    {
      "id": 1,
      "name": "User 1"
    },
    {
      "id": 2,
      "name": "User 2"
    }
  ],
  "meta": {
    "total": 100,
    "per_page": 2,
    "current_page": 1,
    "last_page": 50
  },
  "links": {
    "next": "/users?page=2&per_page=2",
    "last": "/users?page=50&per_page=2"
  }
}

เห็นมั้ยว่า pagination ช่วยให้จัดการข้อมูลเยอะๆ ได้ง่ายขึ้นเยอะเลย

🎬 วิดีโอแนะนำ

ดูวิดีโอเพิ่มเติมเกี่ยวกับREST API Design Best Practices:

Security: สำคัญที่สุด อย่ามองข้าม

API security สำคัญมากนะน้อง ไม่งั้นข้อมูลรั่วไหลหมด:

• Authentication: ยืนยันตัวตน client ก่อนอนุญาตให้เข้าถึง API
• Authorization: กำหนดสิทธิ์การเข้าถึง resource ของ client แต่ละคน
• HTTPS: ใช้ HTTPS เสมอ เพื่อเข้ารหัสข้อมูลระหว่าง client กับ server
• Input Validation: ตรวจสอบข้อมูลที่ client ส่งมาเสมอ เพื่อป้องกัน injection attacks
• Rate Limiting: จำกัดจำนวน request ที่ client แต่ละคนส่งได้ เพื่อป้องกัน DDoS attacks

Authentication และ Authorization เป็นเรื่องใหญ่ ต้องศึกษาให้ดีๆ เดี๋ยวนี้มี standard frameworks ให้ใช้เยอะแยะ ไม่ต้องเขียนเองทั้งหมด

อ่านเพิ่มเติมเกี่ยวกับเรื่อง security ได้ที่ SiamCafe Blog

FAQ: คำถามที่พบบ่อย

1. REST API กับ GraphQL ต่างกันยังไง?

REST API คือ architectural style ที่เน้น resource-based endpoints ส่วน GraphQL คือ query language ที่ให้ client เลือกข้อมูลที่ต้องการได้เอง REST เหมาะกับ API ที่ simple ส่วน GraphQL เหมาะกับ API ที่ซับซ้อนและต้องการ flexibility สูง

2. Swagger/OpenAPI คืออะไร?

Swagger/OpenAPI คือ standard สำหรับการ describe REST API ช่วยให้เราสร้าง documentation แบบอัตโนมัติ และ generate client code ได้

3. API Gateway คืออะไร?

API Gateway คือ server ที่อยู่หน้า API ของเรา ทำหน้าที่เป็น single entry point และจัดการเรื่องต่างๆ เช่น authentication, authorization, rate limiting, logging

หวังว่าบทความนี้จะเป็นประโยชน์นะน้อง อย่าลืมว่า REST API Design เป็นเรื่องที่ต้องเรียนรู้และปรับปรุงอยู่เสมอ อ่านเยอะๆ ลองทำเยอะๆ แล้วจะเก่งเอง

ติดตามบทความดีๆ เกี่ยวกับ IT ได้ที่ SiamCafe Blog นะครับ

Best Practices เพิ่มเติม

ใช้ HATEOAS (Hypermedia as the Engine of Application State)

อันนี้อาจจะดูยากหน่อย แต่จริงๆ แล้วคือการใส่ลิงก์ไปยัง resource อื่นๆ ที่เกี่ยวข้องใน response ของ API เรา สมัยผมทำร้านเน็ต เคยเจอเคสที่ลูกค้าต้องคลิกหลายที กว่าจะเจอสิ่งที่ต้องการ HATEOAS ช่วยแก้ปัญหานี้ได้เยอะเลย

{
  "orderId": 123,
  "total": 100,
  "_links": {
    "self": { "href": "/orders/123" },
    "customer": { "href": "/customers/456" },
    "update": { "href": "/orders/123", "method": "PUT" },
    "cancel": { "href": "/orders/123/cancel", "method": "POST" }
  }
}

ลองดูตัวอย่าง JSON ข้างบนสิ นอกจากข้อมูล order แล้ว ยังมีลิงก์ให้ไปดู customer, update order หรือ cancel order ได้ด้วย สะดวกกว่าเยอะ!

Versioning API

API มันต้อง evolve เรื่อยๆ แหละครับ ไม่มีทางที่จะ perfect ตั้งแต่แรก ดังนั้น การทำ versioning สำคัญมาก ไม่งั้น application เก่าๆ จะพังหมด เวลาเราเปลี่ยน API ใหม่

มีหลายวิธีในการทำ versioning เช่น ใส่ version ใน URL (/v1/products) หรือใช้ header (Accept: application/vnd.example.v2+json) เลือกเอาที่เหมาะกับ project เราเลย

ใช้ Pagination กับ List Endpoints

ถ้า endpoint ของเรา return ข้อมูลเยอะๆ อย่าส่งมาทั้งหมดทีเดียว! Server จะอืด Application ก็จะค้าง Pagination ช่วยได้ครับ

ใส่ query parameters เช่น limit กับ offset เข้าไป เพื่อให้ client สามารถ request ข้อมูลมาทีละหน้าได้

GET /products?limit=20&offset=0

สมัยผมทำร้านเน็ต ก็เคยเจอเคสที่ API ดึงข้อมูลลูกค้าเป็นหมื่นๆ records มาทีเดียว ผลคือ server ล่ม! Pagination นี่แหละช่วยชีวิตไว้

Security First

เรื่องความปลอดภัยสำคัญที่สุด! ใช้ HTTPS เสมอ, validate input ทุกครั้ง, และ protect API ด้วย authentication และ authorization mechanisms ที่เหมาะสม

สมัยก่อนตอนเริ่มทำ SiamCafe.net ใหม่ๆ โดน hack บ่อยมาก เพราะไม่ได้ใส่ใจเรื่อง security เท่าที่ควร บทเรียนราคาแพงเลยครับ

iCafeForex

FAQ คำถามที่พบบ่อย

ทำไมต้องใช้ REST API?

REST API มัน flexible, scalable, และง่ายต่อการ integrate กับ systems อื่นๆ สมัยนี้ ใครๆ ก็ใช้ REST API ครับ

REST API กับ GraphQL ต่างกันยังไง?

REST API return ข้อมูลตามที่ server กำหนด แต่ GraphQL ให้ client เลือกได้ว่าจะเอาข้อมูลอะไรบ้าง GraphQL เหมาะกับ use cases ที่ต้องการ flexibility สูงๆ

Swagger/OpenAPI คืออะไร?

Swagger/OpenAPI เป็น specification สำหรับการ define REST API ทำให้เราสามารถ generate documentation, client SDKs, และ server stubs ได้อัตโนมัติ ชีวิตง่ายขึ้นเยอะเลย

API Gateway คืออะไร?

API Gateway เป็นเหมือน reverse proxy ที่อยู่หน้า API ของเรา ช่วยจัดการเรื่อง authentication, authorization, rate limiting, และ logging ทำให้ API ของเราปลอดภัยและ scalable มากขึ้น

สรุป

REST API design มันเป็นศาสตร์และศิลป์ครับ ไม่มีสูตรสำเร็จตายตัว สิ่งที่สำคัญคือต้องเข้าใจ requirements ของ project เรา และเลือกใช้ practices ที่เหมาะสม หวังว่าบทความนี้จะเป็นประโยชน์นะครับ

อย่าลืมติดตาม SiamCafe Blog นะครับ จะมีบทความเกี่ยวกับ IT ดีๆ มาให้อ่านกันเรื่อยๆ