Phiên bản và khả năng tương thích

API có một phiên bản chính, /v1, và nó chỉ mở rộng thêm. Tích hợp viết hôm nay vẫn tiếp tục hoạt động khi tính năng mới ra đời: không có gì mà nó dựa vào bị đổi tên, bị xóa hoặc bị gán nghĩa mới.

Số phiên bản

API có số phiên bản dạng 1.62.0. Số này thay đổi theo mỗi bản phát hành:

• số phụ khi có thứ được thêm vào: một endpoint, một trường, một sự kiện;
• số bản vá khi một mô tả hoặc văn bản thông báo được sửa và không có gì khác thay đổi.

Bạn có thể đọc phiên bản mà một địa chỉ phục vụ vào bất cứ lúc nào:

GET /v1/health cũng có version, nhưng đó là phiên bản của bản phát hành Sursa phục vụ địa chỉ này, không phải phiên bản của API.

Bạn không chọn phiên bản phụ: mọi yêu cầu được phục vụ bởi phiên bản hiện tại. Nhờ các quy tắc dưới đây, điều đó an toàn.

Những gì có thể thay đổi trong /v1

Những thay đổi này có thể xuất hiện ở bất kỳ phiên bản phụ nào. Hãy viết tích hợp sao cho chúng không làm nó hỏng:

• Endpoint mới.
• Tham số và trường yêu cầu mới không bắt buộc. Yêu cầu không có chúng hoạt động như trước.
• Trường mới trong phản hồi, đối tượng và sự kiện.
• Giá trị mới của tập giá trị enum trong phản hồi, chẳng hạn trạng thái thẻ mới hoặc loại sự kiện mới.
• Mã lỗi mới và header phản hồi mới.
• Giới hạn được nới lỏng: độ dài tối đa lớn hơn, khoảng giá trị rộng hơn.
• Văn bản message của lỗi và mô tả được viết lại.

Những gì mã của bạn phải chấp nhận được

• Bỏ qua các trường bạn không biết. Đừng báo lỗi khi phản hồi có nhiều trường hơn bạn mong đợi, và đừng dùng lược đồ chặt chẽ từ chối chúng.
• Chấp nhận giá trị enum bạn không biết. Mọi tập giá trị trong phản hồi đều có thể mở rộng. Hãy coi giá trị không xác định là “khác” chứ không phải lỗi.
• Bỏ qua loại sự kiện bạn không biết, cả trong webhook lẫn trong luồng.
• Xử lý mã lỗi không xác định theo trạng thái HTTP: xem Lỗi.
• Đừng phụ thuộc vào thứ tự các trường trong đối tượng JSON hay vào văn bản chính xác của thông báo.

Những gì không bao giờ thay đổi trong /v1

• Đường dẫn, tham số, trường hay giá trị enum không bao giờ bị đổi tên hoặc bị xóa.
• Kiểu của trường không bao giờ thay đổi, và trường không bao giờ mang nghĩa mới, chẳng hạn đơn vị mới.
• Yêu cầu được chấp nhận hôm nay sẽ không bị từ chối sau này.
• Mã trạng thái của phản hồi thành công giữ nguyên.
• Mã lỗi giữ nguyên ý nghĩa, và trường detail của phản hồi lỗi giữ nguyên dạng.
• Loại sự kiện không bao giờ bị đổi tên hoặc bị xóa, và data của chúng chỉ có thêm trường.

Thay đổi phá vỡ tương thích

Nếu có lúc cần một thay đổi không tương thích, nó sẽ được phát hành dưới dạng phiên bản chính mới, chẳng hạn /v2, bên cạnh /v1. /v1 tiếp tục hoạt động không đổi, và hai phiên bản chạy song song.

Khi một endpoint sắp bị ngừng:

1. Nó được đánh dấu deprecated trong đặc tả và được ghi trong nhật ký thay đổi cùng ngày nó sẽ bị tắt.
2. Phản hồi của nó mang các header Deprecation: true và Sunset: <date>.
3. Nó tiếp tục hoạt động ít nhất 180 ngày sau thông báo. Các tổ chức có khóa API đang dùng nó được thông báo bằng văn bản trước ít nhất 90 ngày.
4. Sau ngày ngừng hoạt động, nó trả về 410 với mã api.gone trong 90 ngày tiếp theo.

Hãy theo dõi header Deprecation trong nhật ký hoặc hệ thống giám sát của bạn: đó là tín hiệu sớm nhất cho biết một endpoint bạn đang dùng sắp bị loại bỏ.

Luôn cập nhật thông tin

Nhật ký thay đổi của cổng này liệt kê mọi bản phát hành cùng những gì được thêm và những gì trở nên lỗi thời. Trước khi nâng cấp tích hợp của bạn, hãy so sánh mã của nó với các mục kể từ phiên bản mà bạn đã dùng để xây dựng nó.