Введение

Соглашения

Базовый URL для отправки всех API-запросов: http://127.0.0.1:16038/api/v1. HTTPS может быть добавлен в будущем.

API SignalRGB следует стилю RESTful там, где это возможно. Основное отличие — добавление post actions к ресурсам там, где применимо, вместо вторичного JSON-RPC API. Например: POST effect/{effectId}/apply.

JSON-соглашения

API SignalRGB опирается на json:api и Google JSON Style Guide там, где возможно, с небольшими изменениями.
- Тип медиа json:api опускается.
- Отношения json:api опускаются.
Все объекты имеют связанный id. Они уникальны для типа объекта, но могут не быть уникальными для всех типов объектов.
Имена свойств — в snake_case там, где возможно, с исключениями для таких вещей, как пользовательские свойства плагинов/эффектов, которые берутся непосредственно из файла плагина/эффекта.

Объекты ответа

Ответы, как правило, следуют определённой структуре с небольшими различиями в зависимости от успеха, ошибки и одиночного/множественного ресурса. Все ответы возвращают текущую версию API, уникальный id запроса, вызванный URL метода, соответствующие параметры и статус Enum в дополнение к HTTP-коду статуса.

Успешные запросы возвращают свойство 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"
}

Ресурсы

Ресурсы всегда возвращаются внутри объекта данных верхнего уровня и содержат 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-код статуса