소개

규칙

모든 API 요청을 보내는 기본 URL은 http://127.0.0.1:16038/api/v1입니다. Https는 이후 버전에서 추가될 수 있습니다.

SignalRGB API는 가능한 한 RESTful 스타일을 따릅니다. 주요 차이점은 보조 JSON-RPC API 대신 해당하는 리소스에 _post actions_가 추가된 것입니다. 예: POST effect/{effectId}/apply.

JSON 규칙

SignalRGB API는 json:api 및 Google JSON Style Guide를 가능한 한 따르며 일부 변경 사항이 있습니다.
- json:api 미디어 타입은 생략됩니다.
- json:api relationships는 생략됩니다.
모든 객체에는 연관된 id가 있습니다. 이는 객체 유형 내에서 고유하지만 모든 객체 유형에 걸쳐 고유하지 않을 수 있습니다.
속성 이름은 플러그인/이펙트 파일에서 직접 가져온 Plugin/Effect 사용자 속성 등 예외를 제외하고 가능한 한 snake_case를 사용합니다.

응답 객체

응답은 성공, 실패, 다중 리소스 대 단일 리소스에 따라 약간의 차이가 있지만 일반적으로 특정 레이아웃을 따릅니다. 모든 응답은 현재 API 버전, 고유 요청 id, 호출된 메서드 URL, 관련 params, 그리고 HTTP 상태 코드 외에 status Enum을 반환합니다.

성공한 요청은 최상위 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 상태 코드