Bỏ qua

Thêm endpoint API v1

Mục tiêu

Hướng dẫn từng bước để thêm một endpoint mới vào FastAPI router của HieraChain (phiên bản v1), bao gồm định nghĩa schema Pydantic, viết handler, cập nhật router và kiểm thử nhanh bằng curl.

Bước 1: Chuẩn bị schema (tuỳ chọn)

  • Mở hierachain/api/v1/schemas.py.
  • Thêm lớp Pydantic nếu endpoint cần payload mới, ví dụ:
class PingRequest(BaseModel):
  message: str

class PingResponse(BaseModel):
  ok: bool
  echo: str

Bước 2: Thêm handler trong router

  • Mở hierachain/api/v1/endpoints.py.
  • Import schema (nếu có) và thêm route vào APIRouter(prefix="/api/v1", ...).

Ví dụ (mô tả):

@router.post("/ping", response_model=PingResponse)
async def ping(req: PingRequest):
  return PingResponse(ok=True, echo=req.message)

Gợi ý: dùng DI sẵn có (ví dụ Depends(get_hierarchy_manager)) nếu endpoint cần truy cập hệ thống chuỗi.

Bước 3: Chạy server và kiểm thử nhanh

python -m hierachain.api.server

Mở http://localhost:2661/docs để thử trên Swagger UI hoặc dùng curl:

curl -s -X POST http://localhost:2661/api/v1/ping \
  -H 'Content-Type: application/json' \
  -d '{"message":"hello"}'

Nếu bật xác thực API key (production), thêm header theo settings.API_KEY_NAME:

-H 'X-API-Key: <your-key>'

Bước 4: Liên kết tài liệu

  • Cập nhật docs/mkdocs.yml để bổ sung hướng dẫn này vào mục Hướng dẫn (nếu chưa có).
  • Liên kết chéo từ trang API module/Reference.

Lưu ý mở rộng

  • Đặt tên đường dẫn, tham số, và response model rõ ràng.
  • Xử lý lỗi với HTTPException (400/404/500) và thông điệp minh bạch.
  • Viết test (pytest) nếu endpoint có logic quan trọng.

Liên quan