กฎตั้งชื่อ 7 ข้อ · versioning · idempotency

1 · URL ไม่ใช่เรื่องความสวย มันคือ signature ของฟังก์ชันที่ compiler ไม่ช่วยเช็ค

ตลอด 35 บทที่ผ่านมา เวลาคุณเรียกฟังก์ชันผิดชื่อ Go จะด่าคุณทันทีตอน compile — พิมพ์ repo.FindById ทั้งที่ของจริงชื่อ FindByID โปรแกรมไม่ยอมสร้างไฟล์ให้ด้วยซ้ำ
แต่ HTTP ไม่มีขั้นตอนนั้น คนที่เรียก API ของคุณคือโปรแกรมของคนอื่น ที่พิมพ์ path เป็น "สตริง" — พิมพ์ผิดตัวเดียวไม่มีใครเตือน จะรู้ตัวก็ตอน request วิ่งจริงแล้ว

ผมลงทะเบียน (= บอก router ว่ามี path นี้อยู่ ตามที่เจอใน บทเรียน 34 · router คือตัวจัดเส้นทางของ server ที่คอยดูว่า path ไหนให้โค้ดชิ้นไหนรับ) ไว้แค่ GET /payment-methods เส้นเดียว แล้วยิงด้วยการสะกดแบบต่าง ๆ:

GET /payment-methods     -> 200
GET /Payment-Methods     -> 404
GET /PAYMENT-METHODS     -> 404
GET /payment_methods     -> 404
GET /paymentMethods      -> 404

สี่บรรทัดล่างคือคนที่เข้าใจว่า API ของคุณมีอยู่จริง เขาแค่เดาการสะกดผิด และสิ่งที่เขาได้กลับไปคือ 404 — status code เดียวกับ "ไม่มีข้อมูลนี้" เขาจะแยกไม่ออกเลยว่า ผมพิมพ์ path ผิด หรือ ข้อมูลไม่มีจริง

2 · กฎ 7 ข้อ จริง ๆ แล้วตอบอยู่แค่สองคำถาม

ถ้าท่องเป็น 7 ข้อจะลืม แต่ถ้าเห็นว่ามันแบ่งเป็นสองกลุ่มจะจำได้ตลอดชีวิต

กลุ่ม A (ข้อ 1–4) คือกฎการสะกด — ทุกข้อแก้ปัญหาเดียวกับที่คุณเพิ่งเห็นในหัวข้อ 1 คือมี "ตัวสะกดที่ถูก" อยู่แบบเดียว แล้วที่เหลือกลายเป็น 404 หมด
ข้อ 2 ที่ดูจุกจิกที่สุด (/user เอกพจน์ปนกับ /orders พหูพจน์) จริง ๆ แล้วแพงที่สุด เพราะมันทำให้คนที่ใช้ API ของคุณเดาไม่ได้อีกต่อไป — พอเจอ /user ครั้งหนึ่ง เขาต้องเปิดเอกสารทุกครั้งไปตลอด ไม่กล้าเดาอีกเลย

กลุ่ม B (ข้อ 5–7) คือกฎการจัดที่อยู่ของข้อมูล — ต่อยอดจาก บทเรียน 35 โดยตรง:
ข้อ 5 = สิ่งที่ระบุตัวของ (id, ความเป็นเจ้าของ) ไปอยู่ที่ path
ข้อ 6 = สิ่งที่กรอง/เรียง/แบ่งหน้า ไปอยู่ที่ query
ข้อ 7 = สิ่งที่บอกว่าจะทำอะไรกับของชิ้นนั้น ไปอยู่ที่ method

3 · จับผิดสไลด์หน้า 35

หน้า 29–34 ของสไลด์ไล่กฎข้อ 1–6 มาถูกหมด พอถึงหน้า 35 ซึ่งเป็นตัวอย่างของกฎข้อ 7 หน้าจอโชว์แบบนี้ (ผมลอกมาทั้งบล็อกตามที่เห็นในสไลด์ รวมเลขบรรทัด):

1  // ✅ แนะนำ
2  POST /users/create
3  POST /users/123/delete
4
5  // ❌ แบบนี้ไม่แนะนำ
6  POST /users
7  DELETE /users/123

POST /users/create
POST /users/123/delete

POST /users
DELETE /users/123

4 · แล้ว PATCH /users/123/suspend ล่ะ ทำไมถึงถูก

หน้า 36 ของสไลด์ต่อจากหน้า 35 ทันที และหน้านี้เขียนถูก:

