Introduktion

Konventioner

Basis-URL’en for alle API-forespørgsler er http://127.0.0.1:16038/api/v1. HTTPS kan tilføjes på et senere tidspunkt.

SignalRGB API følger en RESTful-stil så vidt muligt. Den primære forskel er tilføjelsen af Post-handlinger, der tilføjes til ressourcer, hvor det er relevant, i stedet for en sekundær JSON-RPC API. F.eks. POST effect/{effectId}/apply.

JSON-konventioner

SignalRGB API følger json:api og Google JSON Style Guide så vidt muligt med mindre ændringer.
- json:api-medietypen udelades.
- json:api-relationer udelades.
Alle objekter har en tilknyttet ID. Disse er unikke for objekttypen, men er muligvis ikke unikke på tværs af alle objekttyper.
Egenskabsnavne er i snake_case så vidt muligt, med undtagelser for ting som plugin/effect-brugeregenskaber, der hentes direkte fra plugin/effect-filen.

Svarobjekter

Svar følger generelt et bestemt layout med mindre forskelle afhængigt af succes, fejl og flere versus enkelt ressourcer. Alle svar returnerer den aktuelle API-version, et unikt forespørgsels-ID, den kaldte metode-URL, alle relevante parametre og et status-enum ud over HTTP-statuskoden.

Vellykkede forespørgsler returnerer en data-egenskab på øverste niveau, mens fejl returnerer et array af fejlobjekter.

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

Ressourcer

Ressourcer returneres altid inden for data-objektet på øverste niveau og indeholder ressourcens id og type. Hvor det er relevant, grupperes underfelter under en attributes-egenskab og relevante links under en links-egenskab.

Ved returnering af flere ressourcer returneres et array af elementer i ovenstående 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"
    },
    ...
  ]
}

Fejl

Fejl returneres altid i et array under en errors-egenskab på øverste niveau.

Egenskab
title	Overordnet fejlmeddelelse
detail	Menneskelæsbar fejlmeddelelse for denne specifikke hændelse
code	Tilsvarende HTTP-statuskode