Introduction

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

• 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

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"

}

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"

    },

Errors

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