Skip to content
This repository has been archived by the owner on Jul 15, 2023. It is now read-only.

Latest commit

 

History

History
647 lines (595 loc) · 15.6 KB

Device.md

File metadata and controls

647 lines (595 loc) · 15.6 KB

Device

A Device is used either to refer to a toilet, a set of these or even an entire room.

The Device API allows the administrator to create, view and manage all the registered devices.

All the vocabulary used in the devices representations is described here.

Device API contents

List devices

List the registered devices.

GET /devices

Parameters

Name Type In Required Description
accept string header no Setting to application/vnd.qrreport+json is recommended.
page integer query no Page number of the results to fetch. Default: 1

Response

Status: 200 OK 
{
    "class": [ "device", "collection" ],
    "properties": {
        "pageIndex": 1,
        "pageMaxSize": 10,
        "collectionSize": 1
    },
    "entities": [
        {
            "class": [ "device" ],
            "rel": [ "item" ],
            "properties": {
                "id": 1,
                "name": "Toilet1",
                "category": "water",
                "state": "active",
                "timestamp": "2022-05-12 20:54:32452"
            },
            "links": [
                { "rel": [ "self" ], "href": "/devices/1" }
            ]
        }
    ],
    "actions": [
        {
            "name": "create-device",
            "title": "Create a device",
            "method": "POST",
            "href": "/devices",
            "type": "application/json",
            "properties": [
                { "name": "name", "type": "string" },
                { "name": "category", "type": "number" }
            ]
        }
    ],
    "links": [
        { "rel": [ "self" ], "href": "/devices?page=1" },
        { "rel": [ "pagination" ], "href": "/devices{?page}", "templated": true }
    ]
}
Status: 400 Bad Request
Status: 401 Unauthorized
Status: 403 Forbidden
Status: 404 Not Found

Create a device

Create a new device.

POST /devices

Parameters:

Name Type In Required Description
accept string header no Setting to application/vnd.qrreport+json is recommended.
content-type string header yes Set to application/json.
name string body yes Unique device name.
category number body yes Category identifier for the device.

Request body example

{
    "name": "Toilet1",
    "category": 1
}

Response

Status: 201 Created
Location: /devices/{deviceId}
{
    "class": [ "device" ],
    "properties": {
        "id": 1,
        "name": "Toilet1",
        "category": "water",
        "state": "active",
        "timestamp": "2022-05-12 20:54:32452"
    },
    "links": [
        { "rel": [ "self" ], "href": "/devices/1" }
    ]
}
Status: 400 Bad Request
Status: 401 Unauthorized
Status: 403 Forbidden
Status: 409 Conflict
  • type: unique-constraint

Get a device

Get a specific device.

GET /devices/{deviceId}

Parameters

Name Type In Required Description
deviceId integer path yes Identifier of the device.
accept string header no Setting to application/vnd.qrreport+json is recommended.

Response

