Pengenalan

Konvensyen

URL asas untuk semua permintaan API ialah http://127.0.0.1:16038/api/v1. HTTPS mungkin ditambah pada masa hadapan.

API SignalRGB mengikuti gaya RESTful sedapat mungkin. Perbezaan utama ialah penambahan Tindakan Post, yang ditambah kepada sumber di mana berkenaan, dan bukannya API JSON-RPC sekunder. Contohnya, POST effect/{effectId}/apply.

Konvensyen JSON

API SignalRGB mengikuti json:api dan Panduan Gaya JSON Google sedapat mungkin dengan perubahan kecil.
- Jenis media json:api ditinggalkan.
- Hubungan json:api ditinggalkan.
Semua objek mempunyai ID yang berkaitan. Ini adalah unik untuk jenis objek, tetapi mungkin tidak unik merentasi semua jenis objek.
Nama sifat adalah dalam snake_case sedapat mungkin, dengan pengecualian untuk perkara seperti sifat pengguna Plugin/Effect yang diambil terus dari fail Plugin/Effect.

Objek Tindak Balas

Tindak balas secara amnya mengikuti susun atur tertentu dengan perbezaan kecil bergantung pada kejayaan, ralat, dan berbilang berbanding sumber tunggal. Semua tindak balas mengembalikan versi API semasa, ID permintaan unik, URL kaedah yang dipanggil, semua parameter relevan, dan enum status di samping kod status HTTP.

Permintaan yang berjaya mengembalikan sifat data peringkat teratas, manakala ralat mengembalikan array objek ralat.

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

Sumber

Sumber sentiasa dikembalikan dalam objek data peringkat teratas dan mengandungi id dan type sumber. Di mana berkenaan, medan bawahan dikumpulkan di bawah sifat attributes dan pautan relevan di bawah sifat links.

Apabila mengembalikan berbilang sumber, array item dalam format yang disebutkan di atas dikembalikan.

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

Ralat

Ralat sentiasa dikembalikan dalam array di bawah sifat errors peringkat teratas.

Sifat
title	Mesej ralat kasar
detail	Mesej ralat boleh baca manusia untuk peristiwa khusus ini
code	Kod status HTTP yang sepadan