บทนำ

ข้อตกลง

Base URL สำหรับส่งคำขอ API ทั้งหมดคือ http://127.0.0.1:16038/api/v1 อาจมีการเพิ่ม Https ในภายหลัง

SignalRGB API ใช้รูปแบบ RESTful เท่าที่เป็นไปได้ ความแตกต่างหลักคือการเพิ่ม post actions ให้กับทรัพยากรในกรณีที่เหมาะสม แทนการใช้ JSON-RPC API แยกต่างหาก เช่น POST effect/{effectId}/apply

ข้อตกลงด้าน JSON

SignalRGB API อ้างอิงจาก json:api และ Google JSON Style Guide เท่าที่เป็นไปได้ โดยมีการเปลี่ยนแปลงเล็กน้อย
- ไม่ใช้ media type ของ json:api
- ไม่ใช้ relationships ของ json:api
ออบเจ็กต์ทั้งหมดมี id ที่เชื่อมโยงอยู่ id เหล่านี้ไม่ซ้ำกันภายในประเภทออบเจ็กต์เดียวกัน แต่อาจซ้ำกันได้ระหว่างประเภทออบเจ็กต์ที่ต่างกัน
ชื่อพร็อพเพอร์ตีจะใช้รูปแบบ snake_case เท่าที่เป็นไปได้ ยกเว้นสิ่งต่าง ๆ เช่น พร็อพเพอร์ตีผู้ใช้ของปลั๊กอิน/เอฟเฟกต์ ที่ดึงมาโดยตรงจากไฟล์ปลั๊กอิน/เอฟเฟกต์

ออบเจ็กต์การตอบกลับ

โดยทั่วไปการตอบกลับจะเป็นไปตามรูปแบบเฉพาะ โดยมีความแตกต่างเล็กน้อยตามการสำเร็จ การล้มเหลว และทรัพยากรแบบหลายรายการหรือรายการเดียว การตอบกลับทั้งหมดจะส่งคืนเวอร์ชัน API ปัจจุบัน, request id ที่ไม่ซ้ำกัน, URL ของเมธอดที่เรียก, พารามิเตอร์ที่เกี่ยวข้อง และ Enum สถานะ นอกเหนือจากรหัสสถานะ HTTP

คำขอที่สำเร็จจะส่งคืนพร็อพเพอร์ตี data ระดับบนสุด ในขณะที่คำขอที่ล้มเหลวจะส่งคืนอาร์เรย์ของออบเจ็กต์ข้อผิดพลาด

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

ทรัพยากร

ทรัพยากรจะถูกส่งคืนภายในออบเจ็กต์ data ระดับบนสุดเสมอ และจะมี id และ type ของทรัพยากร ในกรณีที่เหมาะสม ฟิลด์ย่อยจะถูกจัดกลุ่มไว้ใต้พร็อพเพอร์ตี attributes และลิงก์ที่เกี่ยวข้องจะอยู่ใต้พร็อพเพอร์ตี links

ในกรณีที่ส่งคืนทรัพยากรหลายรายการ จะส่งคืนอาร์เรย์ของรายการที่ตรงกับรูปแบบข้างต้น

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

ข้อผิดพลาด

ข้อผิดพลาดจะถูกส่งคืนในรูปแบบอาร์เรย์ใต้พร็อพเพอร์ตี errors ระดับบนสุดเสมอ

พร็อพเพอร์ตี
title	ข้อความแสดงข้อผิดพลาดโดยสรุป
detail	ข้อความแสดงข้อผิดพลาดที่มนุษย์อ่านเข้าใจได้เกี่ยวกับเหตุการณ์นี้โดยเฉพาะ
code	รหัสสถานะ HTTP ที่ตรงกัน