REST — ทุกอย่างคือ resource

1 · API คืออะไร — และทำไมมือถือถึงไม่ยิง SQL ตรง ๆ

ลองคิดแบบไร้เดียงสาที่สุดก่อน: เรามี PostgreSQL อยู่แล้ว แอปมือถือก็แค่ต่อเข้า database ตรง ๆ แล้ว SELECT * FROM recipes เอง จบ ไม่ต้องมี server ตรงกลางให้เปลืองแรง
ฟังดูเข้าท่า จนกว่าจะถามสี่คำถามนี้:

API คือกำแพงที่แก้ทั้งสี่ข้อพร้อมกัน — เราไม่เปิด database ให้โลกภายนอก แต่เปิดรายการคำขอที่อนุญาตให้แทน ข้างในกำแพงจะเป็น PostgreSQL, MySQL หรือไฟล์ JSON ก็เรื่องของเรา ไม่มีใครข้างนอกต้องรู้

  แบบไร้เดียงสา                        แบบที่ใช้ได้จริง

  📱 แอป ──── SQL ────▶ 🗄️ DB        📱 แอป ─┐
  💻 เว็บ ──── SQL ────▶ 🗄️ DB        💻 เว็บ ─┼─ HTTP ─▶ 🧱 API ─ SQL ─▶ 🗄️ DB
  🤖 บอท ──── SQL ────▶ 🗄️ DB        🤖 บอท ─┘         (กฎธุรกิจ+สิทธิ์
                                                       อยู่ตรงนี้ที่เดียว)
  รหัส DB กระจายอยู่ 3 ที่                รหัส DB อยู่ที่เดียว
  กฎธุรกิจเขียนซ้ำ 3 รอบ                  ใครแก้ schema ก็แก้แค่หลังกำแพง

ถ้าประโยคนี้คุ้น ๆ ก็เพราะมันคือเรื่องเดียวกับ บทเรียน 10 เป๊ะ ๆ — interface คือสัญญาที่บอกว่า "เรียกอะไรได้" โดยไม่บอกว่า "ข้างในทำยังไง"
API ก็คือ interface ตัวหนึ่ง เพียงแต่คนเรียกอยู่คนละเครื่อง และไม่มีคอมไพเลอร์คอยตรวจให้ว่าเรียกถูก — ความผิดพลาดทุกอย่างจะไปโผล่ตอน runtime ในมือของลูกค้าจริง ๆ เท่านั้น

2 · จะคุยกันด้วย protocol อะไร — และทำไมคอร์สนี้เลือก HTTP

protocol แปลว่า "ข้อตกลงว่าสองเครื่องจะส่งข้อความหากันด้วยหน้าตาแบบไหน" — เทียบได้กับการตกลงว่าจะเขียนจดหมายด้วยภาษาอะไรและวางหัวจดหมายตรงไหน ก่อนจะเริ่มเขียนเนื้อความ
"คุยข้ามเครื่อง" ไม่ได้มีวิธีเดียว สี่แบบที่เจอบ่อยที่สุดในงานจริงมีจุดขายคนละอย่าง — อ่านตารางนี้เพื่อรู้ว่ามันมีอยู่ก็พอ ไม่ต้องจำรายละเอียด:

คอร์สนี้ใช้ HTTP ด้วยเหตุผลข้อเดียวที่สำคัญกว่าข้ออื่นรวมกัน: มันเป็นตัวหนังสือที่คุณอ่านออก
เวลาระบบพัง คุณเปิดดูได้ทั้ง request และ response ด้วยตาเปล่า ทดสอบด้วย curl บรรทัดเดียวได้โดยไม่ต้องมีเครื่องมือพิเศษ — สำหรับคนกำลังเรียน นี่มีค่ามากกว่าความเร็ว

3 · REST คืออะไร — สี่หลักที่ต้องจำ

HTTP บอกแค่ว่า "ข้อความต้องมีหน้าตายังไงถึงจะส่งได้" แต่ไม่ได้บอกว่าควรตั้งชื่ออะไร
ถ้าไม่มีข้อตกลงเพิ่ม ทีมสามคนจะได้ API สามสไตล์ในโปรเจกต์เดียว:

POST /getUserById
POST /user_delete
GET  /updateUserName?id=1&n=x
POST /api/DoRecipeSearch

