# API bị khai tử vẫn chạy tiếp, và đó mới là cái bẫy

> Muốn chuyển khách từ v1 sang v2 mà đơn hàng không dừng, cần lớp adapter, chạy song song hai phiên bản và soát kỹ logic ghi, nơi lỗi hiện ra thành dữ liệu sai.

Bản gốc: https://fdetimes.net/vi/bach-khoa/khach-ngung-api-v1-chuyen-tich-hop-sang-v2/

Thử hình dung một sáng thứ Hai ở công ty khách. Trưởng nhóm vận hành chuyển tiếp cho bạn email của một nhà cung cấp phần mềm: API v1 sẽ ngừng hỗ trợ vào một ngày cụ thể, kèm đường link hướng dẫn migration. Dòng cuối của email là của khách: "Việc này em lo được không? Không được để đơn hàng bị dừng."

Cái khó là không ai cho bạn dừng hệ thống để chuyển. Đơn hàng vẫn chạy, đồng bộ vẫn chạy, và mỗi lỗi lúc chuyển sẽ hiện ra dưới dạng dữ liệu sai chứ không phải một exception rõ ràng.

Có một cách làm áp dụng được ngay: phát hiện sớm, bọc lời gọi trong một lớp adapter, chạy song song hai phiên bản, chuyển dần, và kiểm tra lại đúng những chỗ hay hỏng.

## Ngày khai tử không phải hạn chót an toàn

Phản xạ đầu tiên của nhiều kỹ sư là ghi ngày tắt vào lịch rồi lùi lại vài tuần trước đó. Thông báo khai tử v1 của Webflow cho thấy vì sao cách nghĩ này nguy hiểm: sau ngày đó v1 có thể vẫn hoạt động, nhưng sẽ không còn được bảo trì, cập nhật hay hỗ trợ.

**Điểm mấu chốt:** Một API bị khai tử vẫn có thể chạy tiếp, và đó chính là cái bẫy.

Một API "vẫn chạy" nhưng không ai chịu trách nhiệm là kiểu rủi ro tệ nhất. Nó hỏng vào lúc bất kỳ, và khi hỏng bạn không có ai để mở ticket. Webflow vì thế khuyên khách bắt đầu migration càng sớm càng tốt để tích hợp không bị gián đoạn.

Cũng nên hiểu vì sao nhà cung cấp làm vậy.

Nhưng chính Stripe thừa nhận tương thích ngược không miễn phí, vì mỗi phiên bản mới là thêm code phải hiểu và bảo trì. Không phải nhà cung cấp nào cũng sẵn lòng gánh chi phí đó lâu dài, nên ngày tắt là chuyện nên tính trước.

## Để hệ thống tự báo trước khi email đến

Email dễ bị lọt. Header HTTP thì không. RFC 9745 định nghĩa header `Deprecation` để báo cho bên gọi rằng một tài nguyên sẽ bị hoặc đã bị khai tử. Nếu nhà cung cấp gửi thêm header `Sunset`, mốc thời gian của nó không được sớm hơn mốc trong `Deprecation`, tức là thông báo khai tử luôn đi trước ngày tắt.

RFC này còn cho phép trỏ tới tài liệu hướng dẫn qua header `Link` với quan hệ `deprecation`. Không phải nhà cung cấp nào cũng gửi các header này, nhưng ghi log chúng gần như không tốn gì. Đặt đoạn này vào HTTP client dùng chung ở khách:

```python
import logging
import requests

log = logging.getLogger("vendor_api")
BASE = "https://api.vendor.example"

def call(method, path, **kw):
    resp = requests.request(method, BASE + path, timeout=10, **kw)
    if "Deprecation" in resp.headers or "Sunset" in resp.headers:
        log.warning(
            "deprecated endpoint %s %s deprecation=%s sunset=%s link=%s",
            method, path,
            resp.headers.get("Deprecation"),
            resp.headers.get("Sunset"),
            resp.headers.get("Link"),
        )
    return resp
```

