Giới thiệu

Quy ước

URL cơ sở cho tất cả các yêu cầu API là http://127.0.0.1:16038/api/v1. HTTPS có thể được thêm vào sau này.

SignalRGB API tuân theo phong cách RESTful ở nơi có thể. Sự khác biệt chính là thêm Hành động Post vào các tài nguyên khi áp dụng, thay vì API JSON-RPC phụ. Ví dụ: POST effect/{effectId}/apply.

Quy ước JSON

SignalRGB API ở nơi có thể được mô phỏng theo json:api và Google JSON Style Guide với các sửa đổi nhỏ.
- Kiểu media json:api được bỏ qua.
- Quan hệ json:api được bỏ qua.
Tất cả các đối tượng đều có ID liên kết. Chúng là duy nhất cho loại đối tượng, nhưng có thể không duy nhất qua tất cả các loại đối tượng.
Tên thuộc tính ở snake_case ở nơi có thể, với các ngoại lệ cho những thứ như thuộc tính người dùng của plugin/hiệu ứng, được lấy trực tiếp từ tệp plugin/hiệu ứng.

Đối tượng phản hồi

Các phản hồi thường tuân theo một cấu trúc nhất định với các biến thể nhỏ tùy thuộc vào thành công, lỗi và nhiều tài nguyên so với tài nguyên đơn lẻ. Tất cả các phản hồi trả về phiên bản API hiện tại, ID yêu cầu duy nhất, phương thức URL được gọi, tất cả các tham số liên quan và enum trạng thái bên cạnh mã trạng thái HTTP.

Các yêu cầu thành công trả về thuộc tính data ở cấp cao nhất, trong khi lỗi trả về mảng đối tượng lỗi.

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

Tài nguyên

Các tài nguyên luôn được trả về trong đối tượng data ở cấp cao nhất và chứa id và type của tài nguyên. Ở nơi áp dụng, các trường phụ được nhóm dưới thuộc tính attributes, và các liên kết liên quan dưới thuộc tính links.

Khi trả về nhiều tài nguyên, một mảng mục theo định dạng đã nêu ở trên được trả về.

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

Lỗi

Lỗi luôn được trả về trong một mảng dưới thuộc tính errors ở cấp cao nhất.

Thuộc tính
title	Thông báo lỗi chung
detail	Thông báo lỗi có thể đọc được cho sự kiện cụ thể này
code	Mã trạng thái HTTP tương ứng