Uvod

Konvencije

Osnovna URL adresa za sve API zahteve je http://127.0.0.1:16038/api/v1. HTTPS može biti dodat u kasnijem trenutku.

SignalRGB API prati RESTful stil gde je to moguće. Glavna razlika je dodavanje Post akcija resursima gde je primenljivo, umesto sekundarne JSON-RPC API. Npr. POST effect/{effectId}/apply.

JSON konvencije

SignalRGB API se gde je moguće ugleda na json:api i Google JSON Style Guide sa manjim izmenama.
- json:api media tip se izostavlja.
- json:api relacije se izostavljaju.
Svi objekti imaju pridruženi ID. Ovi su jedinstveni za tip objekta, ali možda nisu jedinstveni kroz sve tipove objekata.
Nazivi svojstava su u snake_case gde je moguće, sa izuzecima za stvari poput korisničkih svojstava plugina/efekta, koji se preuzimaju direktno iz datoteke plugina/efekta.

Objekti odgovora

Odgovori generalno prate određeni raspored sa manjim razlikama zavisno od uspešnosti, greške i više nasuprot pojedinačnih resursa. Svi odgovori vraćaju trenutnu verziju API-ja, jedinstven ID zahteva, pozvanu URL metodu, sve relevantne parametre i status enum pored HTTP koda statusa.

Uspešni zahtevi vraćaju svojstvo data na najvišem nivou, dok greške vraćaju niz objekata grešaka.

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

Resursi

Resursi se uvek vraćaju unutar objekta data na najvišem nivou i sadrže id i type resursa. Gde je primenljivo, podpolja su grupisana pod svojstvo attributes, a relevantni linkovi pod svojstvo links.

Pri vraćanju više resursa, vraća se niz stavki u gore navedenom formatu.

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

Greške

Greške se uvek vraćaju u nizu pod svojstvom errors na najvišem nivou.

Svojstvo
title	Opšta poruka greške
detail	Čitljiva poruka greške za ovaj specifičan događaj
code	Odgovarajući HTTP kod statusa