跳到主要内容

关于 REST API

为了支持各类不同平台的开发需要，YedMQ 提供了一组基于 RESTful 标准风格设计的HTTP API。

基本路径​

YedMQ 在 REST API 上做了相关版本区分，现阶段所有的API均已 /api/v1 开头。

HTTP 请求头​

绝大多数API要求请求头中 Accept 值设置为 application/json, 响应内容以JSON格式返回。

认证​

现阶段 YedMQ 主要使用 Http Basic Authentication。

使用 Http Basic Authentication 认证​

在这种方法中，您通过使用配置在 YedMQ 配置文件中的用户名以及密码来对API请求进行身份验证。

新增用户名以及密码​

您可以在配置文件中增加密钥，例如：

[listener.api.auth]
users = [
    { username = "admin", password = "password" } # 必须在一行内
]

您可以增加多个用户名密钥:

  • username: 用户名
  • password: 密码

注意： 因为TOML格式的限制，一个用户配置需要在一行内。

✅正确的配置：

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

❌错误的配置：

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

每次 YedMQ 启动时，会读取配置文件中的密钥，并在API请求时候进行相关检查。

请求示例如下：

curl -X GET http://localhost:3456/api/v1/plugins \
     -u admin:password \
     -H "Content-Type: application/json"

分页​

在一些可能返回数据量比较大的API中，提供了分页功能。

offset limit 分页​

支持分页的API中，您可以通过offset 和 limit 参数来控制分页，如果不指定相关参数，系统默认offset 为 0， limit 为 10。

例如：

GET /api/v1/plugins?offset=0&limit=10

响应结果中 meta 字段将包含分页信息，例如:

{
    "meta": {
        "offset": 0,
        "limit": 10,
        "total": 1
    },
    "data": [
        {
            "name": "YedMQ_Acl_File_Plugin",
            "version": "0.0.1",
            "description": "This plugin provides file-based ACL (Access Control List) management.",
            "entry": "./libyedmq_plugins_acl_file.so",
            "priority": 1000,
            "author": "yedmq"
        }
    ]
}