Sau một tuần, log cho bạn danh sách endpoint thật sự đang bị gọi và đã được đánh dấu khai tử. Danh sách này đáng tin hơn mọi bản kiểm kê làm bằng tay, vì nó đến từ lưu lượng production.

## Ví dụ: đồng bộ trạng thái đơn hàng

Giả sử khách có một service cập nhật trạng thái đơn hàng sang hệ thống của nhà cung cấp. Ở v1, cách duy nhất là đọc cả bản ghi, sửa một trường rồi ghi đè lại cả bản ghi. Tài liệu v2 nói rõ, giống hướng dẫn chuyển đổi của Chainguard: thay logic fetch-modify-write bằng một lời gọi PATCH chỉ đặt những trường cần đổi.

Chi tiết này quan trọng hơn việc đổi `/v1/` thành `/v2/`, vì nó chạm vào logic ghi, tức mọi chỗ trong code gửi dữ liệu lên để tạo hoặc sửa bản ghi.

Với fetch-modify-write, nếu hai tiến trình cùng sửa một bản ghi, lần ghi sau có thể đè mất thay đổi của lần ghi trước. Khi chuyển sang PATCH, cách ghi thay đổi, và mọi chỗ trong code từng ngầm dựa vào việc "ghi lại cả bản ghi" đều phải được rà lại.

Vì thế bước đầu tiên là gom mọi lời gọi vào một adapter duy nhất, rồi quyết định dùng phiên bản nào ở đúng một chỗ:

```python
import zlib

V2_ROLLOUT_PERCENT = 5  # tăng dần: 5 -> 25 -> 50 -> 100

class VendorError(Exception):
    @classmethod
    def from_v2(cls, resp):
        # v2 trả lỗi theo định dạng mới: tách mã lỗi, thông điệp theo tài liệu v2
        return cls(f"{resp.status_code}: {resp.text}")

def use_v2(order_id: str) -> bool:
    return zlib.crc32(order_id.encode()) % 100 < V2_ROLLOUT_PERCENT

class OrderStatusClient:
    def update_status(self, order_id, status):
        if use_v2(order_id):
            return self._v2_patch(order_id, status)
        return self._v1_fetch_modify_write(order_id, status)

    def _v1_fetch_modify_write(self, order_id, status):
        item = call("GET", f"/v1/items/{order_id}").json()
        item["status"] = status
        return call("PUT", f"/v1/items/{order_id}", json=item)

    def _v2_patch(self, order_id, status):
        resp = call("PATCH", f"/v2/items/{order_id}", json={"status": status})
        if resp.status_code >= 400:
            raise VendorError.from_v2(resp)
        return resp
```

Băm theo `order_id` giúp một đơn hàng luôn đi cùng một phiên bản, nên bạn không bị trộn hai kiểu ghi trên cùng bản ghi. Cách này chỉ khả thi khi nhà cung cấp chạy hai phiên bản song song. Chainguard là ví dụ: v1 và v2 cùng hoạt động, khách có thể chuyển dần từng phần, và lúc ra mắt chưa đặt ngày tắt.

Một số nhà cung cấp còn cho làm mịn hơn. Stripe gắn mỗi tài khoản với một phiên bản nhưng cho phép ghi đè phiên bản trên từng request bằng header `Stripe-Version`.

Nghĩa là bạn có thể thử phiên bản mới trên một lời gọi duy nhất trước khi chuyển toàn bộ. Nếu API bạn đang tích hợp có cơ chế tương tự, hãy dùng nó cho giai đoạn 5% đầu tiên.

## Chỗ hỏng thật nằm ở nhánh lỗi

Happy path thường chạy ngay lần đầu, và đó là lý do nhiều đội tuyên bố xong quá sớm. Hướng dẫn của Chainguard cảnh báo đúng điểm này: v2 đổi định dạng lỗi và mã trạng thái, nên phải kiểm tra lại các nhánh xử lý lỗi chứ không chỉ happy path.

