API 集成

概述

闪境空间提供了一套完整的 RESTful API，覆盖了内容管理、媒体资源、分类标签和成员管理等核心功能。同时，Webhook 机制让你的系统可以实时接收闪境空间中的事件通知。

认证

API Token

所有 API 请求都需要通过 API Token 进行认证：

1. 在”设置 > API”页面生成 API Token
2. 每个 Token 可以设置名称和权限范围
3. 建议为不同的集成场景创建不同的 Token

# 在请求头中携带 Token
curl -H "Authorization: Bearer spc_api_xxxxxxxxxxxxxxxx" \
     https://api.shanjing.space/v1/spaces/spc_xxxxx/contents

生成流程

import requests

# 使用 API Token 获取空间内容列表
API_TOKEN = "spc_api_xxxxxxxxxxxxxxxx"
SPACE_ID = "spc_xxxxxxxxxxxxxxxx"
BASE_URL = "https://api.shanjing.space/v1"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

response = requests.get(
    f"{BASE_URL}/spaces/{SPACE_ID}/contents",
    headers=headers,
    params={"page": 1, "per_page": 20}
)

if response.status_code == 200:
    contents = response.json()
    for item in contents["data"]:
        print(f"{item['title']} - {item['status']}")

API Token 应妥善保管，不要泄露到公开仓库或客户端代码中。如果怀疑 Token 泄露，请立即在后台吊销并重新生成。

核心 API 接口

内容管理

GET    /v1/spaces/{space_id}/contents          # 获取内容列表
POST   /v1/spaces/{space_id}/contents          # 创建新内容
GET    /v1/spaces/{space_id}/contents/{id}     # 获取内容详情
PUT    /v1/spaces/{space_id}/contents/{id}     # 更新内容
DELETE /v1/spaces/{space_id}/contents/{id}     # 删除内容

创建内容的请求体示例：

{
  "title": "API 集成指南",
  "content": "# 正文内容\n\n使用 Markdown 格式",
  "format": "markdown",
  "category_id": "cat_xxxxx",
  "tags": ["API", "集成", "教程"],
  "status": "draft",
  "publish_time": null,
  "seo": {
    "title": "API 集成指南 | 闪境空间",
    "description": "学习如何使用闪境空间的 API 进行内容集成"
  }
}

媒体资源

POST   /v1/spaces/{space_id}/media/upload     # 上传文件
GET    /v1/spaces/{space_id}/media             # 获取媒体列表
DELETE /v1/spaces/{space_id}/media/{id}        # 删除媒体文件

分类与标签

GET    /v1/spaces/{space_id}/categories        # 获取分类列表
POST   /v1/spaces/{space_id}/categories        # 创建分类
PUT    /v1/spaces/{space_id}/categories/{id}   # 更新分类
DELETE /v1/spaces/{space_id}/categories/{id}   # 删除分类

GET    /v1/spaces/{space_id}/tags              # 获取标签列表
POST   /v1/spaces/{space_id}/tags              # 创建标签

Webhook

配置 Webhook

在”设置 > Webhook”页面可以配置自定义回调 URL：

1. 点击”新建 Webhook”
2. 输入回调 URL（你的服务器端点）
3. 选择触发事件
4. 设置密钥（用于签名验证）
5. 保存并发送测试事件验证连通性

支持的事件类型

Webhook 签名验证

为了确保 Webhook 请求确实来自闪境空间，每个请求都包含签名头：

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    """验证 Webhook 签名"""
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

处理 Webhook 事件

接收 Webhook 事件时，先验证签名，再根据事件类型处理业务逻辑：

第三方集成

支持的集成

闪境空间目前支持以下第三方服务的集成：

• Slack — 内容发布通知、审核提醒
• 企业微信 — 消息通知、审批流程
• 飞书 — 文档同步、消息通知
• GitHub — 内容变更触发 CI 流程
• Zapier — 连接 2000+ 应用的自动化工作流

自定义集成

如果官方集成列表中没有你需要的服务，你可以通过组合 API 和 Webhook 实现任意自定义集成。例如，监听 content.published 事件，收到通知后调用第三方平台的 API 发布消息。

速率限制

API 调用有速率限制，超过限制会返回 429 Too Many Requests：

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1624032000

• 免费套餐：每分钟 60 次请求
• 专业套餐：每分钟 300 次请求
• 企业套餐：每分钟 1000 次请求（可申请提高）

建议在客户端实现指数退避的重试逻辑。

SDK 与工具

官方提供以下语言的 SDK：

• Python — pip install shanjing-sdk-python
• JavaScript — npm install @shanjing/sdk
• Go — go get github.com/shanjing-space/sdk-go

总结

闪境空间的 API 和 Webhook 能力使它可以深度融入你的技术生态。无论是通过 API 批量管理内容，还是通过 Webhook 实时响应内容变更，都能满足从个人到企业的不同集成需求。