Inleiding

Conventies

De basis-URL voor alle API-verzoeken is http://127.0.0.1:16038/api/v1. HTTPS kan op een later tijdstip worden toegevoegd.

De SignalRGB-API volgt waar mogelijk een RESTful-stijl. Het belangrijkste verschil is de toevoeging van post-acties aan resources waar van toepassing, in plaats van een secundaire JSON-RPC-API. Bijv. POST effect/{effectId}/apply.

JSON-conventies

De SignalRGB-API put uit json:api en de Google JSON Style Guide waar mogelijk, met kleine aanpassingen.
- Het json:api-mediatype is weggelaten.
- json:api-relaties zijn weggelaten.
Alle objecten hebben een bijbehorend ID. Deze zijn uniek per objecttype, maar zijn mogelijk niet uniek over alle objecttypen heen.
Eigenschapsnamen zijn waar mogelijk in snake_case, met uitzonderingen voor zaken als Plugin/Effect-gebruikerseigenschappen die rechtstreeks uit het plugin/effect-bestand worden gehaald.

Responsobjecten

Reacties volgen over het algemeen een specifieke indeling met kleine verschillen op basis van succes, mislukking en meerdere versus enkelvoudige resources. Alle reacties retourneren de huidige API-versie, een uniek verzoek-ID, de aangeroepen methode-URL, relevante parameters en een status-Enum naast de HTTP-statuscode.

Succesvolle verzoeken retourneren een data-eigenschap op het hoogste niveau, terwijl mislukkingen een array van foutobjecten retourneren.

{
    "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 worden altijd teruggegeven binnen het data-object op het hoogste niveau en bevatten de id en type van de resource. Waar van toepassing worden subvelden gegroepeerd onder een attributes-eigenschap en relevante links onder een links-eigenschap.

Bij het retourneren van meerdere resources wordt een array van items teruggegeven die overeenkomt met het bovenstaande formaat.

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

Fouten

Fouten worden altijd teruggegeven in een array onder een errors-eigenschap op het hoogste niveau.

Eigenschap
title	Ruwe foutmelding
detail	Leesbare foutmelding over dit specifieke geval
code	Overeenkomende HTTP-statuscode