Introduktion

Konventioner

Bas-URL:en dit alla API-förfrågningar skickas är: http://127.0.0.1:16038/api/v1. Https kan läggas till vid ett senare tillfälle.

SignalRGB API följer RESTful-stil där det är möjligt. Den huvudsakliga skillnaden är att postade åtgärder läggs till resurser där det är tillämpligt i stället för ett sekundärt JSON-RPC API. T.ex. POST effect/{effectId}/apply.

JSON-konventioner

SignalRGB API drar nytta av json:api och Googles JSON-stilguide med mindre ändringar där det är möjligt.
- json:api-medietypen utelämnas.
- json:api-relationer utelämnas.
Alla objekt har ett associerat id. Dessa är specifika för objekttypen men kanske inte är unika för alla objekttyper.
Egenskapsnamn är i snake_case format där det är möjligt, med undantag för till exempel Plugin/Effect-användaregenskaper som hämtas direkt från plugin/effekt-filen.

Svarsobjekt

Svar följer i allmänhet ett visst mönster med smärre skillnader mellan framgång och misslyckande och mellan flera och enstaka resurser. Alla svar returnerar aktuell API-version, ett unikt förfrågnings-id, den anropade metod-URL:en, relevanta parametrar och status Enum-värdet utöver HTTP-statuskoden.

Framgångsrika förfrågningar returnerar en data-egenskap på toppnivå, medan misslyckanden returnerar en array med felobjekt.

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

Resurser

Resurser returneras alltid inom ett dataobjekt på toppnivå och innehåller resursens id- och type-värden. Där det är tillämpligt grupperas underfält under en attributes-egenskap och relaterade länkar under en links-egenskap.

När flera resurser returneras returneras en array med objekt som matchar formatet ovan.

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

Fel

Fel returneras alltid i en array under en errors-egenskap på toppnivå.

Egenskap
title	Generellt felmeddelande
detail	Mänskligt läsbart felmeddelande om det specifika fallet
code	Matchande HTTP-statuskod