Wprowadzenie

Konwencje

Podstawowy URL dla wszystkich żądań API to http://127.0.0.1:16038/api/v1. HTTPS może być dodane w późniejszym terminie.

API SignalRGB stosuje styl RESTful tam, gdzie to możliwe. Główna różnica to dodanie akcji post do zasobów tam, gdzie ma to zastosowanie, zamiast dodatkowego API JSON-RPC. Np. POST effect/{effectId}/apply.

Konwencje JSON

API SignalRGB czerpie z json:api i Przewodnika po stylu JSON Google tam, gdzie to możliwe, z niewielkimi modyfikacjami.
- Typ mediów json:api jest pominięty.
- Relacje json:api są pominięte.
Wszystkie obiekty mają powiązane ID. Są unikalne według typu obiektu, ale mogą nie być unikalne we wszystkich typach obiektów.
Nazwy właściwości są w snake_case tam, gdzie to możliwe, z wyjątkami dla takich rzeczy jak właściwości użytkownika Plugin/Effect, które są pobierane bezpośrednio z pliku wtyczki/efektu.

Obiekty odpowiedzi

Odpowiedzi generalnie mają określony format z niewielkimi różnicami w zależności od sukcesu, niepowodzenia i wielu zasobów w porównaniu do pojedynczego zasobu. Wszystkie odpowiedzi zwracają bieżącą wersję API, unikalny ID żądania, wywoływany URL metody, odpowiednie parametry i Enum statusu obok kodu statusu HTTP.

Udane żądania zwracają właściwość data na najwyższym poziomie, podczas gdy niepowodzenia zwracają tablicę obiektów błędów.

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

Zasoby

Zasoby są zawsze zwracane w obiekcie data na najwyższym poziomie i zawierają id i type zasobu. Tam gdzie ma to zastosowanie, podpola są grupowane pod właściwością attributes, a odpowiednie linki pod właściwością links.

Przy zwracaniu wielu zasobów zwracana jest tablica elementów odpowiadająca powyższemu formatowi.

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

Błędy

Błędy są zawsze zwracane w tablicy pod właściwością errors na najwyższym poziomie.

Właściwość
title	Surowy komunikat błędu
detail	Czytelny komunikat błędu dotyczący tego konkretnego przypadku
code	Odpowiadający kod statusu HTTP