Introduction

Este conteúdo não está disponível em sua língua ainda.

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

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

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

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

Property
title	Rough error message
detail	human-readable error message about this specific event
code	Matching HTTP status code