Einführung

Konventionen

Die Basis-URL für alle API-Anfragen lautet http://127.0.0.1:16038/api/v1. HTTPS kann zu einem späteren Zeitpunkt hinzugefügt werden.

Die SignalRGB API folgt soweit möglich einem RESTful-Stil. Der Hauptunterschied ist die Ergänzung von Post-Aktionen, die Ressourcen hinzugefügt werden, wo zutreffend, anstelle einer sekundären JSON-RPC API. Z. B. POST effect/{effectId}/apply.

JSON-Konventionen

Die SignalRGB API orientiert sich soweit möglich mit geringfügigen Änderungen an json:api und dem Google JSON Style Guide.
- Der json:api-Medientyp wird weggelassen.
- json:api-Beziehungen werden weggelassen.
Alle Objekte haben eine zugehörige ID. Diese sind für den Objekttyp eindeutig, aber möglicherweise nicht über alle Objekttypen hinweg eindeutig.
Eigenschaftsnamen sind soweit möglich in snake_case, mit Ausnahmen für Dinge wie Plugin/Effect-Benutzereigenschaften, die direkt aus der Plugin/Effect-Datei übernommen werden.

Antwortobjekte

Antworten folgen im Allgemeinen einem bestimmten Layout mit geringfügigen Unterschieden je nach Erfolg, Fehler und mehreren vs. einzelnen Ressourcen. Alle Antworten geben die aktuelle API-Version, eine eindeutige Anfrage-ID, die aufgerufene Methoden-URL, alle relevanten Parameter und ein Status-Enum zusätzlich zum HTTP-Statuscode zurück.

Erfolgreiche Anfragen geben eine data-Eigenschaft auf oberster Ebene zurück, während Fehler ein Array von Fehlerobjekten zurückgeben.

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

Ressourcen

Ressourcen werden immer innerhalb des data-Objekts auf oberster Ebene zurückgegeben und enthalten die id und den type der Ressource. Wo zutreffend, werden Unterfelder unter einer attributes-Eigenschaft und relevante Links unter einer links-Eigenschaft gruppiert.

Bei der Rückgabe mehrerer Ressourcen wird ein Array von Elementen im oben genannten Format zurückgegeben.

"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"
    },
    ...
  ]
}

Fehler

Fehler werden immer in einem Array unter einer errors-Eigenschaft auf oberster Ebene zurückgegeben.

Eigenschaft
title	Grobe Fehlermeldung
detail	Menschenlesbare Fehlermeldung zu diesem spezifischen Ereignis
code	Übereinstimmender HTTP-Statuscode