簡介

慣例

發送所有 API 請求的基本 URL 為 http://127.0.0.1:16038/api/v1。未來可能添加 Https 支援。

SignalRGB API 盡可能遵循 RESTful 風格。主要區別是在適用的資源中添加了 post 操作 來代替次要的 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 狀態碼