Introduction

Attention

Les points de terminaison, les noms de propriétés, les valeurs et le comportement sont tous susceptibles d’être modifiés sans préavis pendant la maturation des composants internes de l’API.

Note

L’API locale SignalRGB nécessite SignalRGB Pro pour la plupart des points de terminaison. Les points de terminaison nécessitant un compte Pro retourneront une erreur 403 Forbidden si l’application en cours d’exécution n’a pas d’utilisateur connecté, ou si l’utilisateur connecté ne possède pas de compte SignalRGB Pro.

Conventions

L’URL de base pour envoyer toutes les requêtes API est http://127.0.0.1:16038/api/v1. Le support HTTPS pourra être ajouté ultérieurement.

L’API SignalRGB suit un style RESTful dans la mesure du possible. La principale différence est l’ajout d’actions post aux ressources, le cas échéant, en remplacement d’une API JSON-RPC secondaire. Par exemple : POST effect/{effectId}/apply.

Conventions JSON

• L’API SignalRGB s’inspire de json:api et du Google JSON Style Guide dans la mesure du possible, avec des modifications mineures.

  • Le type de média json:api est omis.
  • Les relations json:api sont omises.

• Tous les objets possèdent un identifiant associé. Ces identifiants sont uniques au type d’objet, mais peuvent ne pas être uniques pour l’ensemble des types d’objets.

• Les noms de propriétés sont en snake_case dans la mesure du possible, à l’exception des propriétés utilisateur de Plugin/Effect qui sont extraites directement du fichier plugin/effect.

Objets de réponse

Les réponses suivront généralement une structure spécifique avec des différences mineures selon le succès, l’échec, et selon qu’il s’agit de ressources multiples ou uniques. Toutes les réponses retourneront la version actuelle de l’API, un identifiant de requête unique, l’URL de méthode appelée, les paramètres pertinents, ainsi qu’un enum de statut en plus du code de statut HTTP.

Les requêtes réussies retourneront une propriété data de premier niveau, tandis que les échecs retourneront un tableau d’objets d’erreur.

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

Ressources

Les ressources seront toujours retournées à l’intérieur de l’objet data de premier niveau et contiendront l’id et le type de la ressource. Le cas échéant, les sous-champs seront regroupés sous une propriété attributes, et les liens pertinents sous une propriété links.

Dans le cas du retour de plusieurs ressources, un tableau d’éléments sera retourné selon le format ci-dessus.

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

Erreurs

Les erreurs seront toujours retournées dans un tableau sous une propriété errors de premier niveau.

Propriété
title	Message d’erreur approximatif
detail	Message d’erreur lisible par un humain concernant cet événement spécifique
code	Code de statut HTTP correspondant