Đánh số phiên bản API FedEx

Tại FedEx, chúng tôi đánh số phiên bản có ngữ nghĩa để quản lý các phiên bản API. Mỗi phiên bản được mô tả bằng định dạng phiên bản chính.phụ (ví dụ: API gửi hàng 1.1). Phiên bản chính mới cho thấy thay đổi không có tính tương thích ngược và phiên bản phụ mới cho thấy thay đổi có tính tương thích ngược.

Tại FedEx, chúng tôi thực hiện theo đánh số phiên bản URI đơn giản. Trong đó, chỉ có số phiên bản chính được thể hiện trong đường dẫn URI. Xin lưu ý rằng số phiên bản phụ không được đưa vào đường dẫn URI. Chiến lược này sử dụng định tuyến URI để xác định các phiên bản API cụ thể.

Ví dụ: /ship/v1/shipments

Nguyên tắc hướng dẫn chiến lược đánh số phiên bản

Chúng tôi dự định phát hành ít phiên bản chính hơn cho API FedEx và không chấp nhận một phiên bản chính sau hai năm kể từ khi phát hành phiên bản chính mới hơn. Ví dụ: Nếu phiên bản chính ‘N’ được phát hành, phiên bản ‘N-1’ sẽ được hỗ trợ trong hai năm kể từ khi phát hành phiên bản ‘N.’

Ví dụ: Năm 2020, phiên bản chính V1.0 được phát hành. Nếu phiên bản chính V2.0 được phát hành vào năm 2021 thì V1.0 sẽ không được chấp nhận vào năm 2023.

Các phiên bản phụ sẽ hỗ trợ hầu hết các chức năng và tính năng mới cập nhật.

Ví dụ: Sau phiên bản chính 1.0, các phiên bản phụ 1.1, 1.2, v.v sẽ được phát hành để triển khai cập nhật chức năng và tính năng mới.

Tại mọi thời điểm, tất cả các điểm cuối cho một API cụ thể sẽ có cùng một phiên bản chính. Phiên bản mới nhất của tài liệu sẽ chỉ có trên FedEx Developer Portal. Tuy nhiên, sẽ có một bản ghi thay đổi trong mỗi trang Tổng quan của API, trình bày chi tiết những thay đổi về phiên bản chính và phụ.

Khi nào các phiên bản chính của API được phát hành?

Chúng tôi đang cố gắng giảm thiểu số lượng phiên bản chính cho các API. Tuy nhiên, trong một số trường hợp, phát hành phiên bản chính là việc không thể tránh khỏi. Sau đây là một vài lý do chính dẫn đến việc cần phát hành phiên bản chính mới:

• Khi một giá trị liệt kê hiện có bị xóa hoặc định dạng hay chính giá trị trong yêu cầu hoặc phản hồi bị thay đổi
  

  Ví dụ: Giá trị liệt kê “GEOGRAPHIC_COORDINATES” cho phần tử locationSearchCriterion bị xóa trong phiên bản N; cú pháp ngày đổi từ YY-MM-DD thành MM-DD-YYYY; đổi loại địa điểm từ FEDEX_ONSITE thành ONSITE trong phản hồi

• Khi một phần tử hiện có bị xóa trong yêu cầu hay phản hồi
  

  Ví dụ: phần tử pickupType bị xóa (hoặc đổi tên) khỏi yêu cầu về giá cước trong phiên bản N

• Khi một phương thức hiện có bị xóa
  

  Ví dụ: Phương thức tạo và hủy thẻ FedEx Express không còn được hỗ trợ trong phiên bản N

• Khi một phần tử hiện có từng mang tính không bắt buộc hoặc có điều kiện trở thành mang tính bắt buộc trong yêu cầu
  

  Ví dụ: Mã số đặt gửi hàng hiện là phần tử bắt buộc đối với các lô hàng FedEx Express® Freight trong phiên bản N

• Khi có thay đổi về thiết kế API
  

  Ví dụ: Cấu trúc yêu cầu và phản hồi được sắp xếp lại

• Khi có thay đổi về mã lỗi và thông báo lỗi
  

  Ví dụ: Đổi mã lỗi từ INCORRECT.WEIGHT thành WEIGHT.LIMIT.EXCEEDED

Khi nào các phiên bản phụ của API được phát hành?

• Khi một giá trị liệt kê mới được thêm vào
  

  Ví dụ: Một dịch vụ vận chuyển mới được thêm vào phần tử serviceType trong phiên bản N

• Khi một phần tử mới được thêm vào
  

  Ví dụ: Một phần tử (không bắt buộc) mới để đưa số điện thoại của nhà môi giới vào lô hàng quốc tế

• Khi một phương thức mới được thêm vào
  

  Ví dụ: Phương thức sửa đổi tài liệu thương mại quốc tế sau khi tải lên được thêm vào phiên bản N.

• Khi một phần tử hiện có từng mang tính bắt buộc trở thành không bắt buộc
  

  Ví dụ: ID tài liệu giờ đây không mang tính bắt buộc vì FedEx có thể tìm ID tài liệu dựa trên thông tin người dùng.