Skip to content
SignalRGB

Introduction

Conventions

Section titled “Conventions”

The base URL to send all API requests is http://127.0.0.1:16038/api/v1. Https may be added at a later date.

The SignalRGB API follows a RESTful style where possible. The main difference is the addition of post actions being added to resources where applicable in place of a secondary JSON-RPC API. i.e. POST effect/{effectId}/apply.

JSON conventions

Section titled “JSON conventions”

  • The SignalRGB API pulls from json:api and the Google JSON Style Guide where possible with minor changes.

    • json:api media type is omitted.
    • json:api relationships are omitted

  • All objects have an associated id. These are unique to the object type, but may not be unique across all object types.

  • Property names are in snake_case whenever possible with exceptions for things like Plugin/Effect user properties that are pulled directedly from the plugin/effect file.

Response Objects

Section titled “Response Objects”

Reponses will generally follow a specific layout with minor differences based on success, failure, and multiple vs single resources. All responses will return the current API version, a unique request id, the method URL called, any relevant params, and a status Enum in addition to the HTTP status code.

Successful requests will return a top level data property, while failures will return an array of error objects.

{
    "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"
}

Resources

Section titled “Resources”

Resources will always be returned inside of the top-level data object, and will contain the resources id, and type. Where applicable subfields will be grouped under an attributes property, and relevant links under a links property.

In the case of returning multiple resources an array of items will be returned matching the above format.

"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

Section titled “Errors”

Error will always be returned in an array under a top-level errors property.

Property
titleRough error message
detailhuman-readable error message about this specific event
codeMatching HTTP status code