Status: 200 OK 
{
    "class": [ "device" ],
    "properties": {
        "id": 1,
        "name": "Toilet 1",
        "category": "water",
        "state": "active",
        "timestamp": "2022-05-12 20:54:32452"
    },
    "entities": [
        {
            "class": [ "anomaly", "collection" ],
            "rel": [ "device-anomalies" ],
            "properties": {
                "pageIndex": 0,
                "pageMaxSize": 10,
                "collectionSize": 1
            },
            "entities": [
                {
                    "class": [ "anomaly" ],
                    "rel": [ "item" ],
                    "properties": {
                        "id": 1,
                        "anomaly": "Broken toilet"
                    },
                    "actions": [ 
                        {
                            "name": "update-anomaly",
                            "title": "Update anomaly",
                            "method": "PUT",
                            "href": "/devices/1/anomalies/1",
                            "type": "application/json",
                            "properties": [
                                { "name": "anomaly", "type": "string" }
                            ]
                        },
                        {
                            "name": "delete-anomaly",
                            "title": "Delete anomaly",
                            "method": "DELETE",
                            "href": "/devices/1/anomalies/1"
                        }
                    ],
                    "links": [
                        { "rel": [ "self" ], "href": "/devices/1/anomalies/1" }
                    ]
                }
            ],
            "actions": [
                {
                    "name": "create-anomaly",
                    "title": "Create new anomaly",
                    "method": "POST",
                    "href": "/devices/1/anomalies",
                    "type": "application/json",
                    "properties": [
                        { "name": "anomaly", "type": "string" }
                    ]
                }
            ],
            "links": [
                { "rel": [ "self" ], "href": "/devices/1/anomalies?page=1"},
                { "rel": [ "pagination" ], "href": "/devices/1/anomalies{?page}"}
            ]
        }
    ],
    "actions": [
        {
            "name": "deactivate-device",
            "title": "Deactivate device",
            "method": "POST",
            "href": "/devices/1"
        },
        {
            "name": "update-device",
            "title": "Update device",
            "method": "PUT",
            "href": "/devices/1",
            "type": "application/json",
            "properties": [
                { "name": "name", "type": "string" }
            ]
        },
        {
            "name": "change-device-category",
            "title": "Change device category",
            "method": "PUT",
            "href": "/devices/1",
            "type": "application/json",
            "properties": [
                { "name": "category", "type": "number" }
            ]
        }
    ],
    "links": [
        { "rel": [ "self" ], "href": "/devices/1" },
        { "rel": [ "devices" ], "href": "/devices" }
    ]
}
Status: 400 Bad Request
Status: 401 Unauthorized
Status: 403 Forbidden
Status: 404 Not Found

Update a device

Update the name of a specific device.

PUT /device/{deviceId}

Parameters

Name Type In Required Description
deviceId integer path yes Identifier of the device.
accept string header no Setting to application/vnd.qrreport+json is recommended.
content-type string header yes Set to application/json.
name string body yes New unique name for the device.

Response

Status: 200 OK 
{
    "class": [ "device" ],
    "properties": {
        "id": 1,
        "name": "Toilet1",
        "category": "water",
        "state": "active",
        "timestamp": "2022-05-12 20:54:32452"
    },
    "links": [
        { "rel": [ "self" ], "href": "/devices/1" }
    ]
}
Status: 400 Bad Request
Status: 401 Unauthorized
Status: 403 Forbidden
Status: 404 Not Found
Status: 409 Conflict
  • types: unique-constraint, inactive-entity

Change a device category

Change the device category.

PUT /device/{deviceId}/category

Parameters

Name Type In Required Description
deviceId integer path yes Identifier of the device.
accept string header no Setting to application/vnd.qrreport+json is recommended.
content-type string header yes Set to application/json.
category number body yes New category for the device.

Response

Status: 200 OK 
{
    "class": [ "device" ],
    "properties": {
        "id": 1,
        "name": "Toilet1",
        "category": "canalization",
        "state": "active",
        "timestamp": "2022-05-12 20:54:32452"
    },
    "links": [
        { "rel": [ "self" ], "href": "/devices/1" }
    ]
}
Status: 400 Bad Request
Status: 401 Unauthorized
Status: 403 Forbidden
Status: 404 Not Found
Status: 409 Conflict
  • type: inactive-entity

Deactivate a device

Deactivate a specific device.

POST /devices/{deviceId}/deactivate

Parameters

Name Type In Required Description
deviceId integer path yes Identifier of the device.
accept string header no Setting to application/vnd.qrreport+json is recommended.

Response

Status: 200 OK 
{
    "class": [ "device" ],
    "properties": {
        "id": 1,
        "name": "Toilet 1",
        "category": "water",
        "state": "inactive",
        "timestamp": "2022-05-12 20:54:32452"
    },
    "links": [
        { "rel": [ "self" ], "href": "/devices/1" },
        { "rel": [ "devices" ], "href": "/devices" }
    ]
}
Status: 400 Bad Request
Status: 401 Unauthorized
Status: 403 Forbidden
Status: 404 Not Found

Activate a device

Activate a specific device.

POST /devices/{deviceId}/activate

Parameters

Name Type In Required Description
deviceId integer path yes Identifier of the device.
accept string header no Setting to application/vnd.qrreport+json is recommended.

Response

