คุณจะกำหนดเวอร์ชัน API และรักษาความเข้ากันได้ของเวอร์ชันเก่าในบริการได้อย่างไร

Question

Accepted Answer

เนื่องจากบริการปรับใช้อย่างอิสระ คุณไม่สามารถสมมติว่าผู้เรียกอัปเกรดพร้อมกัน **API versioning** บวก **backward compatibility** ช่วยให้ผู้ผลิตสามารถพัฒนาได้โดยไม่ทำลายผู้บริโภคที่มีอยู่

## กลยุทธ์การกำหนดเวอร์ชัน

| กลยุทธ์ | ตัวอย่าง |
|---|---|
| URI path | `GET /v2/orders/42` |
| Header | `Accept: application/vnd.api.v2+json` |
| Schema evolution | เพิ่มฟิลด์ ห้ามลบ/เปลี่ยนชื่อ |

## ให้ความสำคัญกับการเปลี่ยนแปลงเพิ่มเติม (ไม่ทำลาย)

```text
NON-BREAKING (safe):
  ✓ add a new optional field
  ✓ add a new endpoint
  ✓ add a new enum value (if clients tolerate unknowns)

BREAKING (needs a new version):
  ✗ remove or rename a field
  ✗ change a type or make a field required
  ✗ change semantics of an existing field
```

## Protobuf ใจดีต่อสิ่งนี้

```proto
message Order {
  string id = 1;
  double total = 2;
  string currency = 3;  // NEW field 3 — old clients ignore it safely
}
```

หมายเลขฟิลด์ ไม่ใช่ชื่อ กำหนดรูปแบบ wire ดังนั้นการเพิ่มฟิลด์จึงเข้ากันได้ย้อนหลัง

## วงจรชีวิต

```text
Release v2 ─▶ run v1 + v2 together ─▶ migrate consumers ─▶ deprecate v1 ─▶ remove v1
```

## ข้อเสีย

ห้ามลบเวอร์ชันในขณะที่ไฟล์ข้อมูลจริงยังคงใช้อยู่ ติดตามการใช้งานก่อนการเกษียณ

## ทำไมมันถึงสำคัญ

การปรับใช้อย่างอิสระใช้ได้เฉพาะเมื่อผู้ผลิตสามารถส่งการเปลี่ยนแปลงได้โดยไม่ต้องประสานงานการปล่อยรุ่นของผู้บริโภคทั้งหมด

การออกแบบสำหรับการเปลี่ยนแปลงเพิ่มเติมและสนับสนุนเวอร์ชันเก่าระหว่างการย้ายถิ่นคือสิ่งที่รักษาความเป็นอิสระนั้นแทนที่จะบังคับให้ทำการอัปเกรด big-bang ที่ไม่มั่นคง

URI path	`GET /v2/orders/42`
Header	`Accept: application/vnd.api.v2+json`
Schema evolution	เพิ่มฟิลด์ ห้ามลบ/เปลี่ยนชื่อ