مقدمة

الاصطلاحات

عنوان URL الأساسي لإرسال جميع طلبات API هو http://127.0.0.1:16038/api/v1. قد يُضاف دعم Https في وقت لاحق.

تتبع واجهة SignalRGB البرمجية أسلوب RESTful قدر الإمكان. الاختلاف الرئيسي هو إضافة إجراءات POST (post actions) إلى الموارد حيثما ينطبق ذلك، بدلًا من واجهة JSON-RPC ثانوية. على سبيل المثال POST effect/{effectId}/apply.

اصطلاحات JSON

تستند واجهة SignalRGB البرمجية إلى json:api ودليل أسلوب JSON من Google قدر الإمكان مع تغييرات طفيفة.
- يُحذف نوع الوسائط الخاص بـ json:api.
- تُحذف العلاقات (relationships) الخاصة بـ json:api
لكل كائن معرّف (id) مرتبط به. هذه المعرّفات فريدة ضمن نوع الكائن، لكنها قد لا تكون فريدة عبر جميع أنواع الكائنات.
تُكتب أسماء الخصائص بصيغة snake_case كلما أمكن، مع استثناءات لأشياء مثل خصائص المستخدم في الإضافات/التأثيرات التي تُسحب مباشرةً من ملف الإضافة/التأثير.

كائنات الاستجابة

تتبع الاستجابات عمومًا تخطيطًا محددًا مع اختلافات طفيفة بحسب النجاح أو الفشل، وبحسب ما إذا كانت تتعلق بموارد متعددة أو بمورد واحد. تُعيد جميع الاستجابات إصدار API الحالي، ومعرّف طلب فريدًا، وعنوان 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 المطابق