Status: 200 OK 
{
    "class": [ "device" ],
    "properties": {
        "id": 1,
        "name": "Toilet 1",
        "category": "water",
        "state": "active",
        "timestamp": "2022-05-14 14:23:56788"
    },
    "links": [
        { "rel": [ "self" ], "href": "/devices/1" }
    ]
}
Status: 400 Bad Request
Status: 401 Unauthorized
Status: 403 Forbidden
Status: 404 Not Found

List room devices

List the devices of a specific room.

GET /companies/{companyId}/buildings/{buildingId}/rooms/{roomId}/devices

Parameters

Name Type In Required Description
companyId integer path yes Identifier of the company.
buildingId integer path yes Identifier of the building.
roomId integer path yes Identifier of the room.
accept string header no Setting to application/vnd.qrreport+json is recommended.

Response

Status: 200 OK 
{
    "class": [ "device", "collection" ],
    "properties": {
        "pageIndex": 0,
        "pageMaxSize": 10,
        "collectionSize": 1
    },
    "entities": [
        {
            "class": [ "device" ],
            "rel": [ "item" ],
            "properties": {
                "id": 1,
                "name": "Toilet 1",
                "category": "water",
                "state": "active",
                "timestamp": "2022-05-14 14:23:56788"
            },
            "links": [
                { "rel": [ "self" ], "href": "/companies/1/buildings/1/rooms/1/devices/1" }
            ]
        }
    ],
    "actions": [
        {
            "name": "add-room-device",
            "title": "Add device",
            "method": "POST",
            "href": "/companies/1/buildings/1/rooms/1/devices",
            "type": "application/json",
            "properties": [
                { "name": "device", "type": "number", "possibleValues": { "href": "/devices" } }
            ]
        }
    ],
    "links": [
        { "rel": [ "self" ], "href": "/companies/1/buildings/1/rooms/1/devices?page=1" },
        { "rel": [ "pagination" ], "href": "/companies/1/buildings/1/rooms/1/devices{?page}" }
    ]
}
Status: 400 Bad Request
Status: 401 Unauthorized
Status: 403 Forbidden
Status: 404 Not Found

Get a room device

Get the room device with the associated QR Code.

GET /companies/{companyId}/buildings/{buildingId}/rooms/{roomId}/devices/{deviceId}

Parameters

Name Type In Required Description
companyId integer path yes Identifier of the company.
buildingId integer path yes Identifier of the building.
roomId integer path yes Identifier of the room.
deviceId integer path yes Identifier of the device.
accept string header no Setting to application/vnd.qrreport+json is recommended.

Response

Status: 200 OK 
{
    "class": [ "device" ],
    "properties": {
        "id": 1,
        "name": "Toilet1",
        "category": "water",
        "state": "active"
    },
    "entities": [
        {
            "class": [ "qrcode" ],
            "rel": [ "room-device-qrcode" ],
            "properties": {
                "qrcode": "/company/1/building/1/rooms/1/devices/1/qrcode"
            },
            "actions": [
                {
                    "name": "generate-new-qrcode",
                    "title": "Generate new QR Code",
                    "method": "POST",
                    "href": "/company/1/building/1/rooms/1/devices/1/qrcode"
                }
            ]
        }
    ],
    "actions": [
        {
            "name": "remove-room-device",
            "title": "Remove device",
            "method": "DELETE",
            "href": "/company/1/building/1/rooms/1/devices/1"
        }
    ],
    "links": [
        { "rel": [ "self" ], "href": "/company/1/building/1/rooms/1/devices/1" },
        { "rel": [ "room" ], "href": "/company/1/building/1/rooms/1" }
    ]
}
Status: 400 Bad Request
Status: 401 Unauthorized
Status: 403 Forbidden
Status: 404 Not Found

Device representations vocabulary

Name Type Description
id number Unique and stable identifier of the device. Must be greater than 0.
name string Unique name of the device.
category string Name of the device category .
state string Current state of the device, the possible values are active or inactive.
timestamp string Timestamp of the moment that the device state changed to the current state.

Domain specific link relations

Name Description
room-device-qrcode QR Code associated to the room device.
device-anomalies Set of anomalies associated to the device.
devices Resource with the representation of all the devices registered in the system.

The documentation for the media-type, classes, standard link relations and generic errors used in the representations are described here.

The vocabulary about the categories can be consulted here.