// ✅ แนะนำ
PATCH /users/123/suspend
PATCH /users/123/reset-password

ตรงนี้มือใหม่งงกันเยอะมาก — เมื่อกี้บอกว่าห้ามใส่ verb ใน URI แล้วนี่มันไม่ใช่ verb เหรอ
คำตอบอยู่ในตัวกฎเอง: "อย่าใส่ Action ใน URI ถ้า HTTP Method สื่อได้แล้ว" — เงื่อนไขท้ายประโยคคือหัวใจ

HTTP มี method ให้เลือกอยู่ไม่กี่ตัว และมันสื่อได้แค่ 5 อย่าง: อ่าน (GET) / สร้าง (POST) / แทนที่ทั้งก้อน (PUT) / แก้บาง field (PATCH) / ลบ (DELETE)
ทีนี้ลองถามว่า "ระงับบัญชี" คือหนึ่งใน 5 อย่างนั้นไหม

แถวที่สามคือเหตุผลที่แข็งแรงที่สุด: PATCH /users/123 ที่รับ {"status":"suspended"} แปลว่าคุณกำลังบอกโลกว่า status เป็น field ที่แก้ได้ตามใจ — พรุ่งนี้จะมีคนส่ง {"status":"admin"} มาให้เห็น
ส่วน PATCH /users/123/suspend คือประตูบานเดียวที่เปิดไปได้ทางเดียว — ตัว URI เองกลายเป็นการจำกัดสิทธิ์

5 · ก่อนเขียนโค้ด ต้องตอบ 5 ช่องนี้ให้ครบ

สไลด์หน้า 38 ให้ checklist มา 5 บรรทัด และมันสั้นจนอ่านผ่านได้ง่ายมาก แต่นี่คือสิ่งที่แยก "endpoint ที่ทีมอื่นเอาไปใช้ได้" ออกจาก "endpoint ที่ต้องเดินไปถามคนเขียน"

ช่องที่คนลืมบ่อยที่สุดคือช่องสุดท้าย และมันเจ็บที่สุด
ถ้า endpoint หนึ่งตอบ {"error":"..."} อีก endpoint ตอบ {"message":"..."} อีกอันตอบข้อความเปล่า ๆ ไม่ใช่ JSON — ฝั่ง frontend ต้องเขียนโค้ดอ่าน error สามแบบ และจะมีวันที่เขาอ่านพลาดแล้วโชว์ undefined ให้ลูกค้าเห็น

ทั้ง 5 ช่องนี้รวมกันเรียกว่า contract และคำนี้ต้องเข้าใจตามตัวอักษร: มันคือสัญญา
พอมีคนเอา endpoint ของคุณไปใช้แล้ว คุณแก้ contract ฝ่ายเดียวไม่ได้อีก
นั่นคือเหตุผลที่ต้องมี versioning ซึ่งเป็นหัวข้อสุดท้ายของบทนี้ — แต่ก่อนจะไปถึงตรงนั้น มีคำถามที่แพงกว่ารออยู่

6 · Idempotency — คำที่แปลว่า "ยิงซ้ำได้ไม่พัง"

สไลด์หน้า 39 นิยามไว้ว่า "หากมีการเรียก operation เดิมซ้ำหลายครั้ง ผลลัพธ์สุดท้ายควรเหมือนเรียกเพียงครั้งเดียว" แล้วยกตัวอย่างที่ทุกคนกลัว: POST /payments แล้ว retry (= ยิงคำสั่งเดิมซ้ำอีกรอบเพราะรอคำตอบไม่ได้) — จ่ายสองรอบไหม?

ก่อนไปต่อ ต้องเข้าใจว่าทำไมถึงมี retry ตั้งแต่แรก — ไม่ใช่เพราะผู้ใช้กดปุ่มรัว แต่เพราะเน็ตขาดตอนกลางทางแล้วไม่มีใครรู้ว่าถึงหรือยัง
(ในภาพข้างล่าง client คือฝั่งที่ยิงคำสั่งเข้ามา — เว็บ แอปมือถือ หรือ service อื่น · server คือฝั่งที่รับแล้วตอบกลับ)

  client                                server
    │                                     │
    │──── POST /payments ────────────────▶│  ตัดเงินเรียบร้อย ✔
    │                                     │
    │◀╌╌╌ 201 Created ╌╌╌╌✂╌╌ (เน็ตขาด) ╌╌│  server ทำงานเสร็จแล้ว
    │                                     │
  timeout — client เห็นแค่ "ไม่มีคำตอบ"
    │
    ├─▶ ยิงซ้ำ  = เสี่ยงตัดเงินสองรอบ
    └─▶ ไม่ยิงซ้ำ = เสี่ยงลูกค้าจ่ายไม่สำเร็จทั้งที่เงินออกไปแล้ว

