API 文档

Webooks RESTful API 完整参考，支持所有书签管理功能。

认证方式

Webooks API 使用 JWT (JSON Web Token) 进行认证。大部分操作需要有效的 JWT 令牌。

获取 JWT 令牌

通过登录接口获取 JWT 令牌：

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

{
  "username": "your_username",
  "password": "your_password"
}

响应示例

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user_123",
    "username": "your_username",
    "email": "your_email@example.com"
  }
}

使用令牌

在后续请求的 Authorization 头中包含令牌：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

响应格式

所有 API 响应都使用统一的 JSON 格式：

成功响应

{
  "success": true,
  "data": {
    // 实际数据
  }
}

错误响应

{
  "error": "错误描述",
  "details": "详细错误信息（可选）"
}

分页响应

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}

错误处理

Webooks API 使用标准 HTTP 状态码：

200 OK

请求成功

400 Bad Request

请求参数错误

401 Unauthorized

未认证或令牌无效

403 Forbidden

权限不足

404 Not Found

资源不存在

500 Internal Server Error

服务器内部错误

书签管理

完整的书签 CRUD 操作接口。

GET /api/bookmarks

获取书签列表

查询参数

参数 类型 必填 描述
spaceId string 否 按空间 ID 筛选
folderId string 否 按文件夹 ID 筛选
search string 否 搜索关键词（标题、描述、URL）

响应示例

{
  "bookmarks": [
    {
      "id": "bookmark_123",
      "title": "GitHub",
      "url": "https://github.com",
      "description": "代码托管平台",
      "iconUrl": "https://github.com/favicon.ico",
      "createdAt": "2024-01-01T00:00:00Z",
      "folder": {
        "id": "folder_456",
        "name": "开发工具"
      },
      "space": {
        "id": "space_789",
        "name": "工作空间"
      }
    }
  ]
}

POST /api/bookmarks

创建新书签（需要认证）

请求体

{
  "title": "书签标题",
  "url": "https://example.com",
  "description": "书签描述",
  "iconUrl": "https://example.com/favicon.ico",
  "spaceId": "space_123",
  "folderId": "folder_456"
}

响应示例

