# 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](#ve-ho-tro-va-thoi-han) cuối trang.

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

1. **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.
2. **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.
3. **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`.
4. **Không phụ thuộc thứ tự trường** và không phụ thuộc độ dài mã định danh.
5. **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.
6. 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](/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`).