Custom Backend Module API Reference

Tài liệu này mô tả API HTTP public cho Custom Backend Module của Cogover, bao gồm quản lý Project (module) và version, identity policy, Project key, secret, inbound access, background job, Git repository, danh mục Custom Module Action, gọi module production, gọi inbound webhook và preview một version cụ thể.

Dùng HTTPS origin của Cogover Workspace đích làm base URL:

https://{WORKSPACE_DOMAIN}

WORKSPACE_DOMAIN là hostname đầy đủ của Workspace, bao gồm cả domain suffix. Không nối thêm suffix khác.

Chỉ các path, header, request field và response field public được mô tả tại đây thuộc contract tích hợp.

Xác thực và định tuyến

Xác thực bằng Workspace session

API quản lý module, quản lý Project key, gọi production và preview version dùng Cogover Workspace session đã xác thực:

Cookie: HttpSessionId=<session-id>; AuthToken=<workspace-auth-token>
X-Csrf-Token: <csrf-token>

Gửi thêm hai routing header: x-req-type: 9 cho mọi nhóm, và x-req-service theo nhóm API:

Nhóm API	Header	Quyền bắt buộc
Gọi production	`x-req-service: 3`	Người dùng Workspace đã xác thực; module phải có active version
Quản lý module, version, policy và key	`x-req-service: 4`	TypeScript Project SuperAdmin
Preview chính xác một version	`x-req-service: 6`	TypeScript Project SuperAdmin
Danh mục Custom Module Action	`x-req-service: 4`	Mọi thành viên đang hoạt động của Workspace

Thiếu x-req-type: 9 thì request service 4 bị Authorization Server xử lý như lệnh logout, trả {"data":{"deletedTokens":N}} và thu hồi phiên; service 3 trả {"msg":"Error","r":5000}; service 6 trả r: 5001 (Can not found processor for request: service=6).

Với x-req-type: 9, gateway của Workspace trả nguyên HTTP status, header và body của Runtime, không bọc envelope. Body request có thể gửi kèm Content-Encoding: gzip; khi gửi Accept-Encoding: gzip, response lớn có thể được nén gzip. Lỗi do chính gateway sinh ra, không phải của Runtime, ví dụ phiên hết hạn, Runtime không khả dụng hoặc hết thời gian chờ, có header response x-proxy-error: 1 và body {"r": <mã>, "msg": "<thông báo>"}.

Giá trị CSRF thường được cấp cùng phiên đăng nhập Cogover. Không đặt HttpSessionId, AuthToken hoặc CSRF token trong URL hay JSON body.

Quản lý secret, inbound access và job dùng cùng Workspace session và x-req-service: 4. Gọi inbound webhook thì khác: không dùng Workspace session lẫn routing header, chỉ dùng inbound credential mô tả ở Gọi inbound webhook.

Quy ước chung

Request và response body dùng JSON, trừ khi module được gọi trả về content type khác được hỗ trợ.
Tất cả route quản lý đều dùng POST, kể cả thao tác đọc hoặc xóa. Hai route danh mục Custom Module Action dùng GET và cũng nhận POST.
Path resource ID như projectId, versionId và keyId gồm 15 chữ cái in hoa hoặc chữ số.
Timestamp là Unix epoch millisecond.
API dùng tên field projectId cho module trong route quản lý và projectSlug cho module đã deploy trong route invocation.
Slug phải khớp [A-Za-z_][A-Za-z0-9_]{0,99} và không thể đổi sau khi tạo.
Idempotency-Key phải khớp [A-Za-z0-9][A-Za-z0-9._:-]{0,127}.
Nội dung thông báo do Cogover trả về luôn bằng tiếng Anh.

Lỗi có JSON shape sau, với Content-Type: application/json; charset=utf-8. Một số lỗi có thêm field chẩn đoán an toàn như code, reason, operation, objectSlug, fieldSlug, objectServerR hoặc writesMayHaveCompleted.

{
  "r": 400,
  "msg": "Invalid resource ID"
}

Các HTTP status thường gặp: 400 request không hợp lệ, 401 cần xác thực hoặc phiên hết hạn, 403 thiếu quyền, 404 không tìm thấy resource, 405 HTTP method không được hỗ trợ, 409 xung đột lifecycle hoặc idempotency, 413 request quá lớn, 422 script chạy thất bại, 429 vượt quota, 500 lỗi server không dự kiến và 502/503/504 lỗi dịch vụ tạm thời. Lỗi server không dự kiến trả { "r": 500, "msg": "Internal server error" }, không kèm chi tiết. Path quản lý không khớp route nào, ví dụ /api/v1/ts-projects/{projectId}/secrets/unknown/update, trả 404 với msg: "TypeScript project management route not found".