REST API 概览

YedMQ 提供管理用 REST API，用于自动化、诊断和集群操作。

权威参考

生成的 管理 API 参考 才是最权威的接口文档。本页主要概括认证方式、API 结构和常见使用模式。

基本路径

当前所有接口都挂在 /api/v1 之下。

认证方式

管理 API 使用在 yedmq.toml 中配置的 HTTP Basic Authentication。

仓库自带的示例配置会把 API 绑定到 127.0.0.1，并且默认 users = []，因此调用接口前需要先添加至少一个用户：

[listener.api.auth]
users = [{ username = "admin", password = "replace_me" }]

请求示例：

curl -u admin:replace_me \
  http://127.0.0.1:3456/api/v1/plugins

主要接口分组

• 系统与插件：
  • GET /api/v1/system_info
  • GET /api/v1/plugins
• 租户范围接口：
  • GET /api/v1/{tenant_id}/clients
  • GET /api/v1/{tenant_id}/topics
  • GET /api/v1/{tenant_id}/messages/retained
  • POST /api/v1/{tenant_id}/messages
  • POST /api/v1/{tenant_id}/clients/{client_id}/kickoff
• 集群管理：
  • GET /api/v1/cluster/metrics
  • GET /api/v1/cluster/ready
  • POST /api/v1/cluster/learners
  • POST /api/v1/cluster/nodes
  • POST /api/v1/cluster/topic/learners
  • POST /api/v1/cluster/session_actor_map/learners
  • POST /api/v1/cluster/session_state/learners
  • POST /api/v1/cluster/membership
  • 以及各 raft 的初始化和成员管理接口

分页

列表类接口通常会暴露 offset 和 limit 查询参数。支持分页的响应里会返回 meta 字段，用于描述当前窗口。

集群操作建议

• 在自动化流程、健康检查或切流前，优先调用 GET /api/v1/cluster/ready 判断三个 raft 组是否都已就绪。
• 当你希望一次性把节点加入整个集群时，优先使用 POST /api/v1/cluster/nodes 这个高层接口。
• .../learners 和 .../membership 这类按 raft 拆分的接口更适合做分阶段变更、恢复操作或手工修复。

推荐使用方式

以下场景建议直接查看生成的 OpenAPI 页面：

• 请求与响应结构
• 精确字段名
• 示例 payload
• 单个接口的参数列表