简介

约定

发送所有 API 请求的基本 URL 为 http://127.0.0.1:16038/api/v1。Https 可能会在以后的日期添加。

SignalRGB API 尽可能遵循 RESTful 风格。主要区别在于在适用的资源上添加了 post actions，以代替辅助 JSON-RPC API。即 POST effect/{effectId}/apply。

JSON 约定

SignalRGB API 尽可能参考 json:api 和 Google JSON 样式指南，并进行了少量更改。
- 省略 json:api 媒体类型。
- 省略 json:api 关系。
所有对象都有关联的 id。这些 id 在对象类型内是唯一的，但在所有对象类型中可能不唯一。
属性名称尽可能使用 snake_case，但像插件/效果用户属性（直接从插件/效果文件中提取）这样的内容除外。

响应对象

响应通常遵循特定的布局，根据成功、失败以及多个资源与单个资源之间有细微差异。所有响应除了 HTTP 状态码外，还将返回当前 API 版本、唯一请求 id、调用的方法 URL、任何相关参数以及状态枚举。

成功的请求将返回顶级 data 属性，而失败的请求将返回错误对象数组。

{
    "apiVersion": "1.0",
    "data": {
        "attributes": {
            "name": "Neon Shift"
        },
        "id": "Neon Shift.html",
        "links": {
            "self": "/api/v1/lighting/effects/Neon Shift.html"
        },
        "type": "current_effect"
    },
    "id": 1,
    "method": "/api/v1/lighting",
    "params": {},
    "status": "ok"
}

{
  "apiVersion": "1.0",
    "errors": [
        {
            "code": "404",
            "detail": "The requested effect was not found",
            "title": "Not Found"
        }
    ],
    "id": 2,
    "method": "/api/v1/lighting/effects/-Mg1qujV9F4rabJxlS",
    "params": {
        "id": "-Mg1qujV9F4rabJxlS"
    },
    "status": "error"
}

资源

资源将始终在顶级 data 对象内返回，并将包含资源的 id 和 type。在适用的情况下，子字段将归组在 attributes 属性下，相关链接归组在 links 属性下。

在返回多个资源的情况下，将返回与上述格式匹配的项目数组。

"data": {
        "attributes": {
            "name": "Neon Shift"
        },
        "id": "Neon Shift.html",
        "links": {
            "self": "/api/v1/lighting/effects/Neon Shift.html"
        },
        "type": "current_effect"
    },

"data": {
  "items": [
    {
      "attributes": {
        "name": "Wolfenstein II: TNC"
      },
      "id": "-MQtFeX-o2hMR6sv8aFr",
      "links": {
        "apply": "/api/v1/lighting/effects/-MQtFeX-o2hMR6sv8aFr/apply",
        "self": "/api/v1/lighting/effects/-MQtFeX-o2hMR6sv8aFr"
      },
      "type": "effect"
    },
    {
      "attributes": {
        "name": "4th Dimension"
      },
      "id": "-N-YhDDs2ZIGJ42azDgJ",
      "links": {
        "apply": "/api/v1/lighting/effects/-N-YhDDs2ZIGJ42azDgJ/apply",
        "self": "/api/v1/lighting/effects/-N-YhDDs2ZIGJ42azDgJ"
      },
      "type": "effect"
    },
    ...
  ]
}

错误

错误将始终在顶级 errors 属性下的数组中返回。

属性
title	粗略错误消息
detail	关于此特定事件的人类可读错误消息
code	匹配的 HTTP 状态码