Phiên bản

Phiên bản của API nằm trong đường dẫn: mọi endpoint hiện nay dưới /api/open/v1. Envelope sự kiện mang apiVersion: "v1" cho cùng ý nghĩa.

Thay đổi không phá vỡ

Những thay đổi sau có thể xảy ra mà không đổi phiên bản, nên client phải chịu được chúng:

thêm endpoint mới;
thêm trường mới vào phản hồi, vào data của sự kiện hay vào thân lỗi;
thêm tham số tuỳ chọn mới (query, header, trường thân);
thêm giá trị mới cho một danh sách giá trị (enum), ví dụ một trạng thái đơn mới hay một loại sự kiện mới;
thêm mã lỗi code mới;
đổi câu chữ của title và detail trong lỗi, thứ tự các trường JSON, độ dài của các mã định danh.

Thay đổi phá vỡ

Những thay đổi sau chỉ xảy ra ở một phiên bản mới (/v2), không bao giờ ở /v1:

bỏ hoặc đổi tên một trường, một endpoint hay một tham số;
đổi kiểu hay ý nghĩa của một trường;
thêm tham số bắt buộc;
bỏ một giá trị khỏi danh sách giá trị;
thêm luật kiểm tra mới làm một request đang hợp lệ thành không hợp lệ;
đổi cách xác thực.

Ngoại lệ trước ngày DANIX mở cho người dùng: v1 chưa đóng băng — xem mục Về hỗ trợ và thời hạn cuối trang.

Viết client chịu được thay đổi

Bỏ qua trường lạ. Parse JSON theo kiểu "lấy các trường mình cần", không từ chối khi gặp trường chưa biết.
Bỏ qua giá trị enum lạ. Gặp trạng thái hay loại sự kiện chưa biết thì lưu lại hoặc bỏ qua, đừng báo lỗi hay dừng cả tiến trình.
Rẽ nhánh theo code của lỗi, không theo title hay detail; coi code lạ như lỗi cùng nhóm status.
Không phụ thuộc thứ tự trường và không phụ thuộc độ dài mã định danh.
Giá trị tiền và số lượng là chuỗi thập phân: giữ nguyên dạng chuỗi hoặc dùng kiểu số thập phân chính xác, đừng ép sang số dấu phẩy động.
Thời gian luôn là ISO 8601 UTC.

Về hỗ trợ và thời hạn

Tài liệu này mô tả v1 hiện hành. DANIX chưa công bố cam kết về thời hạn hỗ trợ cho các phiên bản, và chưa phát tín hiệu báo ngừng hỗ trợ trong header phản hồi; khi có, thông tin sẽ được ghi ở trang này. Tệp openapi.json luôn là đặc tả của phiên bản đang chạy.

Trước ngày DANIX mở cho người dùng, v1 chưa đóng băng và có thể nhận thay đổi phá vỡ. Thay đổi đã có: POST /orders/{id}/status từ chối đưa một đơn đã rời new quay về new (order-status-not-allowed).