Các chiến lược versioning API chính là gì, và deprecate một version thế nào?

Question

IT Interview Practice · Accepted Answer

Versioning cho phép tiến hoá API với **breaking change** mà không làm hỏng client hiện có. Có ba chiến lược chủ đạo, cộng với một quy trình deprecation.

## Ba chiến lược

**1. URI versioning** — version nằm trong path.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Đơn giản và dễ thấy nhất; dễ route, cache và test ngay trên trình duyệt. Nhược điểm: về lý thuyết nó vi phạm "URI định danh một tài nguyên" (cùng một user giờ có hai URL). Đây là lựa chọn phổ biến nhất (GitHub, Stripe trước đây).

**2. Custom header versioning** — version đi trong header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Giữ URL sạch nhưng vô hình trên trình duyệt và khó cache hơn.

**3. Media-type (content negotiation) versioning** — version trong `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
"RESTful" nhất (URL tài nguyên ổn định; chỉ representation được version), nhưng khó tiếp cận nhất với người dùng.

## Thế nào là breaking

```text
BREAKING      → xoá/đổi tên field, đổi kiểu, đổi auth, siết validation
NON-BREAKING  → thêm field optional mới, thêm endpoint mới, thêm giá trị enum*
```
Chỉ breaking change mới cần version mới; thay đổi non-breaking thì thêm vào version hiện tại.

## Quy trình deprecation

1. **Thông báo** kèm ngày tháng trong docs và changelog.
2. **Phát tín hiệu lúc runtime** bằng header để client nhận biết tự động:
```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. **Theo dõi** lượng dùng version cũ và liên hệ những caller còn lại.
4. **Sunset** chỉ khi lượng dùng gần về 0.

## Tại sao điều này quan trọng

Người phỏng vấn hỏi câu này để xem bạn có thể phát triển API trong production mà không làm hỏng client phụ thuộc vào nó không — một mối lo vận hành thật, không phải lý thuyết. Câu trả lời mạnh nhất nêu hai phân biệt: thứ nhất, **đa số thay đổi là non-breaking** và không nên bump version (thay đổi bổ sung đi vào version hiện tại), chỉ dành versioning cho breaking change thực sự; thứ hai, *chiến lược* ít quan trọng hơn *quy trình* — một lộ trình deprecation rõ ràng với header `Deprecation`/`Sunset` và giám sát lượng dùng mới là thứ thực sự bảo vệ người dùng. URI versioning thắng trong thực tế nhờ dễ thấy và được tooling hỗ trợ, nhưng biết đánh đổi (header và media-type giữ URL ổn định và RESTful hơn, đổi lại khó khám phá) cho thấy bạn hiểu không gian thiết kế chứ không chỉ bắt chước `/v1/`.

Ba chiến lược

Thế nào là breaking

Quy trình deprecation

Tại sao điều này quan trọng

Câu hỏi liên quan