api-design

name	api-design
description	ออกแบบหรือรีวิว API — resource naming, status codes ที่ถูกความหมาย, pagination ตั้งแต่วันแรก, error shape เดียวทั้งแอป, idempotency — โดยอ่าน routes จริงใน codebase ก่อน เพราะ consistency กับของเดิมชนะความสวยตามตำรา Trigger on "ออกแบบ api", "รีวิว api", "วาง endpoint", "api design", or when the user is adding or changing API endpoints.

api-design — API ที่ดีคือ API ที่เดาได้ โดยไม่ต้องเปิด docs

Phase 0 — Convention เดิมมาก่อนตำรา

ถ้าโปรเจกต์มี API อยู่แล้ว: อ่าน routes จริงทั้งหมดก่อน (routes/, controllers/, app router) แล้วสกัด convention ที่ใช้อยู่ — แอปที่ผสมสอง convention แย่กว่าแอปที่ใช้ convention เชยๆ แต่สม่ำเสมอทั้งแอป ของใหม่ต้องหน้าตาเหมือนของเก่า เว้นแต่ user สั่งยกเครื่อง

Phase 1 — Checklist ออกแบบ/รีวิว

เรื่อง	กติกา
Naming	คำนามพหูพจน์ ไม่ใช่กริยา — POST /orders ไม่ใช่ /createOrder; nested ไม่เกิน 2 ชั้น (/users/:id/orders พอ ลึกกว่านั้นใช้ query/filter)
Status codes	201+Location เมื่อสร้าง, 204 เมื่อไม่มี body, 400 รูปแบบผิด vs 422 ค่าไม่ผ่านกติกา, 401 ยังไม่ล็อกอิน vs 403 ล็อกอินแล้วแต่ไม่มีสิทธิ์, 409 ชนกับ state ปัจจุบัน — ห้ามตอบ 200 พร้อม {"error": ...}
Error shape	โครงเดียวทั้งแอป: {"error": {"code": "...", "message": "...", "details": [...]}} — code เป็น machine-readable สำหรับ client แยก case, message สำหรับคน
Pagination	บังคับบน collection ตั้งแต่วันแรก (เติมทีหลัง = breaking change) — cursor-based ถ้าข้อมูลโต/insert ถี่, page-based พอถ้าเล็กและมี UI แบ่งหน้า
Filtering/sorting	query params ตั้งชื่อสม่ำเสมอ (?status=paid&sort=-created_at) — อย่า invent DSL ใหม่ถ้าไม่จำเป็น
Idempotency	PUT/DELETE ต้อง idempotent โดยความหมาย; POST ที่ retry แล้วอันตราย (จ่ายเงิน, สั่งซื้อ) รองรับ Idempotency-Key
ค่าและเวลา	เวลา = ISO 8601 UTC เสมอ (2026-07-08T14:00:00Z); เงิน = integer หน่วยย่อย (สตางค์) ห้าม float
Versioning	ยังไม่มีผู้ใช้ภายนอก → ยังไม่ต้องมี /v1 ก็ได้ แต่ตัดสินใจแล้วบันทึกไว้; มีเมื่อไหร่ breaking change ต้องออก version ใหม่ ไม่แก้ของเดิมเงียบๆ

Phase 2 — Output

• ตาราง endpoint: method · path · req body · res body · error codes ที่เป็นไปได้
• ตัวอย่าง JSON จริง ของ req/res อย่างน้อย endpoint หลัก — shape จริงมีค่ากว่าคำอธิบาย
• โหมดรีวิว: ชี้จุดที่ขัด convention ของ codebase เองเป็น file:line เรียงตามผลกระทบ (breaking > confusing > cosmetic)

กติกา

• อย่า over-engineer — ไม่เสนอ HATEOAS, GraphQL, gRPC, event sourcing ถ้าโจทย์ไม่ได้เรียก ความเรียบง่ายที่สม่ำเสมอคือเป้า
• ระวังเปิดข้อมูลเกิน: ทุก endpoint ระบุว่าใครเรียกได้ และ response ไม่แถม field ที่ role นั้นไม่ควรเห็น (mass assignment / over-fetching)
• ถ้าแตะ endpoint เดิมที่มีคนใช้อยู่ — ระบุเสมอว่าอะไร breaking อะไร additive