client ไม่มีทางรู้เลยว่า request ตายก่อนถึง server หรือตายตอนขากลับ — สองเคสนี้หน้าตาเหมือนกันเป๊ะจากฝั่ง client นี่คือเหตุผลที่ทุก HTTP client ในโลกจริงมี retry และเป็นเหตุผลที่ idempotency ต้องมีอยู่

$ curl -X POST http://127.0.0.1:53691/payments   # ยิงสามครั้งติด

{"payment_id":"pay_1","amount":500,"charged_total":500}   <- 201
{"payment_id":"pay_2","amount":500,"charged_total":1000}  <- 201
{"payment_id":"pay_3","amount":500,"charged_total":1500}  <- 201

$ curl http://127.0.0.1:53691/total
charged_total=1500 payments=pay_1,pay_2,pay_3

เทียบกับ PUT ที่ยิงซ้ำแบบเดียวกัน — ผมยิงสองครั้งด้วย body เดิม:

$ curl -X PUT -d '{"name":"Somchai"}' http://127.0.0.1:53691/users/9   # ยิงสองครั้ง
{"id":"9","name":"Somchai"}  <- 200
{"id":"9","name":"Somchai"}  <- 200

เหมือนกันทุกตัวอักษร เพราะ PUT แปลว่า "ทำให้ user 9 มีหน้าตาเป็นแบบนี้" ไม่ใช่ "เพิ่มอีกหนึ่ง" — ความต่างอยู่ที่ความหมายของคำสั่ง ไม่ได้อยู่ที่ความเก่งของโค้ด

7 · DELETE /users/1 สองครั้ง ครั้งที่สองควรตอบ 404 หรือ 204

นี่เป็นคำถามที่ถูกเถียงกันในทุกทีมที่เคยทำ API และมันไม่มีคำตอบเดียว — แต่การรู้ว่าทำไมถึงไม่มีคำตอบเดียว มีค่ากว่าการจำคำตอบ ผมเขียนทั้งสองแบบแล้วยิงจริง
(กล่องแดง/เขียวข้างล่างเป็นแค่สีของกล่องเปรียบเทียบ ไม่ได้แปลว่าแบบ A ผิด — เดี๋ยวจะเห็นว่าถูกทั้งคู่)

1st DELETE /users/1 -> 204
2nd DELETE /users/1 -> 404
{"error":"user not found"}

1st DELETE /users/2 -> 204
2nd DELETE /users/2 -> 204

สำคัญที่สุด: ทั้งสองแบบ idempotent ทั้งคู่
เพราะ idempotency วัดที่สถานะปลายทางของ server — และปลายทางของทั้งสองแบบเหมือนกันเป๊ะ คือ "ไม่มี user คนนี้" ไม่ว่าจะยิงกี่ครั้ง · status code ที่ต่างกันไม่ได้ทำให้มันเลิก idempotent

เวลาเลือกจริง ให้ถามว่าใครเป็นคนเรียก endpoint นี้:

8 · แล้ว POST ที่ retry ไม่ได้ล่ะ — Idempotency-Key

POST จะไม่มีวัน idempotent ได้ด้วยตัวมันเอง เพราะความหมายของมันคือ "สร้างของใหม่"
ทางออกจึงไม่ใช่การแก้ method แต่คือให้ client บอก server ว่า "สาม request นี้คือเจตนาเดียวกันนะ" — ด้วย header ที่ client เป็นคนสร้างค่าเอง

  client สร้าง key ครั้งเดียว ก่อนยิงครั้งแรก  →  key = "8f3c-01"
    │
    ├─▶ POST /payments   Idempotency-Key: 8f3c-01
    │      server: ยังไม่เคยเห็น key นี้ → ตัดเงินจริง → เก็บ (key → คำตอบ) ไว้
    │
    ├─▶ POST /payments   Idempotency-Key: 8f3c-01   (retry เพราะ timeout)
    │      server: เคยเห็นแล้ว → ไม่ทำอะไรใหม่ → คืนคำตอบเดิมที่เก็บไว้
    │
    └─▶ POST /payments   Idempotency-Key: 8f3c-02   (ผู้ใช้ตั้งใจจ่ายรอบใหม่จริง ๆ)
           server: key ใหม่ → ตัดเงินอีกรอบ ถูกต้องแล้ว