GET    /users/1
DELETE /users/1
PATCH  /users/1
GET    /recipes?q=x

ก่อนอ่านตารางถัดไป ขอนิยามสองคำที่จะใช้ตลอดทั้ง Day 8 ก่อน:
resource = "ของ" หนึ่งอย่างที่ API เปิดให้ยุ่งด้วย — เป็นได้ทั้งกอง (/recipes = สูตรทั้งหมด) และชิ้นเดียว (/recipes/7 = สูตรที่ 7)
endpoint = หนึ่งคู่ของ method + path ที่ server รับ — GET /recipes/7 คือหนึ่ง endpoint ส่วน DELETE /recipes/7 เป็นอีก endpoint หนึ่ง ถึงจะ path เดียวกันก็ตาม

REST ยืนบนสี่หลักนี้ — สามข้อแรกเป็นวิธีทำ ข้อสุดท้ายคือผลลัพธ์ที่เราต้องการจริง ๆ:

4 · resource-based: URL คือคำนาม ไม่ใช่คำกริยา

กฎมีข้อเดียว: URL บอกว่า "ของชิ้นไหน" · method บอกว่า "จะทำอะไรกับมัน"
คนใหม่มักเผลอเอาคำกริยาไปยัดใน URL เพราะมันเป็นวิธีที่เราตั้งชื่อฟังก์ชันมาตลอด 32 บท (getUser, deleteUser) — แต่ HTTP มีช่องสำหรับคำกริยาแยกไว้ให้แล้ว คือ method
พอเขียนคำกริยาไว้สองที่ มันจะขัดกันเองได้ทันที: POST /recipes/7/delete อ่านฝั่ง method ว่า "สร้าง" แต่อ่านฝั่ง URL ว่า "ลบ" — แล้วเครื่องมือที่อ่าน method (เช่นตัวที่ตัดสินใจว่า retry ได้ไหม) ก็เชื่อฝั่งที่ผิด

สังเกตคอลัมน์ขวา: มีชื่อ resource อยู่แค่สองคำทั้งตาราง (/recipes กับ /users) ส่วนคอลัมน์กลางมีชื่อไม่ซ้ำกันเลยห้าอัน
นี่คือเหตุผลที่ REST ทำให้ระบบเล็กลงในหัวคน — จำนวนชื่อที่ต้องจำ โตตามจำนวน "ของ" ไม่ใช่ตามจำนวน "สิ่งที่ทำได้"

5 · URI · path · path parameter — สามคำที่คนใช้ปนกัน

ก่อนคุยเรื่อง method ต้องแยกศัพท์สามคำนี้ให้ออกก่อน เพราะทั้ง Day 8 จะพูดถึงมันตลอด
ผมเปิด server แล้วดักอ่านไบต์ดิบที่ curl ส่งออกไปจริง ๆ — หน้าตาแบบนี้:

