Method และ Status Code

คำศัพท์เล็ก ๆ สองชุดทำงานส่วนใหญ่ใน REST API นั่นคือ HTTP method ไม่กี่ตัวที่บอกเจตนา และ status code ที่รายงานผลลัพธ์ เรียนรู้สองสิ่งนี้ให้ดีแล้วการตัดสินใจด้านการออกแบบส่วนใหญ่จะง่ายขึ้น

Method

Method	ความหมาย	Safe	Idempotent
`GET`	อ่าน resource	yes	yes
`HEAD`	อ่านเฉพาะ header	yes	yes
`POST`	สร้าง / ส่งข้อมูล	no	no
`PUT`	แทนที่ resource	no	yes
`PATCH`	อัปเดตบางส่วน	no	no
`DELETE`	ลบ resource	no	yes
`OPTIONS`	อธิบายว่าทำอะไรได้บ้าง	yes	yes

Safe หมายถึงการเรียกนั้นไม่มี side effect ที่สังเกตได้ คืออ่านอย่างเดียว ส่วน idempotent หมายถึงเรียกซ้ำหลายครั้งได้ผลเท่ากับเรียกครั้งเดียว สองคุณสมบัตินี้เป็นตัวกำหนดความถูกต้องอยู่มาก เพราะ client และ proxy จะ retry request ที่ safe/idempotent ได้อย่างอิสระ แต่ต้องระวังเป็นพิเศษเวลาจะ retry POST

ตระกูลของ status code

flowchart TD
  R[Response status] --> I[1xx Informational]
  R --> S[2xx Success]
  R --> RD[3xx Redirection]
  R --> C[4xx Client error]
  R --> SE[5xx Server error]
  S --> S2[200 OK / 201 Created / 204 No Content]
  C --> C2[400 / 401 / 403 / 404 / 409 / 422]
  SE --> SE2[500 / 503]

ห้าตระกูล; ในทางปฏิบัติคุณใช้เพียงส่วนย่อยเล็ก ๆ เท่านั้น

ตัวที่คุณใช้อยู่ตลอด: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 500 Internal Server Error กฎทองคือ 2xx หมายถึง request สำเร็จ 4xx หมายถึง client ต้องเปลี่ยนแปลงอะไรบางอย่าง และ 5xx หมายถึง server ทำงานล้มเหลว

Method และ status ใน API จริง

แอป Hono ตัวนี้เปิดสาม route ที่คืน method และ status ต่างกัน ลองเปิดใน StackBlitz เพื่อรัน server จริงแล้วยิงเข้า endpoint ดู:

JavaScript

// A tiny read-only resource with sensible statuses.
const articles = [{ id: 1, title: 'Hello' }];

app.get('/articles', (c) => c.json(articles)); // 200 OK

app.get('/articles/:id', (c) => {
  const found = articles.find((a) => a.id === Number(c.req.param('id')));
  if (!found) return c.json({ error: 'Not found' }, 404);
  return c.json(found); // 200 OK
});

app.post('/articles', async (c) => {
  const body = await c.req.json();
  const created = { id: articles.length + 1, ...body };
  articles.push(created);
  return c.json(created, 201); // 201 Created
});

HTTP Method	Intent	Idempotent?
GET	อ่านข้อมูล	✅ ใช่
POST	สร้าง resource ใหม่	❌ ไม่ใช่
PUT	แทนที่ resource ทั้งหมด	✅ ใช่
PATCH	แก้ไขบางส่วน	อาจใช่
DELETE	ลบ resource	✅ ใช่

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

ใช้ POST สำหรับทุก operation อาการ:

POST /getUser, POST /updateUser, POST /deleteUser
ไม่มีวิธีรู้ว่า request ทำอะไรโดยไม่อ่าน body
ใช้ method ที่ตรงกับ intent: GET อ่าน, DELETE ลบ, PATCH แก้

Return 200 แม้เกิด Error อาการ:

{ "status": "error", "message": "Not found" } พร้อม HTTP 200
monitoring tool คิดว่า request สำเร็จ — alert ไม่ทำงาน
ใช้ status code ที่ถูกต้อง: 404 เมื่อไม่พบ, 400 เมื่อ request ผิด

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

GitHub API:

GET /repos/{owner}/{repo} — อ่านข้อมูล repo

DELETE /repos/{owner}/{repo} — ลบ repo

PATCH /repos/{owner}/{repo} — แก้ไข repo settings

method บอก intent ทันที โดยไม่ต้องอ่าน URL

Stripe API:

POST /charges — สร้าง charge ใหม่

GET /charges/{id} — ดู charge

status code ครบ: 200, 201, 400, 401, 402, 404, 429, 500