Thử nghĩ tới code retry của khách. Nếu nó đang so khớp một chuỗi trong body lỗi của v1 để quyết định có thử lại hay không, sang v2 chuỗi đó biến mất. Kết quả: lỗi tạm thời không được thử lại, hoặc lỗi vĩnh viễn bị thử lại mãi. Không có gì sập, chỉ có đơn hàng lặng lẽ nằm sai trạng thái.

## Trình tự làm ở công ty khách

Bắt đầu bằng log header trong một tuần để có danh sách endpoint thật. Tiếp theo, đọc hướng dẫn migration và đánh dấu từng thay đổi về hành vi, nhất là cách ghi và cách trả lỗi, vì đó là phần cần viết lại chứ không chỉ đổi đường dẫn.

Sau đó dựng adapter, viết test cho cả hai nhánh, rồi bật v2 ở 5%. Theo dõi tỷ lệ lỗi và so sánh dữ liệu giữa hai nhóm đơn hàng trước khi tăng lên. Chỉ xoá code v1 khi v2 đã chạy 100% đủ lâu để đi qua cả những tác vụ chạy theo tuần hay theo tháng.

Song song, viết cho khách một trang ngắn: những gì thay đổi, tỷ lệ chuyển hiện tại, cách quay lại v1 nếu có sự cố. Người vận hành không cần đọc code, nhưng cần biết ai bấm nút lùi và lúc nào.

## Những lỗi hay gặp

Lỗi phổ biến nhất là coi ngày khai tử là ngày tắt và đợi đến sát ngày. Lỗi thứ hai là để lời gọi API rải khắp codebase, khiến không thể chuyển dần mà buộc phải đổi tất cả cùng lúc. Lỗi thứ ba là chỉ test happy path, như đã thấy ở trên.

Lỗi ít được nói tới hơn là quên các script phụ: cron job, notebook phân tích, công cụ nội bộ ai đó viết hai năm trước. Chúng không đi qua adapter của bạn, nên nếu khách có proxy hoặc gateway chung, hãy ghi log header khai tử ở cả tầng đó để không bỏ sót.

Khi kể lại cuộc migration này trong CV hay phỏng vấn, một dòng như "chuyển tích hợp X từ v1 sang v2 theo từng phần lưu lượng, không gián đoạn, viết lại logic ghi sang PATCH" nói nhiều hơn một danh sách công nghệ, nhất là khi bạn kể tiếp được nhánh lỗi mình đã bắt được.

Email khai tử sẽ còn đến, từ nhà cung cấp này hay nhà cung cấp khác. Nếu adapter và log header đã có sẵn, lần sau bạn chỉ cần sửa một file, và khách sẽ không bao giờ biết đã có chuyện gì xảy ra.

**Thử ngay tuần này:**

- Thêm vào HTTP client đang dùng ở khách một dòng log cảnh báo khi response có header Deprecation hoặc Sunset, rồi xem sau 7 ngày endpoint nào hiện ra.
- Liệt kê mọi chỗ trong codebase đang đọc toàn bộ một bản ghi rồi ghi đè lại cả bản ghi, và đánh dấu những chỗ sẽ cần đổi khi API mới hỗ trợ PATCH.
- Viết ba test cho nhánh lỗi (400, 404, 429) của một tích hợp bạn phụ trách và chạy chúng trên cả hai phiên bản API.

## Nguồn

- [RFC 9745: The Deprecation HTTP Response Header Field](https://www.rfc-editor.org/rfc/rfc9745.html)

- [APIs as infrastructure: future-proofing Stripe with versioning](https://stripe.com/blog/api-versioning)

- [Webflow v1 API Deprecation Notice](https://developers.webflow.com/data/v1.0.0/docs/webflow-v1-api-deprecation-notice)

- [Migrating from API v1 to API v2](https://www.chainguard.dev/docs/platform/api/api-v2-migration/index.md)