ผมทำ endpoint แบบนี้แล้วยิง key เดิมสามครั้ง แล้วตามด้วย key ใหม่หนึ่งครั้ง (... ในคำสั่งข้างล่างคือ http://127.0.0.1:53691 ตัวเดิม ย่อไว้ให้อ่านง่าย):

$ curl -X POST -H 'Idempotency-Key: 8f3c-01' .../idem/payments   # สามครั้ง
{"payment_id":"pay_4","amount":500,"charged_total":2000}  <- 201
{"payment_id":"pay_4","amount":500,"charged_total":2000}  <- 201
{"payment_id":"pay_4","amount":500,"charged_total":2000}  <- 201

# คนละ key = คนละเจตนา
$ curl -X POST -H 'Idempotency-Key: 8f3c-02' .../idem/payments
{"payment_id":"pay_5","amount":500,"charged_total":2500}  <- 201

charged_total ขยับจาก 1500 → 2000 ครั้งเดียว ตลอดสาม request แรก แล้วขยับเป็น 2500 ตอนเปลี่ยน key — นี่คือพฤติกรรมที่เราต้องการเป๊ะ ๆ

สังเกตว่าครั้งที่ 2 และ 3 ก็ยังตอบ 201 Created ทั้งที่ไม่ได้สร้างอะไรใหม่ — เพราะ server กำลังเล่นเทปคำตอบเดิม ให้ฟัง จุดนี้คนออกแบบมักเติม header บอกไว้ให้ client รู้ตัว ผมใส่ไว้ด้วย:

# -D -  = พิมพ์ response header ออกจอ · -o /dev/null = ทิ้ง body ไม่ต้องโชว์
$ curl -D - -o /dev/null -X POST -H 'Idempotency-Key: 8f3c-01' .../idem/payments
HTTP/1.1 201 Created
Idempotent-Replay: true

9 · Versioning — "breaking change" คืออะไรกันแน่

สไลด์หน้า 37 บอกว่า versioning มีไว้ "รองรับกรณีที่เกิด Breaking Change เพื่อให้ Client เดิมที่ยังไม่ Migrate สามารถทำงานต่อไปได้ในช่วงเวลาที่กำหนด" แล้วโชว์ /api/v1/users → /api/v2/users

ประโยคนั้นถูก แต่มันข้ามคำถามที่ยากที่สุดไป: รู้ได้ยังไงว่าอะไรคือ breaking change
คำจำกัดความที่ใช้ได้จริงมีข้อเดียว — "client ตัวเก่าที่ไม่ได้แก้อะไรเลย ยังทำงานถูกต้องอยู่ไหม" ถ้าคำตอบคือไม่ นั่นคือ breaking
ผมเลยทดลองเป็น client เก่าจริง ๆ: struct ตัวนี้เขียนไว้ตั้งแต่ v1 แล้วไม่เคยแก้อีกเลย

// client เก่า — ไม่เคยแก้ตั้งแต่ v1
type Recipe struct {
    ID          int    `json:"id"`
    Name        string `json:"name"`
    CookingTime int    `json:"cooking_time"`
}

// แล้วเอา JSON 5 แบบนี้มา json.Unmarshal ใส่ struct เดิม
เพิ่ม field ใหม่   {"id":7,"name":"ต้มยำกุ้ง","cooking_time":30,"difficulty":"medium"}
ลบ field ทิ้ง      {"id":7,"name":"ต้มยำกุ้ง"}
เปลี่ยนชื่อ field  {"id":7,"name":"ต้มยำกุ้ง","cookingTime":30}
เปลี่ยน type      {"id":7,"name":"ต้มยำกุ้ง","cooking_time":"30 นาที"}
เปลี่ยนความหมาย   {"id":7,"name":"ต้มยำกุ้ง","cooking_time":1800}  // เปลี่ยนหน่วยนาที→วินาที

// แถวแรกคือ JSON v1 เดิม ใส่ไว้เป็นตัวเทียบ ที่เหลือคือ 5 แบบในโจทย์
v1 เดิม                err=<nil>
                       ได้ {ID:7 Name:ต้มยำกุ้ง CookingTime:30}
เพิ่ม field ใหม่       err=<nil>
                       ได้ {ID:7 Name:ต้มยำกุ้ง CookingTime:30}
ลบ field cooking_time  err=<nil>
                       ได้ {ID:7 Name:ต้มยำกุ้ง CookingTime:0}
เปลี่ยนชื่อ field      err=<nil>
                       ได้ {ID:7 Name:ต้มยำกุ้ง CookingTime:0}
เปลี่ยน type           err=json: cannot unmarshal string into Go struct field Recipe.cooking_time of type int
                       ได้ {ID:7 Name:ต้มยำกุ้ง CookingTime:0}
เปลี่ยนความหมาย        err=<nil>
                       ได้ {ID:7 Name:ต้มยำกุ้ง CookingTime:1800}

// js คือสตริง JSON ก้อนเดิมที่มี "difficulty" เพิ่มเข้ามา
dec := json.NewDecoder(strings.NewReader(js))
dec.DisallowUnknownFields()      // เจอ field แปลกปลอม = error
err := dec.Decode(&recipe)      // ใช้ Decode ไม่ใช่ json.Unmarshal

DisallowUnknownFields err=json: unknown field "difficulty"

พอรู้ว่าอะไรคือ breaking แล้ว กฎของ /api/v1 → /api/v2 ก็ตรงไปตรงมา:

10 · เอาทั้งบทมาทาบกับ Wongnok

สไลด์หน้า 71–72 ให้ API spec ของโปรเจกต์ Wongnok (เว็บรวมสูตรอาหาร) มาแล้ว ลองเอากฎทั้งหมดในบทนี้ไปทาบดู

แถวสุดท้ายไม่ใช่ความผิดพลาด — endpoint กลุ่ม auth คือข้อยกเว้นที่โลกยอมรับกันทั่วไป เพราะ /login ไม่ได้กำลัง "สร้าง resource" มันคือขั้นตอนของโปรโตคอล (OAuth เรียกชื่อพวกนี้มาตายตัวอยู่แล้ว ทีมคุณเปลี่ยนชื่อเองไม่ได้)
นี่คือบทเรียนสำคัญของทั้งบท: กฎพวกนี้เป็นค่าตั้งต้นที่ดี ไม่ใช่กฎหมาย — แต่คุณควรแหกกฎเพราะมีเหตุผลที่พูดออกมาได้ ไม่ใช่เพราะไม่รู้ว่ามีกฎ

ส่วนแถว POST /recipes/:id/favorite คือของจริงที่คุณจะเจอในโปรเจกต์นี้: ผู้ใช้กดหัวใจแล้วเน็ตช้า เขากดซ้ำอีกที ถ้าคุณเขียนเป็น "เพิ่มแถวใน favorites" เขาจะได้สองแถว — แต่ถ้าเขียนเป็น "ทำให้ (user, recipe) คู่นี้อยู่ในตาราง favorites" กดกี่ครั้งก็ได้ผลเดียว · ความต่างอยู่ที่ประโยคที่คุณคิดในหัว ไม่ใช่ที่ syntax

ทดสอบความเข้าใจ

$ mkdir wongnok-contract && cd wongnok-contract
$ go mod init wongnok-contract
$ touch recipe_test.go        # ไฟล์เดียวพอ ไม่ต้องมี main.go
$ go test ./...               # รันจากในโฟลเดอร์นี้

อ้างอิง

• RFC 9110 §9.2.2 — Idempotent Methods · §9.2.1 Safe Methods — นิยามทางการของ safe/idempotent และประโยคสำคัญที่ว่า status code ที่ต่างกันไม่ได้ทำให้เลิก idempotent
• RFC 3986 §6.2.2.1 — Case Normalization — ทำไม path ถึงสนตัวพิมพ์เล็กใหญ่ แต่ scheme/host ไม่สน
• MDN — HTTP request methods · 204 No Content — ตารางสรุป safe / idempotent / cacheable ของทุก method
• IETF Internet-Draft — The Idempotency-Key HTTP Header Field — ร่างมาตรฐานของ header ตัวนี้ (ย้ำว่ายังเป็น draft)
• Stripe API — Idempotent requests — ตัวอย่างการใช้จริงระดับ production รวมถึงอายุของ key และการผูก key กับผู้ใช้
• pkg.go.dev — Decoder.DisallowUnknownFields · บทเรียน 13 — พฤติกรรม default ของ json.Unmarshal กับ field ที่ไม่รู้จัก
• Google — API Design Guide: Resource Oriented Design — อีกสำนักหนึ่งที่บังคับให้ทุก action กลายเป็น resource ใช้เทียบกับกฎข้อ 7 ได้ดี