Phiên bản & ngừng hỗ trợ
Phiên bản nằm ở đâu
Phần tiêu đề “Phiên bản nằm ở đâu”Phiên bản là một đoạn đường dẫn, và đó là nơi duy nhất nó xuất hiện:
https://api.zelnum.com/api/v1Chỉ có một phiên bản đang hoạt động. Định danh của nó trong tài liệu OpenAPI là 1.0.0; đoạn đường dẫn v1 là thứ bạn nhắm tới. Body phản hồi cố ý không lặp lại phiên bản, nên không có trường thứ hai cần đồng bộ.
Cách phân loại các thay đổi
Phần tiêu đề “Cách phân loại các thay đổi”| Loại | Ví dụ | Ảnh hưởng tới bạn |
|---|---|---|
| Bổ sung | Một endpoint mới, một trường yêu cầu tùy chọn mới, một trường phản hồi mới, một sản phẩm mới trong danh mục | Không. Không tăng phiên bản, không cần hành động. |
| Hành vi | Một giá trị mới trong một enum đã có như error_code hoặc billing_status; một giá trị mặc định bị thay đổi | Thường là không, nhưng nó có thể phá vỡ việc so khớp bao quát. |
| Phá vỡ | Xóa hoặc đổi tên một trường, thay đổi một kiểu, thay đổi ý nghĩa của một trạng thái, yêu cầu thêm một header mới | Đòi hỏi một phiên bản mới. |
| Hợp đồng | Tài liệu đã mô tả sai về điều API thực sự làm | Không — nhưng xem bên dưới. |
Khi tài liệu thay đổi
Phần tiêu đề “Khi tài liệu thay đổi”Tài liệu được sửa ngay tại chỗ khi hành vi của API bị mô tả sai. Đó là một thay đổi về tài liệu, không phải thay đổi hợp đồng: API không đổi, phần mô tả mới đổi. Vì một sửa đổi đúng là sự kiện bạn không thể thấy trong một mục changelog kiểu “không có gì thay đổi”, các sửa đổi được liệt kê rõ ràng trong changelog.
Nếu một sửa đổi thay đổi thứ mà bạn đã xây dựa vào, nó xuất hiện ở đó dưới dạng một ghi chú thay vì một chỉnh sửa âm thầm.
Chính sách ngừng hỗ trợ
Phần tiêu đề “Chính sách ngừng hỗ trợ”Khi một thao tác bị ngừng hỗ trợ, nó được đánh dấu deprecated: true trong tài liệu OpenAPI, và trang này ghi tài liệu cho phần thay thế. Thao tác vẫn hoạt động trong suốt thời gian thông báo, và thời gian thông báo được nêu rõ tại nơi công bố việc ngừng hỗ trợ.
Một lần ngừng hỗ trợ không bao giờ cùng bản phát hành với lần giới thiệu phần thay thế của nó. Cả hai cùng hoạt động, nên bạn có thể chuyển đổi theo lịch của riêng mình thay vì trong lúc có sự cố.
Lần ngừng hỗ trợ hiện tại duy nhất
Phần tiêu đề “Lần ngừng hỗ trợ hiện tại duy nhất”POST /v1/realtime/detect được giữ lại cho các client tiền phát hành và được đánh dấu ngừng hỗ trợ trong hợp đồng. Các tích hợp mới nên dùng những endpoint dành riêng cho từng chuỗi.
Đây là việc đổi tên, không phải thiết kế lại — body yêu cầu và phản hồi có cùng cấu trúc:
| Cũ | Hiện tại | |
|---|---|---|
| Endpoint | POST /v1/realtime/detect | POST /v1/realtime/check/phone hoặc POST /v1/realtime/check/email |
| Chuỗi | Được suy ra từ các sản phẩm bạn gửi | Được nêu rõ trong đường dẫn, và phải khớp với chúng |
| Trường products | products (bí danh) | product_ids |
Idempotency-Key | Bắt buộc | Bắt buộc |
Chuyển đổi chỉ là một thay đổi hai dòng:
# Beforecurl -X POST "https://api.zelnum.com/api/v1/realtime/detect" \ -H "X-API-Key: YOUR_KEY_HERE" \ -H "Idempotency-Key: UNIQUE_REQUEST_ID" \ -H "Content-Type: application/json" \ -d '{"identifier":"+8613800138000","products":[47]}'
# After — the series moves into the path and the field is renamedcurl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \ -H "X-API-Key: YOUR_KEY_HERE" \ -H "Idempotency-Key: UNIQUE_REQUEST_ID" \ -H "Content-Type: application/json" \ -d '{"identifier":"+8613800138000","product_ids":[47]}'Gửi đồng thời cả product_ids và products trong một request sẽ bị từ chối với 400 invalid_realtime_request, nên không được trộn hai thứ này trong một đợt triển khai theo giai đoạn.