PATCH /users/42?fields=name HTTP/1.1
Host: 127.0.0.1:8793
User-Agent: curl/8.13.0
Accept: */*
Authorization: Bearer abc123
Content-Type: application/json
Content-Length: 21

{"name":"Somchai Jr"}

ทั้งหมดนี้คือ "หนึ่ง request" — ตัวหนังสือล้วน ๆ ไม่มีเวทมนตร์อะไรเลย แบ่งเป็นสามส่วนเรียงจากบนลงล่างเสมอ:

• บรรทัดแรก — method + path (+ query ถ้ามี) + เวอร์ชัน HTTP · นี่คือหัวใจ: "จะทำอะไร" กับ "ของชิ้นไหน" อยู่ในบรรทัดเดียวนี้
• header — บรรทัด ชื่อ: ค่า ต่อกันกี่บรรทัดก็ได้ เป็นข้อมูลประกอบของ request เช่น Content-Type บอกว่า body เป็นข้อมูลชนิดไหน · Authorization บอกว่าใครเป็นคนยิง
• body — ก้อนข้อมูลจริงที่ส่งไป อยู่หลังบรรทัดว่างหนึ่งบรรทัด (บรรทัดว่างนั้นแหละคือเส้นแบ่งว่า header จบแล้ว) · GET ปกติไม่มีส่วนนี้

ทีนี้ซูมเข้าไปดูเฉพาะ "ที่อยู่" ในบรรทัดแรก — ผมเขียนแบบเต็มพร้อมชื่อ server ให้เห็นครบทุกชิ้น:

  https://api.wongnok.com/users/42/orders?status=paid&page=2
  └──────────┬───────────┘└───────┬──────┘└──────────┬──────────┘
        ที่อยู่ของ server          path              query string
     (ไม่ได้อยู่ในบรรทัดแรก        = "ของชิ้นไหน"       = "กรอง/เรียงยังไง"
      แต่อยู่ใน header Host)          │
                                     └─▶ /users/42/orders
                                                  ▲
                                          path parameter — ช่องว่างใน path
                                          ที่เปลี่ยนค่าได้ · เขียนเป็น /users/{id}/orders

  ทั้งบรรทัดรวมกัน = URI (ที่อยู่เต็มของ resource ชิ้นนั้น)

ฝั่ง server มองเห็นเป็นคนละชิ้นแยกกันจริง ๆ ไม่ใช่แค่การเรียกให้ต่างกัน — ผมยิง GET /users/42/orders?status=paid&page=2 ใส่ server อีกตัวที่พิมพ์ทุกอย่างที่มันเห็นออกมา (คนละตัวกับตัวที่พิมพ์ไบต์ดิบข้างบน จึงคนละพอร์ต):

Method      = "GET"
Host        = "127.0.0.1:8792"
URL.Path    = "/users/42/orders"
PathValue   = "42"
RawQuery    = "status=paid&page=2"
Query status= "paid"
RequestURI  = "/users/42/orders?status=paid&page=2"
header Accept           = "application/json"
header User-Agent       = "curl/8.13.0"

ชื่อทางซ้ายไม่ใช่ศัพท์ REST — เป็นชื่อช่องที่ Go เตรียมไว้ให้อ่าน ในบทถัด ๆ ไปของ Day 8 เราจะเรียกมันเองกับมือ ตอนนี้แค่รู้ว่ามันแยกกันจริงก็พอ
ที่ต้องสังเกตคือ PathValue = "42" — Go ได้เลข 42 มาเพราะ server ลงทะเบียนไว้ว่า path หน้าตาแบบ /users/{id}/orders แล้ว {id} คือช่องว่างที่รอรับค่า
ส่วน RawQuery คือ query ทั้งเส้นที่ยังไม่ได้แยก และ Query status คือค่าที่แยกออกมาแล้วเฉพาะตัว status

เส้นแบ่งที่ใช้ตัดสินใจได้จริง — ถ้าเอาส่วนนั้นออกแล้วไม่รู้ว่าพูดถึงของชิ้นไหน มันคือ path parameter (/users/orders เพียว ๆ ไม่มีความหมาย)
ถ้าเอาออกแล้วยังรู้ว่าพูดถึงของกองไหน แค่ได้มาเยอะขึ้น มันคือ query parameter (/users/42/orders ยังแปลว่า "order ของ user 42 ทั้งหมด")

6 · หัวใจของบท — "stateless" แปลว่าอะไรจริง ๆ

คำนี้ถูกแปลผิดบ่อยที่สุดในบรรดาศัพท์ REST ทั้งหมด
stateless ไม่ได้แปลว่า "ห้ามเก็บข้อมูล" — เก็บลง database ได้เต็มที่ นั่นคืองานของมัน
มันแปลว่า: server ไม่จำอะไรเกี่ยวกับ ตัวคุณ ระหว่าง request สองอันติดกัน
request แต่ละอันมาถึงในสภาพคนแปลกหน้า เสมอ ต่อให้เพิ่งคุยกันไปเมื่อ 0.2 วินาทีที่แล้ว

ผมเปิด server ที่นับ request ให้ดูด้วย แล้วยิงสามครั้งติดกันจาก terminal เดียวกัน
ครั้งที่สองผมแนบ token ไปด้วย — token คือข้อความสั้น ๆ ที่ server ออกให้ตอน login แล้ว client เก็บไว้ใช้เป็นบัตรประจำตัวในครั้งถัด ๆ ไป ส่งไปในบรรทัด header ชื่อ Authorization
ตัวเลขที่ตอบกลับมา (401, 200) คือ status code — ตัวเลขสามหลักที่สรุปว่าผลเป็นยังไง ความหมายของแต่ละตัวอยู่ใน บทเรียน 34 ตอนนี้อ่านแค่ว่า 200 = ผ่าน · 401 = ไม่รู้ว่าคุณเป็นใคร ก็พอ

$ curl -i http://127.0.0.1:8791/me                              # ครั้งที่ 1 ไม่ส่งอะไรมา
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 99

{"error":"missing Authorization header","request_no":1,"server_knows":"nothing about who you are"}

$ curl -i http://127.0.0.1:8791/me -H 'Authorization: Bearer abc123'   # ครั้งที่ 2 ส่ง token
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 63

{"request_no":2,"token_seen":"Bearer abc123","user":"Somchai"}

$ curl -i http://127.0.0.1:8791/me                              # ครั้งที่ 3 ไม่ส่ง token อีก
HTTP/1.1 401 Unauthorized
...
{"error":"missing Authorization header","request_no":3,"server_knows":"nothing about who you are"}

ดู request_no ให้ดี: 2 แล้ว 3 — เป็น server ตัวเดียวกัน ยังไม่ได้ restart อะไรเลย
ครั้งที่ 2 มันเพิ่งรู้จักคุณเมื่อเสี้ยววินาทีก่อน ครั้งที่ 3 มันตอบ 401 หน้าตาย
นี่ไม่ใช่บั๊ก — นี่คือธรรมชาติของ HTTP: สิ่งเดียวที่ server รู้ คือสิ่งที่อยู่ใน request ก้อนที่กำลังอ่านอยู่ตอนนี้ ก้อนก่อนหน้าไม่มีอยู่ในโลกของมันแล้ว

"แล้ว session ที่เคยได้ยินล่ะ?" — เก็บ session ไว้ใน RAM ของ server ก็ทำได้ และมันจะทำงาน ตอนที่คุณรัน server ตัวเดียวบนเครื่องตัวเอง
แต่จำเรื่องจาก บทเรียน 32 ได้ไหม — ตอน deploy จริงเราไม่ได้รันโปรแกรมตัวเดียว เรารันสำเนาของโปรแกรมเดียวกันหลายตัว (สำเนาแต่ละตัวเรียกว่า instance) แล้วมีตัวกระจาย request สุ่มไปตัวไหนก็ได้
สำคัญตรงนี้: instance แต่ละตัวคือคนละ process มี RAM ของใครของมัน — ตัวที่ 1 จำอะไรไว้ ตัวที่ 7 มองไม่เห็นเลย

7 · method 5 ตัว — และคู่ที่คนใหม่พลาดบ่อยที่สุด

URL บอกว่า "ของชิ้นไหน" แล้ว · ที่เหลือคือ "จะทำอะไรกับมัน" ซึ่งบอกด้วย method:

สังเกตว่า POST ยิงใส่กอง (/recipes) ส่วน PUT / PATCH / DELETE ยิงใส่ชิ้น (/recipes/7) — เพราะจะสร้างของใหม่ เรายังไม่รู้ id ของมัน จึงชี้เจาะจงไม่ได้

ทีนี้มาถึงจุดที่คนใหม่พลาดกันแทบทุกคน — และมันไม่ใช่ความผิดพลาดที่คอมไพเลอร์หรือ test จะจับให้:

$ curl http://127.0.0.1:8791/users/1
{"id":1,"name":"Somchai","email":"somchai@example.com","role":"member"}

$ curl -X PUT http://127.0.0.1:8791/users/1 \
       -H 'Content-Type: application/json' \
       -d '{"name":"Somchai Jr"}'

$ curl -X PUT .../users/1 -d '{"name":"Somchai Jr"}'
{"id":1,"name":"Somchai Jr","email":"","role":""}

$ curl .../users/1                     # อ่านซ้ำเพื่อยืนยันว่าไม่ใช่แค่ response หลอกตา
{"id":1,"name":"Somchai Jr","email":"","role":""}

$ curl -X PATCH .../users/1 -d '{"name":"Somchai Jr"}'
{"id":1,"name":"Somchai Jr","email":"somchai@example.com","role":"member"}

ก่อน: {name:"Somchai", email:"s@ex.com", role:"member"}
ส่ง:  {name:"Somchai Jr"}
หลัง: {name:"Somchai Jr", email:"", role:""}

ก่อน: {name:"Somchai", email:"s@ex.com", role:"member"}
ส่ง:  {name:"Somchai Jr"}
หลัง: {name:"Somchai Jr", email:"s@ex.com", role:"member"}

อย่าอ่านกล่องซ้ายว่า "PUT คือของผิด" — PUT ไม่ได้ผิด และเราจะใช้มันจริงในบทถัด ๆ ไป
ที่ผิดคือเลือกไม่ตรงกับสิ่งที่ client มีอยู่ในมือ ณ ตอนกดปุ่ม
คำถามเดียวที่ใช้ตัดสิน: ตอนนี้ client ถือข้อมูลครบทั้งก้อนอยู่หรือเปล่า — ครบ → PUT ได้ · ไม่ครบ → ต้อง PATCH

8 · ยิงซ้ำแล้วโลกเปลี่ยนไหม — idempotent

เน็ตหลุดระหว่างรอคำตอบเป็นเรื่องปกติมาก แอปทุกตัวจึงยิงซ้ำอัตโนมัติ
คำถามที่ต้องตอบให้ได้ตั้งแต่ตอนออกแบบคือ: ยิงซ้ำแล้วเกิดอะไรขึ้น
คำว่า idempotent แปลว่า "ยิง 1 ครั้งกับยิง 10 ครั้ง สภาพสุดท้ายของข้อมูลเหมือนกัน"

$ curl -i -X POST http://127.0.0.1:8794/users -d '{"name":"Somchai"}'
$ curl -i -X POST http://127.0.0.1:8794/users -d '{"name":"Somchai"}'
$ curl http://127.0.0.1:8794/users

# ครั้งที่ 1
HTTP/1.1 201 Created
Location: /users/1
{"id":1,"name":"Somchai"}

# ครั้งที่ 2 — body เดิมทุกตัวอักษร
HTTP/1.1 201 Created
Location: /users/2
{"id":2,"name":"Somchai"}

$ curl .../users
[{"id":1,"name":"Somchai"},{"id":2,"name":"Somchai"}]

DELETE ก็ idempotent แต่มีจุดที่ทำให้คนสับสน — status ไม่เท่ากันทั้งสองครั้ง:

$ curl -i -X DELETE http://127.0.0.1:8794/users/1     # ครั้งแรก
HTTP/1.1 204 No Content

$ curl -i -X DELETE http://127.0.0.1:8794/users/1     # ยิงซ้ำ
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Content-Length: 27

{"error":"user not found"}

ครั้งแรกไม่มี body ตามมาเลยเพราะ 204 แปลว่า "สำเร็จ แต่ไม่มีอะไรจะส่งกลับให้"
ตรงนี้ต้องแยกให้ชัด: idempotent พูดถึง "สภาพของข้อมูล" ไม่ใช่ "status ที่ตอบกลับ"
หลังยิงครั้งแรก user 1 หายไป · หลังยิงครั้งที่สอง user 1 ก็ยังหายไปอยู่ดี — สภาพสุดท้ายเหมือนกัน จึงถือว่า idempotent เต็มตัว ส่วน 404 เป็นแค่การรายงานว่า "ไม่มีอะไรให้ลบแล้วนะ"

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

อ้างอิง

• MDN — HTTP request methods — นิยามของ GET/POST/PUT/PATCH/DELETE พร้อมตารางว่าอันไหน safe / idempotent / cacheable
• RFC 9110 §9.3.4 — PUT — ประโยคต้นทางที่บอกว่า PUT คือการ replace ทั้ง representation
• RFC 5789 — PATCH Method for HTTP — เอกสารที่ตั้ง PATCH ขึ้นมาเพราะ PUT แก้บางส่วนไม่ได้
• RFC 9110 §9.2.2 — Idempotent Methods — นิยามที่พูดถึง "ผลต่อ server" ไม่ใช่ "status ที่ตอบกลับ"
• MDN — URI ประกอบด้วยอะไรบ้าง — แยก scheme / host / path / query ให้เห็นเป็นชิ้น ๆ
• Roy Fielding — REST (บทที่ 5 ของวิทยานิพนธ์ต้นฉบับ) — อ่านหัวข้อ 5.1.3 Stateless ถ้าอยากเห็นเหตุผลดั้งเดิมว่าทำไมถึงตัดความจำของ server ทิ้ง
• pkg.go.dev — net/http.ServeMux — pattern "GET /users/{id}" และ r.PathValue("id") ที่ใช้รันตัวอย่างทั้งบทนี้ (จะได้เขียนเองในบทถัดไปของ Day 8)