Đặc tả API

Shell API cung cấp một giao diện thống nhất cho quản lý định danh, khám phá dịch vụ và điều phối nền tảng. Hệ thống công khai cả các endpoint REST (OpenAPI) và gRPC (Connect RPC).

1. REST API (Công khai & Quản trị)

REST API tuân thủ các mã trạng thái HTTP tiêu chuẩn và trả về cấu trúc JSON nhất quán: { code, data, messageError? }.

Xác thực & Định danh

Endpoint	Phương thức	Mô tả
/auth/login	GET	Lấy URL ủy quyền OIDC.
/auth/callback	GET	Xử lý callback OIDC và cấp Shell JWT.
/auth/refresh	POST	Làm mới Shell JWT bằng Refresh Token.
/auth/logout	POST	Đưa token vào danh sách đen và kết thúc phiên.
/auth/me	GET	Lấy thông tin hồ sơ và tổ chức của người dùng hiện tại.

Danh mục Ứng dụng (Khám phá)

Endpoint	Phương thức	Mô tả
/config/apps	GET	Công khai: Liệt kê các ứng dụng vệ tinh có sẵn.
/admin/apps	GET	Quản trị: Liệt kê ứng dụng kèm metadata chi tiết.
/admin/apps	POST	Quản trị: Đăng ký một ứng dụng vệ tinh mới.

---

2. gRPC / Connect RPC

Đối với giao tiếp giữa các service (service-to-service), Shell cung cấp một cổng gRPC hiệu năng cao sử dụng giao thức Connect RPC (JSON qua HTTP/2).

AuthGateway

Được sử dụng bởi các ứng dụng vệ tinh để trao đổi token hoặc xác minh danh tính.

• Package: auth.v1
• Method: ExchangeForService(ExchangeForServiceRequest) returns (ExchangeForServiceResponse)

RbacService

Được sử dụng bởi các vệ tinh để thực hiện kiểm tra quyền chi tiết dựa trên engine Casbin trung tâm.

• Package: rbac.v1
• Method: CheckPermission(CheckPermissionRequest) returns (CheckPermissionResponse)
• Method: GetUserPermissions(GetUserPermissionsRequest) returns (GetUserPermissionsResponse)

---

3. Tài liệu & Khám phá

Interactive Explorer

Shell API tự động tạo tài liệu OpenAPI 3.0.

• JSON Spec: GET /api/doc/openapi.json
• Swagger UI: GET /api/doc/explorer

Kiểm tra Sức khỏe (Health Check)

Giám sát kết nối cơ sở dữ liệu và tính khả dụng của Redis.

• Endpoint: GET /api/health
• Phanh hồi: { status: "UP", version: "1.0.0" }