Tài liệu API

Tham chiếu kỹ thuật cho REST API và tích hợp WebSocket của Resolflow

Tham chiếu API nội bộ

Tài liệu này mô tả REST API nội bộ của Resolflow để hiểu cách nền tảng hoạt động. Resolflow là một ứng dụng độc lập, không phải API nền tảng cho tích hợp bên thứ ba. Nếu bạn cần tương tác với Resolflow bằng lập trình, hãy sử dụng giao thức MCP.

Tổng quan API

Kiến trúc và khả năng

Thiết kế RESTful

Phương thức HTTP chuẩn (GET, POST, PATCH, DELETE)

Cập nhật thời gian thực

WebSocket cho thông báo trực tiếp

Phản hồi JSON

Định dạng dữ liệu nhất quán

Xác thực

Xác thực dựa trên JWT với token kép

Hệ thống token

Access Token
15 phút

Token ngắn hạn lưu trong cookie HTTP-only. Dùng cho các yêu cầu API.

Refresh Token
7 ngày

Token dài hạn để lấy access token mới mà không cần đăng nhập lại.

# Đăng nhập để lấy token

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "yourpassword"
}

Response:
{
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "name": "John Doe"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

# Dùng access token trong yêu cầu

GET /api/workspaces
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Điểm cuối API cốt lõi

Tài nguyên và thao tác chính

Xác thực

POST
/api/auth/register

Tạo tài khoản mới

POST
/api/auth/login

Đăng nhập bằng email/mật khẩu

POST
/api/auth/refresh

Lấy access token mới

POST
/api/auth/logout

Xóa token và kết thúc phiên

GET
/api/auth/me

Lấy thông tin người dùng hiện tại

Không gian làm việc

GET
/api/workspaces

Liệt kê tất cả không gian làm việc

GET
/api/workspaces/:id

Lấy chi tiết không gian làm việc

POST
/api/workspaces

Tạo không gian làm việc mới

PATCH
/api/workspaces/:id

Cập nhật không gian làm việc

DELETE
/api/workspaces/:id

Xóa không gian làm việc

Dự án

GET
/api/workspaces/:workspaceId/projects

Liệt kê dự án trong không gian làm việc

POST
/api/workspaces/:workspaceId/projects

Tạo dự án

PATCH
/api/projects/:id

Cập nhật thiết lập dự án

Nhiệm vụ & Việc cần làm

GET
/api/projects/:projectId/tasks

Liệt kê nhiệm vụ

POST
/api/projects/:projectId/tasks

Tạo nhiệm vụ

GET
/api/tasks/:taskId/todos

Liệt kê việc cần làm của nhiệm vụ

PATCH
/api/todos/:id

Cập nhật trạng thái việc cần làm

Agent & Kết nối

GET
/api/workspaces/:workspaceId/agents

Liệt kê agent MCP

POST
/api/projects/:projectId/tokens

Tạo token MCP

GET
/api/workspaces/:workspaceId/repos

Liệt kê kho GitHub đã kết nối

Orchestrator

POST
/api/orchestrator/suggest-tasks

Tạo nhiệm vụ bằng AI

GET
/api/orchestrator/inbox

Lấy tin nhắn orchestrator

POST
/api/orchestrator/ask

Hỏi orchestrator để được hướng dẫn

Báo cáo & Phân tích

GET
/api/projects/:projectId/reports

Liệt kê báo cáo

GET
/api/reports/:id

Lấy chi tiết báo cáo

Cập nhật thời gian thực WebSocket

Thông báo trực tiếp và đồng bộ dữ liệu

Kết nối với máy chủ WebSocket để cập nhật thời gian thực về nhiệm vụ, việc cần làm, tin nhắn orchestrator và báo cáo.

# Kết nối với WebSocket

// Send authentication
{
  "type": "auth",
  "token": "your-access-token"
}

// Subscribe to workspace updates
{
  "type": "subscribe",
  "workspaceId": "workspace-uuid"
}

// Receive updates
{
  "type": "task_updated",
  "data": {
    "taskId": "uuid",
    "status": "in_progress",
    "updatedBy": "agent-name"
  }
}

Loại sự kiện

task_created

Đã thêm nhiệm vụ mới

task_updated

Trạng thái nhiệm vụ đã thay đổi

todo_updated

Cập nhật tiến độ việc cần làm

orchestrator_message

Hướng dẫn mới từ AI

report_generated

Báo cáo phân tích mới

loop_signal

Phát hiện agent bị kẹt

Ví dụ: Tạo nhiệm vụ

Luồng yêu cầu và phản hồi đầy đủ

Yêu cầu

POST /api/projects/550e8400-e29b-41d4-a716-446655440000/tasks
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "title": "Add dark mode support",
  "description": "Implement dark mode toggle with system preference detection",
  "type": "feature",
  "priority": "medium"
}

Phản hồi (201 Created)

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "title": "Add dark mode support",
  "description": "Implement dark mode toggle with system preference detection",
  "type": "feature",
  "priority": "medium",
  "status": "not_started",
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "user-uuid",
  "createdAt": "2024-02-12T10:30:00Z",
  "updatedAt": "2024-02-12T10:30:00Z"
}

Giới hạn tốc độ & Thực hành tốt nhất

Hướng dẫn sử dụng API

Giới hạn tốc độ

Hiện không áp dụng giới hạn tốc độ cho các phiên bản tự lưu trữ. Đối với triển khai sản xuất, hãy cân nhắc triển khai giới hạn tốc độ dựa trên hạ tầng của bạn.

Thực hành tốt nhất

  • • Dùng WebSocket cho dữ liệu thời gian thực thay vì polling
  • • Lưu cache phản hồi phía client (React Query xử lý việc này)
  • • Gộp thao tác khi có thể (tạo hàng loạt việc cần làm)
  • • Xử lý làm mới token tự động bằng interceptor
  • • Dùng cập nhật lạc quan để có UX tốt hơn

Xử lý lỗi

Mã trạng thái HTTP chuẩn:

  • • 200 - Thành công
  • • 201 - Đã tạo
  • • 400 - Yêu cầu sai (lỗi xác thực)
  • • 401 - Không được phép (token không hợp lệ/hết hạn)
  • • 403 - Bị cấm (không đủ quyền)
  • • 404 - Không tìm thấy
  • • 500 - Lỗi máy chủ