กลยุทธ์การทำ versioning ของ API หลัก ๆ มีอะไรบ้าง และคุณ deprecate เวอร์ชันหนึ่งอย่างไร?

Question

IT Interview Practice · Accepted Answer

Versioning ช่วยให้คุณวิวัฒน์ API ด้วย **breaking change** โดยไม่ทำให้ client เดิมพัง มีสามกลยุทธ์กระแสหลัก บวกกับกระบวนการ deprecation

## สามกลยุทธ์

**1. URI versioning** — เวอร์ชันอยู่ใน path
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
ง่ายที่สุดและมองเห็นชัดที่สุด route, cache, และทดสอบในเบราว์เซอร์ได้ง่าย ข้อเสีย: ในทางเทคนิคมันละเมิดหลัก "URI ระบุทรัพยากรหนึ่งอัน" (user คนเดิมกลับมีสอง URL) นี่เป็นตัวเลือกที่พบบ่อยที่สุดโดยห่างชั้น (GitHub, Stripe ในอดีต)

**2. Custom header versioning** — เวอร์ชันเดินทางไปใน header
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
รักษา URL ให้สะอาด แต่มองไม่เห็นในเบราว์เซอร์และ cache ยากกว่า

**3. Media-type (content negotiation) versioning** — เวอร์ชันอยู่ใน `Accept`
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
"RESTful" ที่สุด (URL ของทรัพยากรคงที่ มีเพียง representation ที่ถูก version) แต่เข้าถึงยากที่สุดสำหรับผู้ใช้

## อะไรนับเป็น breaking

```text
BREAKING      → remove/rename a field, change a type, change auth, tighten validation
NON-BREAKING  → add a new optional field, add a new endpoint, add an enum value*
```
เฉพาะ breaking change เท่านั้นที่ต้องมีเวอร์ชันใหม่ ส่วนการเปลี่ยนแบบ non-breaking ให้เพิ่มเข้าในเวอร์ชันปัจจุบัน

## กระบวนการ deprecation

1. **ประกาศ** พร้อมวันที่ในเอกสารและ changelog
2. **ส่งสัญญาณตอน runtime** ด้วย header เพื่อให้ client สังเกตเห็นแบบอัตโนมัติ:
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. **เฝ้าดู** การใช้งานเวอร์ชันเก่าและติดต่อ caller ที่ยังเหลือ
4. **Sunset** เฉพาะเมื่อการใช้งานลดลงใกล้ศูนย์

## ทำไมจึงสำคัญ

ผู้สัมภาษณ์ถามข้อนี้เพื่อดูว่าคุณเติบโต API ใน production ได้โดยไม่ทำ client ที่พึ่งพามันพังหรือไม่ — เป็นความกังวลเชิงปฏิบัติการจริง ไม่ใช่เชิงทฤษฎี คำตอบที่แข็งแรงที่สุดจะแยกสองประเด็น: หนึ่ง **การเปลี่ยนแปลงส่วนใหญ่เป็น non-breaking** และไม่ควรกระตุ้นการ bump เวอร์ชันเลย (การเปลี่ยนแบบเพิ่มเติมเข้าไปในเวอร์ชันปัจจุบัน) โดยสงวน versioning ไว้ให้ breaking change ที่แท้จริง; และสอง *กลยุทธ์* สำคัญน้อยกว่า *กระบวนการ* — ไทม์ไลน์ deprecation ที่ชัดเจนพร้อม header `Deprecation`/`Sunset` และการเฝ้าดูการใช้งาน คือสิ่งที่ปกป้องผู้ใช้จริง ๆ URI versioning ชนะในทางปฏิบัติเพราะมองเห็นชัดและมีเครื่องมือรองรับ แต่การรู้การแลกเปลี่ยน (header และ media-type รักษา URL ให้คงที่และ RESTful กว่า แลกกับความยากในการค้นพบ) แสดงว่าคุณเข้าใจพื้นที่การออกแบบ ไม่ใช่แค่ลอกเลียน `/v1/`

สามกลยุทธ์

อะไรนับเป็น breaking

กระบวนการ deprecation

ทำไมจึงสำคัญ

คำถามที่เกี่ยวข้อง