สรุปแนวปฏิบัติที่ดี

ตอนนี้คุณมีชุดเครื่องมือครบถ้วนแล้ว นี่คือทั้งคอร์สรวมเป็นเช็กลิสต์เดียวที่คุณนำไปใช้กับ API ใด ๆ ที่คุณออกแบบหรือรีวิวได้

แผนผัง

flowchart TD
  Start[Design a REST API] --> R[Resources & URIs]
  Start --> M[Methods & idempotency]
  Start --> E[Status & errors]
  Start --> Q[Querying collections]
  Start --> VC[Versioning & caching]
  Start --> Sec[Security]
  Start --> Ship[Docs, tests, build]

เจ็ดด้านที่ประกอบกันเป็น API ที่ออกแบบมาอย่างดี

เช็กลิสต์

Resources & URIs — สร้างโมเดลเป็นคำนาม ไม่ใช่การกระทำ; collection เป็นพหูพจน์ (/articles); path เป็นตัวพิมพ์เล็กคั่นด้วยขีดกลาง; ID อยู่ใน path; ซ้อน (nest) เฉพาะกรณีที่เป็นเจ้าของกันจริง ๆ นอกนั้นให้ใช้ link แทน ดู Resource & URI Design

Methods & idempotency — map CRUD ไปยัง GET/POST/PUT/PATCH/DELETE; ห้ามเปลี่ยนแปลงข้อมูลบน GET; ทำให้การเขียนเป็น idempotent ในที่ที่ทำได้; ปกป้องการสร้างที่ไม่ใช่ idempotent ด้วย idempotency key ดู Methods, CRUD & Idempotency

Status & errors — เลือก status code ที่แม่นยำ; ห้ามคืน 200 สำหรับความล้มเหลว; ใช้รูปแบบ error problem+json ที่สม่ำเสมอเพียงหนึ่งเดียว; คืน error จากการ validate ทั้งหมดในคราวเดียว ดู Status Codes & Errors

Querying collections — ทำ pagination เสมอ (เลือก cursor สำหรับข้อมูลที่ใหญ่/เปลี่ยนแปลงบ่อย); ทำ allowlist สำหรับ field ที่ filter/sort; เสนอ sparse fieldset และ envelope ที่สม่ำเสมอ ดู Querying Collections

Versioning & caching — เน้นการเปลี่ยนแปลงแบบเพิ่มเติมที่ไม่ทำให้พัง; ทำ version แบบหยาบเมื่อจำเป็น; ตั้งค่า Cache-Control และ ETag; ใช้ conditional request เพื่อจัดการ concurrency ดู Versioning & Caching

Security — ใช้ HTTPS เท่านั้น; ห้ามใส่ secret ใน URL; แยกแยะ 401/403; ตรวจสอบ token (อย่าเพียงแค่ decode); allowlist CORS ที่รัดกุม; rate-limit และ validate input ทั้งหมด ดู Security

Ship it — อธิบาย API ด้วย OpenAPI; ทดสอบทั้งชั้น unit/integration/contract; ให้ handler บางและ service ปลอดจาก HTTP ดู OpenAPI

Category	Best Practice	Anti-Pattern
Resource Design	noun-based URI, plural	/getUser, /createOrder
HTTP Methods	method แสดง intent	POST สำหรับทุก operation
Status Codes	2xx/4xx/5xx ถูกต้อง	200 พร้อม error body
Error Format	machine-readable code	plain string message
Pagination	default limit, cursor/offset	return ทุก record
Authentication	Bearer token ใน header	token ใน query string
Versioning	URI versioning /v1/	ไม่มี version เลย
Caching	Cache-Control, ETag	ไม่มี caching header

ข้อผิดพลาดที่พบบ่อย

ไม่มี API Design Review ก่อน Implement อาการ:

• developer implement endpoint ก่อน ค่อยทำ documentation
• consumer ใช้ API แล้วพบว่า design ไม่ consistent
• ทำ API design review (OpenAPI spec หรือ design doc) ก่อน implement ทุกครั้ง

Breaking Change โดยไม่ Version อาการ:

• เปลี่ยน response field name: userId → user_id ใน /v1/
• consumer ที่ใช้ userId พังทันที
• additive change เท่านั้นใน version เดิม; breaking change ต้อง bump version

💡 ตัวอย่างจากของจริง

Stripe API:

• ยึดถือ backward compatibility อย่างเคร่งครัด — API v1 ออก 2011, ยัง support ในปัจจุบัน
• ทุก breaking change มีเวอร์ชัน date ใหม่ และ account lock ที่ version เก่าโดยอัตโนมัติ

GitHub API:

• deprecation notice ล่วงหน้า 12 เดือน
• Deprecation header บน response ที่ใกล้หมดอายุ — consumer รู้ก่อน endpoint ปิด

🌐 ความสม่ำเสมอเหนือกว่าความฉลาด

API ที่ดีที่สุดไม่ใช่ API ที่ฉลาดที่สุด แต่คือ API ที่คาดเดาได้มากที่สุด ถ้าใช้แนวปฏิบัติเหล่านี้อย่างสม่ำเสมอ developer ที่เคยใช้ endpoint เดียวของคุณจะเดาที่เหลือได้เอง และความคาดเดาได้นี่แหละ มากกว่าฟีเจอร์ใด ๆ ที่ทำให้การเขียน code คุยกับ API ของคุณเป็นเรื่องน่าสนุก

คุณภาพเดียวใดที่ทำให้ API น่าใช้มากที่สุด?

ความฉลาด ความสม่ำเสมอที่คาดเดาได้ทั่วทุก endpoint เฟรมเวิร์กที่ใหม่ที่สุด เอกสารที่น้อยที่สุด

ข้อใดคือกฎทั่วทั้งคอร์สที่คุณไม่ควรฝ่าฝืน?

ใช้ cursor pagination เสมอ ห้ามคืน 200 สำหรับความล้มเหลว ซ้อน sub-resource ลึก ๆ เสมอ ใส่ version ใน header เสมอ

Submit

Mark as complete