Quy ước API

Mọi API trong hệ sinh thái xAI tuân theo cùng một bộ quy ước, giúp bạn học một lần và áp dụng cho mọi sản phẩm.

Base URL & phiên bản

Mỗi sản phẩm có base URL riêng theo subdomain:

https://identity.xai.io.vn
https://governance.xai.io.vn
https://blockchain.xai.io.vn

Định dạng

Tất cả qua HTTPS.
Body & phản hồi mặc định là JSON (Content-Type: application/json). Một số endpoint đăng nhập nhận form (multipart/form-data).
Thời gian dạng ISO 8601 hoặc Unix epoch (giây) tùy endpoint — ghi rõ trong reference.

Lỗi

API dùng mã trạng thái HTTP chuẩn. Thân lỗi có dạng:

{ "error": "invalid_credentials" }

Mã	Ý nghĩa
`400`	Yêu cầu không hợp lệ / thiếu trường
`401`	Chưa xác thực (thiếu/hết hạn phiên)
`403`	Không đủ quyền (RBAC)
`404`	Không tìm thấy tài nguyên
`409`	Xung đột (vd dữ liệu đã tồn tại)
`429`	Vượt giới hạn tần suất

Giới hạn tần suất

Một số endpoint (vd relayer blockchain) áp giới hạn ~5 yêu cầu/phút/IP. Khi vượt, API trả 429 kèm header Retry-After (giây):

HTTP/1.1 429 Too Many Requests
Retry-After: 12

CORS

Endpoint introspection cho phép CORS với mọi *.xai.io.vn và localhost (kèm credentials). Endpoint xác minh công khai (vd /api/did/verify, /api/verify) cho phép mọi origin.

Tính bất biến (idempotency)

Các thao tác niêm phong dữ liệu là idempotent theo dấu vân tay: gửi lại cùng dữ liệu sẽ trả 409 (đã niêm phong) thay vì tạo bản ghi trùng.