{
  "bookmark": {
    "id": "bookmark_789",
    "title": "书签标题",
    "url": "https://example.com",
    "description": "书签描述",
    "iconUrl": "https://example.com/favicon.ico",
    "spaceId": "space_123",
    "folderId": "folder_456",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

GET /api/bookmarks/[id] - 文档错误

注意：此端点在当前版本中未实现。如需获取单个书签详情，请使用 `GET /api/bookmarks` 并在客户端进行筛选。

PUT /api/bookmarks/[id]

更新书签信息（需要认证）

路径参数

  • id - 书签 ID

请求体

{
  "title": "更新后的标题",
  "description": "更新后的描述",
  "folderId": "folder_789"
}

DELETE /api/bookmarks/[id]

删除书签（需要认证）

路径参数

  • id - 书签 ID

响应示例

{
  "success": true,
  "message": "书签删除成功"
}

POST /api/bookmarks/import

导入书签文件（需要认证）

请求体 (multipart/form-data)

  • file - 书签 HTML 文件
  • spaceId - 目标空间 ID
  • folderId - 目标文件夹 ID（可选）

响应示例

{
  "success": true,
  "folderId": "folder_123",
  "folderName": "导入的书签",
  "total": 45,
  "successCount": 42,
  "errorCount": 3,
  "message": "成功导入 42 个书签，失败 3 个",
  "errors": [
    "导入书签失败: Example Title (https://invalid-url) - Invalid URL format"
  ]
}

GET /api/bookmarks/export

导出书签为 HTML 文件

查询参数

  • spaceId - 指定要导出的空间 ID（可选）

响应

返回 HTML 文件下载，内容为 NETSCAPE-Bookmark-file-1 格式

空间管理

书签空间的创建和管理接口。

GET /api/spaces

获取用户的所有空间列表

响应示例

{
  "spaces": [
    {
      "id": "space_123",
      "name": "工作空间",
      "description": "用于工作相关的书签",
      "iconUrl": "https://example.com/icon.png",
      "systemCardUrl": "https://example.com/card.png",
      "createdAt": "2024-01-01T00:00:00Z",
      "_count": {
        "bookmarks": 25,
        "folders": 3
      }
    }
  ]
}

POST /api/spaces

创建新空间（需要认证）

请求体

{
  "name": "新空间名称",
  "description": "空间描述",
  "iconUrl": "https://example.com/icon.png",
  "systemCardUrl": "https://example.com/card.png"
}

响应示例

{
  "space": {
    "id": "space_456",
    "name": "新空间名称",
    "description": "空间描述",
    "iconUrl": "https://example.com/icon.png",
    "systemCardUrl": "https://example.com/card.png",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

GET /api/spaces/[id]

获取指定空间的详细信息

路径参数

  • id - 空间 ID

响应示例

{
  "space": {
    "id": "space_123",
    "name": "工作空间",
    "description": "用于工作相关的书签",
    "iconUrl": "https://example.com/icon.png",
    "systemCardUrl": "https://example.com/card.png",
    "createdAt": "2024-01-01T00:00:00Z",
    "bookmarks": [...],
    "folders": [...]
  }
}

PUT /api/spaces/[id]

更新空间信息（需要认证）

路径参数

  • id - 空间 ID

请求体

{
  "name": "更新后的空间名称",
  "description": "更新后的描述",
  "iconUrl": "https://example.com/new-icon.png"
}

DELETE /api/spaces/[id]

删除空间（需要认证）

路径参数

  • id - 空间 ID

注意

删除空间会同时删除空间内的所有书签和文件夹

POST /api/spaces/[id]/verify-password

验证加密空间密码

路径参数

  • id - 空间 ID

请求体

{
  "password": "space_password"
}

响应示例

{
  "valid": true,
  "message": "密码验证成功"
}

POST /api/spaces/verify-password

通过空间名称验证加密空间密码

请求体

{
  "spaceName": "空间名称",
  "password": "space_password"
}

响应示例

{
  "valid": true,
  "spaceId": "space_123"
}

文件夹管理

书签文件夹的创建和管理接口。

GET /api/folders

获取文件夹列表

查询参数

  • spaceId - 按空间 ID 筛选（可选）
  • parentId - 按父文件夹 ID 筛选（可选）

响应示例

{
  "folders": [
    {
      "id": "folder_123",
      "name": "开发工具",
      "description": "开发相关的工具和资源",
      "spaceId": "space_456",
      "parentId": null,
      "bookmarkCount": 12,
      "createdAt": "2024-01-01T00:00:00Z",
      "subfolders": [...]
    }
  ]
}

POST /api/folders

创建新文件夹（需要认证）

请求体

{
  "name": "新文件夹名称",
  "description": "文件夹描述",
  "spaceId": "space_123",
  "parentId": "folder_456"
}

响应示例

{
  "folder": {
    "id": "folder_789",
    "name": "新文件夹名称",
    "description": "文件夹描述",
    "spaceId": "space_123",
    "parentId": "folder_456",
    "bookmarkCount": 0,
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

系统管理

系统配置和数据管理相关的 API 接口。

GET /api/system-config

获取系统配置信息

响应示例

{
  "id": "config_123",
  "defaultSpaceId": "space_456",
  "defaultSpace": {
    "id": "space_456",
    "name": "默认空间"
  },
  "siteTitle": "Webooks",
  "faviconUrl": "/favicon.ico",
  "seoDescription": "智能书签管理系统",
  "keywords": "书签,管理,工具",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

PUT /api/system-config

更新系统配置（需要认证）

请求体

{
  "defaultSpaceId": "space_456",
  "siteTitle": "My Webooks",
  "faviconUrl": "/custom-favicon.ico",
  "seoDescription": "自定义描述",
  "keywords": "自定义,关键词"
}

GET /api/system-export

导出完整系统数据（需要认证）

响应

返回 JSON 格式的系统数据，包含用户信息、配置、空间、文件夹和书签等完整信息

{
  "version": "1.0",
  "exportTime": "2024-01-01T00:00:00Z",
  "user": {...},
  "systemConfig": {...},
  "spaces": [...],
  "folders": [...],
  "bookmarks": [...],
  "summary": {
    "totalSpaces": 5,
    "totalFolders": 12,
    "totalBookmarks": 150,
    "encryptedSpaces": 2
  }
}

POST /api/system-import

导入系统数据（需要认证）

请求体 (multipart/form-data)

  • file - 系统导出的 JSON 文件
  • mode - 导入模式（"append" 或 "replace"）

响应示例

{
  "success": true,
  "mode": "replace",
  "imported": {
    "spaces": 5,
    "folders": 12,
    "bookmarks": 150
  },
  "message": "成功导入系统数据"
}

扩展功能

浏览器扩展相关的 API 接口。

GET /api/extension/bookmarks

获取扩展可访问的书签（需要 API 密钥）

请求头

Authorization: Bearer YOUR_API_KEY

响应示例

{
  "bookmarks": [
    {
      "id": "bookmark_123",
      "title": "GitHub",
      "url": "https://github.com",
      "description": "代码托管平台"
    }
  ]
}

GET /api/extension/api-key

获取扩展 API 密钥（需要管理员认证）

响应示例

{
  "apiKey": "webooks_extension_key_123456789"
}

POST /api/scrape

抓取网页元数据（需要认证）

请求体

{
  "url": "https://example.com"
}

响应示例

{
  "success": true,
  "metadata": {
    "title": "网页标题",
    "description": "网页描述",
    "iconUrl": "https://example.com/favicon.ico"
  }
}