APIDesc.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "LightsControllerAPI | v1",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://[::]:5042"
    }
  ],
  "paths": {
    "/rooms": {
      "get": {
        "tags": [
          "Rooms"
        ],
        "summary": "Retrieve all rooms with their floor information",
        "description": "Returns all rooms, including their names and floor numbers. This data can be cached for efficiency",
        "operationId": "GetRooms",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Room"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/rooms/{roomId}": {
      "get": {
        "tags": [
          "Rooms"
        ],
        "summary": "Retrieve a room’s name, floor, and unique ID",
        "description": "A room is representing a group of lights where the 'RoomId' is the same. Each room has a unique Name and Floor number associated with the lights with the same RoomId.  if a command is addressing the room without specifying the light name then all the lights located in the room should be receiving the command. Remember all the rooms for future use",
        "operationId": "GetRoom",
        "parameters": [
          {
            "name": "roomId",
            "in": "path",
            "description": "Unique identifier for the room",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/lights": {
      "get": {
        "tags": [
          "Rooms",
          "Lights"
        ],
        "summary": "Returns all lights with their states, capabilities, and room details",
        "description": "Returns a list of all available lights including their states, capabilities, and RoomId that referrences the room where it resides Name and Floor",
        "operationId": "GetLights",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Light"
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Rooms",
          "Lights"
        ],
        "summary": "Batch update multiple lights with new states, colors, or brightness",
        "description": "Allows batch updates for multiple lights, adjusting their states, colors, or brightness levels as specified. Returns a list of lights affected by the operation along with their updated values",
        "operationId": "UpdateLights",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PatchResponse"
                }
              }
            }
          },
          "207": {
            "description": "Multi-Status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PatchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        }
      }
    },
    "/lights/{id}": {
      "get": {
        "tags": [
          "Rooms",
          "Lights"
        ],
        "summary": "Retrieve a single light",
        "description": "Returns details of a specific light by its ID: LightId",
        "operationId": "GetLight",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Light"
                }
              }
            }
          },
          "404": {
            "description": "Not Found"
          }
        }
      }
    },
    "/lights/floor/{floor}": {
      "get": {
        "tags": [
          "Rooms",
          "Lights"
        ],
        "summary": "Fetch lights by floor, including states and capabilities",
        "description": "Fetches all lights on a specified floor, detailing their IDs: LightId, current states and capabilities",
        "operationId": "GetLightsByFloor",
        "parameters": [
          {
            "name": "floor",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Light"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Capabilities": {
        "type": "object",
        "properties": {
          "canChangeColor": {
            "type": "boolean",
            "description": "Indicates whether the light supports color changes. If True, Color can be adjusted. If False, Color remains fixed and cannot be altered",
            "default": false
          },
          "isDimmable": {
            "type": "boolean",
            "description": "Indicates whether the light supports brightness adjustment. If True, Brightness can be adjusted. If False, brightness remains fixed and cannot be altered.",
            "default": false
          }
        },
        "description": "Light capabilities such as dimming and color-changing support",
        "default": null
      },
      "Light": {
        "required": [
          "lightId",
          "name",
          "roomId",
          "state"
        ],
        "type": "object",
        "properties": {
          "lightId": {
            "maximum": 2147483647,
            "minimum": 0,
            "type": "integer",
            "description": "Unique identifier for the light",
            "format": "int32"
          },
          "name": {
            "maxLength": 100,
            "minLength": 0,
            "type": "string",
            "description": "Name of the light"
          },
          "roomId": {
            "maximum": 2147483647,
            "minimum": 0,
            "type": "integer",
            "description": "Room ID where the light is located",
            "format": "int32"
          },
          "state": {
            "$ref": "#/components/schemas/LightState"
          },
          "color": {
            "pattern": "^[0-9A-Fa-f]{6}$",
            "type": "string",
            "description": "Color of the light in hex format",
            "default": "FFFFFF"
          },
          "brightness": {
            "maximum": 100,
            "minimum": 0,
            "type": "integer",
            "description": "Brightness of the light (0-100)",
            "format": "int32",
            "default": 100
          },
          "capabilities": {
            "$ref": "#/components/schemas/Capabilities"
          }
        }
      },
      "LightState": {
        "enum": [
          "Off",
          "On"
        ],
        "description": "State of the light: On or Off",
        "default": "Off"
      },
      "LightUpdateRequest": {
        "required": [
          "lightId"
        ],
        "type": "object",
        "properties": {
          "lightId": {
            "minLength": 1,
            "type": "integer",
            "description": "light LightId to update",
            "format": "int32"
          },
          "state": {
            "type": "string",
            "description": "Turns a light (\"On\" or \"Off\")",
            "nullable": true
          },
          "color": {
            "pattern": "^[0-9A-Fa-f]{6}$",
            "type": "string",
            "description": "New color in hex format",
            "nullable": true
          },
          "brightness": {
            "maximum": 100,
            "minimum": 0,
            "type": "integer",
            "description": "New brightness level (0-100)",
            "format": "int32",
            "nullable": true
          }
        }
      },
      "PatchRequest": {
        "type": "object",
        "properties": {
          "lightUpdates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LightUpdateRequest"
            }
          }
        }
      },
      "PatchResponse": {
        "required": [
          "results"
        ],
        "type": "object",
        "properties": {
          "successCount": {
            "type": "integer",
            "description": "Number of successfully updated lights.",
            "format": "int32"
          },
          "failureCount": {
            "type": "integer",
            "description": "Number of failed updates.",
            "format": "int32"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UpdateLightResponse"
            },
            "description": "List of update results."
          }
        }
      },
      "Room": {
        "required": [
          "roomId",
          "name"
        ],
        "type": "object",
        "properties": {
          "roomId": {
            "maximum": 2147483647,
            "minimum": 0,
            "type": "integer",
            "description": "RoomId: Unique identifier for the room",
            "format": "int32"
          },
          "name": {
            "maxLength": 100,
            "minLength": 0,
            "type": "string",
            "description": "Room Name"
          },
          "floor": {
            "maximum": 500,
            "minimum": -5,
            "type": "integer",
            "description": "Floor number where the Room is located",
            "format": "int32",
            "default": 1
          }
        }
      },
      "UpdateLightResponse": {
        "required": [
          "lightId",
          "status",
          "error"
        ],
        "type": "object",
        "properties": {
          "lightId": {
            "type": "integer",
            "description": "Unique Id of the light that was updated",
            "format": "int32"
          },
          "status": {
            "type": "string",
            "description": "Indicates whether the update was successful ('success' or 'failed')"
          },
          "error": {
            "type": "string",
            "description": "Detailed error message if the update status is failed",
            "nullable": true
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Rooms"
    },
    {
      "name": "Lights"
    }
  ]
}