Quản lý phiên bản

Partner API được đánh phiên bản trong URL. Phiên bản hiện tại là:

https://partner-api.performancehub.co/partner/v1/

Chính sách thay đổi

Performance Hub hướng đến việc thực hiện các thay đổi bổ sung, tương thích ngược bất cứ khi nào có thể.

Ví dụ về các thay đổi tương thích ngược:

Thêm một trường không bắt buộc mới vào yêu cầu.
Thêm một trường mới vào phản hồi.
Thêm một endpoint mới.
Thêm một giá trị enum mới ở những nơi ứng dụng khách được kỳ vọng xử lý các giá trị không xác định.
Cải thiện thông báo kiểm tra dữ liệu mà không thay đổi cam kết về mã trạng thái.

access_time_windows và access_time_windows_revision là các trường bổ sung trong yêu cầu Member. Các ứng dụng khách hiện có bỏ qua các trường này sẽ giữ nguyên ảnh chụp nhanh Access Time Window đã lưu. Quy tắc bỏ qua này duy trì khả năng tương thích với upsert một phần; việc bỏ qua không tương đương với việc gửi một mảng rỗng.

Ví dụ về các thay đổi gây gián đoạn:

Xóa hoặc đổi tên một trường.
Thay đổi kiểu dữ liệu của một trường.
Chuyển một trường yêu cầu không bắt buộc thành bắt buộc.
Xóa một endpoint.
Thay đổi ý nghĩa của một mã trạng thái hiện có hoặc một reason theo lĩnh vực cụ thể.

Ngừng hỗ trợ

Khi cần thực hiện một thay đổi gây gián đoạn, Performance Hub sẽ tránh thay đổi trực tiếp phiên bản hiện có khi có thể. Thay vào đó, chúng tôi sẽ giới thiệu một phiên bản mới hoặc lộ trình chuyển đổi và thông báo thay đổi cho các đối tác bị ảnh hưởng.

Thông báo ngừng hỗ trợ có thể bao gồm:

Một mục trong nhật ký thay đổi.
Liên lạc trực tiếp với đối tác.
Ghi chú trong Partner Console.
Hướng dẫn chuyển đổi trong tài liệu.

Khuyến nghị cho ứng dụng khách

Xây dựng ứng dụng khách có khả năng chấp nhận các thay đổi bổ sung:

Bỏ qua các trường phản hồi mà bạn không sử dụng.
Coi các giá trị enum không xác định là không được hỗ trợ thay vì để ứng dụng gặp sự cố.
Tránh kiểm tra so khớp phản hồi một cách tuyệt đối.
Ghi nhật ký các giá trị không nhận dạng được để bạn có thể chủ động cập nhật tích hợp của mình.

Đối với các phân vùng Member có phiên bản như Access Time Windows, hãy lưu lại phiên bản đã gửi và payload đã chuẩn hóa cho đến khi biết kết quả. Dùng lại một phiên bản cho nội dung đã thay đổi là xung đột, còn phát lại cùng nội dung là idempotent. Xem Access Time Windows.

Đặc tả OpenAPI

Sử dụng các đặc tả OpenAPI đã công bố để tạo ứng dụng khách, kiểm tra yêu cầu và theo dõi các thay đổi về cấu trúc API theo thời gian.

Xem Đặc tả OpenAPI.