API
Bảng dưới liệt kê các đường dẫn chính dưới /api/v1; đặc tả đầy đủ ở OpenAPI (/v3/api-docs) của backend đang chạy; backend không kèm giao diện thử gọi, đưa đặc tả vào công cụ của bạn (Postman, Insomnia hay trình sinh mã).
Mọi phản hồi bọc trong ApiResponse, và lỗi có errorCode ổn định.
Script e2e/api/check_docs.py kiểm mọi đường dẫn nêu ở đây có trong OpenAPI.
| Đường dẫn | Việc |
|---|---|
POST /api/v1/models/plan, /apply | Xem trước và áp dụng tệp mô hình (ADMIN) |
POST /api/v1/models/upgrade | Chạy tuần tự các migration đến format hiện hành và trả nội dung để xem trước, không lưu tệp (ADMIN) |
POST /api/v1/models/{model}/rollback/plan, /rollback | Xem trước và quay về phiên bản trước (ADMIN) |
POST /api/v1/models/{model}/resume, /abandon | Hoàn tất hoặc hủy bỏ lần áp dụng đã dừng giữa chừng (ADMIN) |
GET /api/v1/models, /models/{model}/runs | Mô hình đã áp dụng và lịch sử từng bước (ADMIN) |
GET /api/v1/models/schema, /families, /templates, /{model}/versions | Đặc tả tệp mô hình, họ mẫu kèm trạng thái và hành động, thư viện mẫu và các phiên bản đã áp dụng, cho bảng điều khiển (ADMIN) |
GET /api/v1/models/{model}/data-lineage | Phả hệ của từng trường của một mô hình đang chạy, dựng lúc gọi từ chính mô hình, kèm phiên bản đang chạy: origins (vai được ghi, mặc định, thực thể tham chiếu, đơn vị, tệp, mã sinh khi tạo hồ sơ, tên cũ), uses (quy tắc đọc trường: required_when, require và when của hành động, chủ sở hữu, phạm vi đơn vị) và destinations (lịch sử, dòng sự kiện, webhook, lưu trữ); không có bước biến đổi vì lõi giữ nguyên giá trị (ADMIN) |
GET /api/v1/models/{model}/data-catalog | Danh mục dữ liệu của một mô hình đang chạy, dựng lúc gọi từ chính mô hình: nơi dữ liệu đi vào (vai và ứng dụng ngoài đã đăng ký), nơi đi ra (webhook, hành động hoàn tất, dòng sự kiện, lưu trữ), liên kết tham chiếu và chủ sở hữu giữa các thực thể, và mỗi thực thể có số bản ghi, quyền theo vai và danh sách trường (ADMIN) |
POST /api/v1/models/diagram | Sơ đồ quy trình của một tệp mô hình: trạng thái, hành động (kèm vai riêng và trường bắt buộc), vai xử lý, hạn, các mức leo thang, hành động tự đóng và hành động after; tệp sai thì valid: false kèm dòng và cột (ADMIN) |
GET /api/v1/meta/models | Metadata mà người gọi được xem; mô hình đang bị giữ hiện với held và không có thực thể; mỗi trường có thêm multiple, min, max, pattern và requiredWhen ({field, op, value}) khi tệp mô hình khai báo, và mỗi thực thể có ui (icon, menu, list, form, hints) khi khai báo |
GET /api/v1/meta/models/{model}/openapi | Tài liệu OpenAPI của một mô hình đang chạy, sinh lúc gọi từ chính mô hình nên đổi theo mỗi lần áp dụng và quay về: các đường của API dữ liệu cho từng thực thể mà người gọi chạm tới (ADMIN thấy hết), trường kèm kiểu, bắt buộc và lựa chọn, hành động của quy trình, mã lỗi; trả chính tài liệu, không bọc khung ApiResponse, để trình sinh client hoặc công cụ API đọc được từ địa chỉ này; 404 khi mô hình không có hoặc người gọi không chạm tới thực thể nào |
/api/v1/data/{model}/{entity} | Danh sách, tạo, xem, sửa, xóa; lọc filter.<trường>[.<phép>] (trường boolean chỉ so bằng, trường date so bằng và gte, lte, trường nhiều lựa chọn chỉ nhận contains), sort, order, page, size; giá trị boolean là true hoặc false, date là YYYY-MM-DD, trường nhiều lựa chọn là mảng chuỗi; sửa nhận version đã đọc, hồ sơ đã đổi thì 409 ERR_CONCURRENT_MODIFICATION; 403 ERR_ACTION_NOT_ALLOWED và 409 ERR_INVALID_STATE có data.reason; tạo hồ sơ và hành động nhận header Idempotency-Key (1 đến 128 ký tự A-Za-z0-9._:-): gửi lại cùng khóa và cùng nội dung thì trả lại câu trả lời lần đầu kèm header Idempotent-Replayed: true mà không làm lại, cùng khóa với yêu cầu khác (nội dung hay đích khác) là 409 với data.reason IDEMPOTENCY_KEY_REUSED, khóa sai khuôn là 400, và yêu cầu bị từ chối không giữ khóa; khóa thuộc về người gửi và giữ 24 giờ |
GET /api/v1/data/{model}/{entity}/stats | Đếm trên các dòng người gọi được xem, nhận cùng bộ lọc filter.* như danh sách: total; với thực thể có quy trình thêm byStatus (số hồ sơ mỗi trạng thái) và overdue (hồ sơ có hạn xử lý trước computedAt), avgDecisionSeconds (giây trung bình từ lúc tạo đến trạng thái cuối), avgOpenAgeSeconds và oldestOpenAgeSeconds (tuổi trung bình và lớn nhất của hồ sơ chưa vào trạng thái cuối, tính đến computedAt), ba số sau là null khi không có hồ sơ nào để tính; với thực thể khai hạn xử lý thêm closedOnTime và closedLate, số hồ sơ đã đóng (không tính hồ sơ rút lại) chưa từng quá hạn và đã từng quá hạn, đếm từ các dòng lịch sử overdue; một hồ sơ từng quá hạn rồi xong đúng hạn ở hạn mới vẫn tính là đã từng quá hạn; với thực thể có trường unit thêm byUnit; truy vấn bị cắt sau 10 giây |
GET /api/v1/data/{model}/{entity}/report | Nhóm các dòng người gọi được xem theo một trường rồi tính số liệu, nhận cùng bộ lọc filter.* như danh sách. groupBy là một trường lựa chọn, đơn vị hoặc đúng/sai (không phải trường nhiều giá trị), status với thực thể có quy trình, hoặc một trường ngày và created_at theo tháng dạng trường:month (tháng tính theo UTC); metrics là danh sách ngăn bởi dấu phẩy gồm count (mặc định), sum(trường), avg(trường), min(trường), max(trường) trên trường số, tối đa 6; limit là số nhóm, mặc định 50 và tối đa 200. Mỗi nhóm có key (null cho các dòng không có giá trị) và một giá trị cho mỗi phép tính, xếp theo key; totals là cùng các phép tính trên mọi dòng; truncated là true khi còn nhóm chưa trả. sum, avg, min, max bỏ qua giá trị rỗng và là null khi nhóm không có giá trị nào, count đếm dòng, và avg làm tròn bốn chữ số thập phân. Không có groupBy thì chỉ có totals. Trường hoặc phép tính mô hình không cho phép là 400, không phần nào của yêu cầu thành SQL; truy vấn bị cắt sau 10 giây |
GET /api/v1/data/{model}/{entity}/quality | Số đo chất lượng của các dòng người gọi được xem (ADMIN: mọi dòng của thực thể, và chỉ nhận số đếm), nhận cùng bộ lọc filter.* như danh sách và staleDays (1 đến 3650, mặc định 90): measuredAt, sampleSize và metrics; completeness cho mỗi trường số bản ghi có giá trị (filled), missing và rate, trong đó chuỗi rỗng và danh sách rỗng tính là thiếu và rate là null khi sampleSize là 0; requiredWhen cho mỗi trường khai required_when số bản ghi thỏa điều kiện (applicable) và số bản ghi trong đó còn trống (missing); constraints cho mỗi trường có lựa chọn, min, max hoặc pattern số giá trị đang lưu vi phạm (violating); freshness cho thời điểm đổi cũ nhất và mới nhất và số bản ghi không đổi quá staleDays ngày, không tính hồ sơ đã vào trạng thái cuối; vai không chạm thực thể và không phải ADMIN thì 403; truy vấn bị cắt sau 10 giây |
POST /api/v1/data/{model}/{entity}/{id}/actions/{action} | Hành động của quy trình; metadata liệt kê các vai xử lý (handlers), hành động kèm roles, require và when ({field, op, value}, op là ==, !=, <, <=, > hoặc >=, value là số với trường number; null khi không có điều kiện), trạng thái đầu và người được làm; metadata của thực thể có handlerActions, tên các hành động mà vai của người gọi được thực hiện, để client chỉ hiện nút hợp lệ |
POST .../{id}/assign, GET .../{id}/handlers | Giao việc và danh sách người giao được |
GET .../{id}/events | Dòng lịch sử của bản ghi; detail của dòng updated là JSON {"trường": ["cũ", "mới"]} với giá trị dạng chuỗi hoặc null, cắt ở 200 ký tự |
.../{id}/files | Tải lên, liệt kê, lấy link tải có hạn (/{fileId}/link) và gỡ tệp đính kèm |
GET .../{id}/documents, GET .../{id}/documents/{tên} | Các mẫu in của hồ sơ và việc in được ở trạng thái hiện tại; tệp PDF của một mẫu, cho người đọc được hồ sơ (409 DOCUMENT_NOT_AVAILABLE khi trạng thái không cho in) |
GET /api/v1/inbox | Hồ sơ đang chờ người gọi, trên mọi mô hình; page, size |
GET /api/v1/inbox/stream | Kênh sự kiện text/event-stream cho người đã đăng nhập: sau khi một dòng lịch sử hồ sơ ghi xong ở bất kỳ mô hình nào, kênh gửi khung event: changed với dữ liệu {}, không kèm nội dung và giống nhau với mọi người, để client đọc lại hộp việc; dòng chú thích : ping mỗi 20 giây; server đóng kênh sau 10 phút nên client nối lại với token mới; một người giữ tối đa 8 kênh và mở thêm thì kênh cũ nhất bị đóng; 503 khi server đã giữ hết số kênh phục vụ được; kênh nằm trong bộ giới hạn 300 lượt mở mỗi phút mỗi người |
GET /api/v1/events | Dòng lịch sử theo đúng dạng của webhook, từ sau một eventId (after, size, model) (ADMIN) |
GET /api/v1/events/admin | Việc áp dụng, quay về, tiếp tục, hủy bỏ mô hình và thay đổi tài khoản theo đúng dạng thông điệp admin.event, từ sau một eventId (after, size, model); eventId đếm riêng, không cùng dãy với /events; dòng được ghi dù có đích webhook hay không (ADMIN) |
GET /api/v1/outbox, POST /api/v1/outbox/{id}/retry | Thông điệp gửi đi theo trạng thái (lỗi, chờ gửi, đã gửi) và thử lại thông điệp chưa gửi (ADMIN) |
GET /api/v1/people | Tìm người cho trường user, chỉ trả id và tên hiển thị: q tìm tối đa 20 tài khoản theo tên, tên đăng nhập hoặc email (ít hơn 2 ký tự thì trả danh sách rỗng), ids là tối đa 50 id cách nhau bởi dấu phẩy và trả những tài khoản có thật; người đã đăng nhập nào cũng gọi được |
GET /api/v1/clients, POST /api/v1/clients, PUT /api/v1/clients/{name}, POST /api/v1/clients/{name}/secret, DELETE /api/v1/clients/{name} | Ứng dụng ngoài: danh sách, đăng ký (name, model, role), đổi sang vai khác của cùng mô hình (role, giữ nguyên mã bí mật), cấp mã bí mật mới và xóa (ADMIN); đăng ký tạo client dxos-app-{name} giữ đúng một vai của một mô hình, và mã bí mật chỉ nằm trong câu trả lời của đăng ký và đổi mã, kèm Cache-Control: no-store |
GET /api/v1/users, /users/options, /users/{id} | Tìm và xem người dùng, vai theo từng mô hình và đơn vị; vai và đơn vị có thể gán (ADMIN) |
PUT, DELETE /api/v1/users/{id}/roles/{model}/{role}, /units/{unit} | Gán và gỡ vai của một mô hình, và đơn vị (ADMIN) |
POST /api/v1/users, PUT /{id}/enabled, POST /{id}/password | Tạo người dùng với mật khẩu tạm, khóa và mở, đặt lại mật khẩu (ADMIN) |
GET /api/v1/audit-logs | Nhật ký lần truy cập bị từ chối, lỗi, thay đổi về tài khoản và việc áp dụng mô hình; lọc theo actor, action, targetType, targetId, outcome, from, to (ADMIN) |