Pengenalan

Konvensi

URL dasar untuk mengirim semua permintaan API adalah http://127.0.0.1:16038/api/v1. Https mungkin ditambahkan di kemudian hari.

API SignalRGB mengikuti gaya RESTful di mana mungkin. Perbedaan utama adalah penambahan post actions yang ditambahkan ke resource di mana berlaku sebagai pengganti API JSON-RPC sekunder. yaitu POST effect/{effectId}/apply.

Konvensi JSON

API SignalRGB mengacu pada json:api dan Panduan Gaya JSON Google di mana mungkin dengan perubahan kecil.
- Tipe media json:api dihilangkan.
- Hubungan json:api dihilangkan
Semua objek memiliki id yang terkait. Ini unik untuk tipe objek, tetapi mungkin tidak unik di semua tipe objek.
Nama properti dalam snake_case bila memungkinkan dengan pengecualian untuk hal-hal seperti properti pengguna Plugin/Effect yang diambil langsung dari file plugin/effect.

Objek Respons

Respons umumnya akan mengikuti tata letak tertentu dengan perbedaan kecil berdasarkan keberhasilan, kegagalan, dan beberapa vs sumber daya tunggal. Semua respons akan mengembalikan versi API saat ini, id permintaan unik, URL metode yang dipanggil, parameter yang relevan, dan Enum status selain kode status HTTP.

Permintaan yang berhasil akan mengembalikan properti data tingkat atas, sementara kegagalan akan mengembalikan array objek error.

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

Sumber daya akan selalu dikembalikan di dalam objek data tingkat atas, dan akan berisi id dan type dari sumber daya. Jika berlaku, subfield akan dikelompokkan di bawah properti attributes, dan tautan relevan di bawah properti links.

Dalam kasus mengembalikan beberapa sumber daya, array item akan dikembalikan sesuai format di atas.

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

Error

Error akan selalu dikembalikan dalam array di bawah properti errors tingkat atas.

Properti
title	Pesan error kasar
detail	Pesan error yang dapat dibaca manusia tentang peristiwa spesifik ini
code	Kode status HTTP yang cocok