API v3

Mục đích

Mô tả các endpoint REST trong phiên bản API v3 (System & Admin) dùng cho các tác vụ quản trị hệ thống: xác minh danh tính node, kiểm tra trạng thái hoạt động (uptime, version, active chains).

Tổng quan endpoint

POST /api/v3/verify-identity — Xác minh danh tính node bằng cách ký vào một chuỗi challenge. (Yêu cầu xác thực)
GET /api/v3/status — Lấy báo cáo chi tiết về trạng thái node. (Yêu cầu API Key nếu AUTH_ENABLED=true)

Schema chính (trích từ `hierachain/api/v3/schemas.py`)

VerifyIdentityRequest
- challenge: str (Chuỗi challenge cần ký, hex encoded)
VerifyIdentityResponse
- status: str ("success")
- node_id: str (Định danh của node)
- signature: str (Chữ ký số của challenge)
- challenge: str (Challenge gốc đã nhận)
NodeStatusResponse
- status: str ("active")
- version: str (Phiên bản Ledger)
- chains_active: int (Số lượng sub-chain đang hoạt động)
- license_active: bool (Trạng thái bản quyền)
- uptime: str (Thời gian hoạt động của hệ thống)

Ví dụ sử dụng

Giả định server đang chạy tại http://localhost:2661:

Xác minh danh tính node (Verify Identity)

Endpoint này thường được sử dụng bởi các công cụ quản lý để xác nhận node này là thành viên hợp lệ của mạng lưới.

sequenceDiagram
    participant Client
    participant Node

    Client->>Node: POST /verify-identity {challenge: "abcd"}
    Note over Node: Ký challenge bằng Private Key
    Node-->>Client: 200 OK {signature: "..."}
    Note over Client: Verify signature bằng Node Public Key

Request:

curl -X POST http://localhost:2661/api/v3/verify-identity \
  -H "Content-Type: application/json" \
  -d '{
        "challenge": "abcd1234"
      }'

Phản hồi (200 OK):

{
  "status": "success",
  "node_id": "node_1",
  "signature": "3045022100...", 
  "challenge": "abcd1234"
}

(Lưu ý: signature sẽ là chuỗi hex thực tế được ký bởi private key của node)

Kiểm tra trạng thái node (Node Status)

Lấy thông tin tổng quan về sức khỏe và trạng thái của node.