apiary.apib

FORMAT: 1A
HOST: http://netdb.udc-service.io:10150

# SMART ROOM API Document

Smart Room back-end API

API-version: 0.3.0

# Group User Management

## Login [/login]

Used to login platform.

### Login [POST]
<pre>
curl -X "POST" "http://netdb.udc-service.io:10150/login" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "account": "test",
  "password": "test"
}'
</pre>

+ Request (application/json)
    + Attributes
        + account: `test` (string, required) - Login Account
        + password: `test` (string, required) - Account's Password

+ Response 200 (application/json)
    + Attributes
        + token: `429ec8b19da2f4af86fe010e4c4850e051e419de25d06c846e352eba46036c72` - Authentication Bearer Token

+ Response 401 (application/json)
    + Attributes
        + error: `Unauthorized Access` - error message

## User [/user]

User Account Management

### Get User [GET]

Get user data.

<pre>
curl "http://netdb.udc-service.io:10150/user" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR'
</pre>

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Authentication Bearer Token

+ Response 200 (application/json)
    + Attributes
        + uuid: `31ca7c42-a125-11eb-99de-8c8590002bb6` (string) - user uuid
        + account: `ACCOUNT` (string) - account name

+ Response 400 (application/json)
    + Attributes
        + message: `error` - error message

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

### Create User [POST]

Create user account.

<pre>
curl -X "POST" "http://netdb.udc-service.io:10150/user" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "account": "USER",
  "password": "PASSWD"
}'
</pre>

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Authentication Bearer Token

    + Attributes
        + account: `TEST123` (string, required) - user account
        + password: `2020-01-01` (string, required) - user password

+ Response 200 (application/json)
    + Attributes
        + message: `Account created` - success
        + token: `7d41361fbfe0ff2e7d5598f8c7021a45f300467260776fd07b1bb35cbd42126f` - Bearer token

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

+ Response 409 (application/json)
    + Attributes
        + error: `Account already exists` - error message

### Update User [PUT]

Update user password.

<pre>
curl -X "PUT" "http://netdb.udc-service.io:10150/user" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "original_password": "OLDPASSWD",
  "new_password": "NEWPASSWD"
}'
</pre>

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Authentication Bearer Token

    + Attributes
        + original_password: `OLDPASSWD` (string, required) - original password
        + new_password: `NEWPASSWD` (string, required) - new password

+ Response 200 (application/json)
    + Attributes
        + message: `Accept` - success
        + token: `1d8de44e322da45bea3c36efb89e8b1d04e1f9ba8105839b80f061b3f2ebc2bf` - new token

+ Response 400 (application/json)
    + Attributes
        + message: `Reject` - original password error

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

# Group Device Management

## Sensor [/sensor]

Sensor Management

### Get Sensors [GET /sensor{?name,room,location,device_type}]

Get sensors.

<pre>
curl "http://netdb.udc-service.io:10150/sensor?name=Sensor1&room=Room1&location=floor1&device_type=DHT11" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR'
</pre>

+ Parameters
    + name: `Sensor1` (string) - sensor name
    + room: `Room1` (string) - room name
    + location: `floor1` (string) - sensor location
    + device_type: `DHT11` (string) - sensor device type

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Authentication Bearer Token

+ Response 200 (application/json)
    + Attributes
        + uuid: `31ca7c42-a125-11eb-99de-8c8590002bb6` (string) - sensor uuid
        + name: `Sensor1` (string) - sensor name
        + room: `Room1` (string) - room name
        + location: `floor1` (string) - sensor location
        + device_type: `DHT11` (string) - sensor device type
        + created: `Wed, 17 Feb 2021 13:43:26 GMT` (string) - sensor create time

+ Response 400 (application/json)
    + Attributes
        + message: `error` - error message

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

### Create Sensor [POST]

Create sensor.

<pre>
curl -X "POST" "http://netdb.udc-service.io:10150/sensor" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "name": "Sensor2",
  "room": "Room2",
  "location": "floor2",
  "device_type": "DHT22"
}'

</pre>

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Authentication Bearer Token

    + Attributes
        + name: `Sensor2` (string, required) - sensor name
        + room: `Room2` (string, required) - room name
        + location: `floor2` (string, required) - sensor location
        + device_type: `DHT22` (string, required) - sensor device type

+ Response 200 (application/json)
    + Attributes
        + message: `Success` - success

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

## Gateway [/gateway]

Gateway (data uploader) management

### Create Gateway [POST]

Create Gateway.

<pre>
curl -X "POST" "http://netdb.udc-service.io:10150/gateway" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "name": "GW"
}'

</pre>

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Gateway Authentication Bearer Token

    + Attributes
        + name: `GW` (string, required) - gateway name
        + token: `d43b634aff32f2ab0bb670d94307570955057c03747f37556c4e334b7072c68c` (string) - gateway token

+ Response 200 (application/json)
    + Attributes
        + message: `success` - success
        + token: `d43b634aff32f2ab0bb670d94307570955057c03747f37556c4e334b7072c68c` - gateway token

+ Response 400 (application/json)
    + Attributes
        + error: `Failed` - error message

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

## Device [/device]

Controllable device management

### Create Device [POST]

Create AC Device.

<pre>
curl -X "POST" "http://netdb.udc-service.io:10150/device" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "name": "AC",
  "room": "room1",
  "location": "loc_N",
  "url": "localhost:7000"
}'

</pre>

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Authentication Bearer Token

    + Attributes
        + name: `AC` (string, required) - device name
        + room: `room1` (string, required) - room name
        + location: `loc_N` (string, required) - location name
        + url: `localhost:7000` (string, required) - device socket url
        + token: `d43b634aff32f2ab0bb670d94307570955057c03747f37556c4e334b7072c68c` (string) - device token

+ Response 200 (application/json)
    + Attributes
        + message: `Success` - success

+ Response 400 (application/json)
    + Attributes
        + error: `Failed` - error message

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

# Group Data

## Sensor Data [/sensor_data]

Sensor Data

### Get Sensor Data [GET /sensor_data{?name}]

Get sensors.

<pre>
curl "http://netdb.udc-service.io:10150/sensor_data?name=Sensor1" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR'
</pre>

+ Parameters
    + name: `Sensor1` (string) - sensor name

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Authentication Bearer Token

+ Response 200 (application/json)
    + Attributes
        + temperature: 25.6 (number, required) - temperature
        + humidity: 70 (number, required) - humidity

+ Response 400 (application/json)
    + Attributes
        + message: `Failed` - error message

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

### Upload Sensor Data [POST]

Upload sensor Data.

<pre>
curl -X "POST" "http://netdb.udc-service.io:10150/sensor_data" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "temperature": 25.6,
  "humidity": 70,
  "sensor": "Sensor1"
}'

</pre>

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Gateway Authentication Bearer Token

    + Attributes
        + temperature: 25.6 (number, required) - temperature
        + humidity: 70 (number, required) - humidity
        + sensor: `Sensor1` (string, required) - sensor name

+ Response 200 (application/json)
    + Attributes
        + message: `Success` - success

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

## Meter Data [/meter_data]

Meter Data

### Get Meter Data [GET /meter_data{?start_time,end_time,interval}]

Get meter data.

<pre>
curl "http://netdb.udc-service.io:10150/meter_data?" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR'
</pre>

+ Parameters
    + `start_time`: `2021-01-01T00:00:00` (string) - start time
    + `end_time`: `2021-01-02T00:00:00` (string) - end time
    + `interval`: `day` (string) - interval (hour, day)

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Authentication Bearer Token

+ Response 200 (application/json)
    + Attributes
        + overview - outdoor temperature and total power consumption
            + temp - time, temp pair
                + `2021-01-01T00:00:00`: 25.5
                + `2021-01-01T00:01:00`: 25.6
                + `2021-01-01T00:02:00`: 26.1
                + `2021-01-01T00:03:00`: 26.6
            + power - time, power consumption pair
                + `2021-01-01T00:00:00`: 200.1
                + `2021-01-01T00:01:00`: 300.2
                + `2021-01-01T00:02:00`: 1000.0
                + `2021-01-01T00:03:00`: 1050.6
        + `602` - 608 temperature & power consumption
            + temp - time, temp pair
                + `2021-01-01T00:00:00`: 25.5
                + `2021-01-01T00:01:00`: 25.6
                + `2021-01-01T00:02:00`: 26.1
                + `2021-01-01T00:03:00`: 26.6
            + power - time, power consumption pair
                + `2021-01-01T00:00:00`: 200.1
                + `2021-01-01T00:01:00`: 300.2
                + `2021-01-01T00:02:00`: 1000.0
                + `2021-01-01T00:03:00`: 1050.6
        + `608` - 602 temperature & power consumption
            + temp - time, temp pair
                + `2021-01-01T00:00:00`: 25.5
                + `2021-01-01T00:01:00`: 25.6
                + `2021-01-01T00:02:00`: 26.1
                + `2021-01-01T00:03:00`: 26.6
            + power - time, power consumption pair
                + `2021-01-01T00:00:00`: 200.1
                + `2021-01-01T00:01:00`: 300.2
                + `2021-01-01T00:02:00`: 1000.0
                + `2021-01-01T00:03:00`: 1050.6

+ Response 400 (application/json)
    + Attributes
        + message: `Failed` - error message

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

### Upload Meter Data [POST]

Upload Meter Data.

<pre>
curl -X "POST" "http://netdb.udc-service.io:10150/meter_data" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "voltage": 218.204,
  "current": 0.139,
  "power": 8.638,
  "total_consumption": 17.368,
  "sensor": "SmartMeter"
}'

</pre>

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Gateway Authentication Bearer Token

    + Attributes
        + voltage: 218.204 (number, required) - voltage
        + current: 0.139 (number, required) - current
        + power: 8.638 (number, required) - power
        + total_consumption: 17.368 (number, required) - total_consumption
        + sensor: `SmartMeter` (string, required) - sensor name

+ Response 200 (application/json)
    + Attributes
        + message: `Success` - success

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message


## Control Record [/control]

Control Record

### Get Latest Control Record [GET /control{?device}]

Get latest control record.

<pre>
curl "http://netdb.udc-service.io:10150/control?device=AC1" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR'
</pre>

+ Parameters
    + device: `AC1` (string) - device name

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Authentication Bearer Token

+ Response 200 (application/json)
    + Attributes
        + status: `25C` (string, required) - device status

+ Response 400 (application/json)
    + Attributes
        + message: `Failed` - error message

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

### Control Device [POST]

Send Control Command.

<pre>
curl -X "POST" "http://netdb.udc-service.io:10150/control" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "device": "AC1",
  "command": "25C"
}'

</pre>

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Gateway Authentication Bearer Token

    + Attributes
        + device: AC1 (string, required) - device name
        + command: 25C (string, required) - command

+ Response 200 (application/json)
    + Attributes
        + message: `Success` - success

+ Response 400 (application/json)
    + Attributes
        + error: `Device Not Found` - error message

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

+ Response 500 (application/json)
    + Attributes
        + error: `Control Success, Save Failed` - error message

## Pir Records [/pir_records]

Motion Sensor Data

### Upload Pir Data [POST]

Upload Pir Data.

<pre>
curl -X "POST" "http://netdb.udc-service.io:10150/pir_records" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "created": "2021-08-12T07:56:34.158830",
  "device_id": "TEST:DEVICE",
  "status": "0"
}'

</pre>

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Authentication Bearer Token

    + Attributes
        + device_id: `TEST:DEVICE` (string, required) - device Mac address
        + created: `2021-08-12T07:56:34.158830` (string, required) - data timestamp
        + status: `0` (number, required) - pir status
        + token: `d43b634aff32f2ab0bb670d94307570955057c03747f37556c4e334b7072c68c` (string) - device token

+ Response 200 (application/json)
    + Attributes
        + message: `Success` - success

+ Response 400 (application/json)
    + Attributes
        + error: `Failed` - error message

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

# Group Front-end

## Appliances Data [/appliance]

Get Appliances Latest State

### Get Appliances Data [GET /appliance{?name,room,location}]

Get appliances latest status.

<pre>
curl "http://netdb.udc-service.io:10150/appliance?room=608" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR'
</pre>

+ Parameters
    + name: `Sensor1` (string) - sensor name
    + room: `602` (string) - sensor room
    + location: `VLDB` (string) - sensor location

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Authentication Bearer Token

+ Response 200 (application/json)
    + Attributes (array, fixed-type)
        + (object)
            + `device_type`: `thermo_sensor` (string) - device type
            + name: `Sensor1` (string) - device name
            + room: `602` (string) - device room
            + time: `2021-04-23 20:48:05` (string) - data upadte time
            + data
                + temperature: 25.6 (number) - temperature
                + humidity: 70 (number) - humidity
        + (object)
            + `device_type`: `ac` (string) - device type
            + name: `AC1` (string) - device name
            + room: `602` (string) - device room
            + time: `2021-04-23 20:48:05` (string) - data upadte time
            + data
                + status: `OFF` (string) - latest status (ON/OFF)
                + mode: `off` (string) - latest mode (cool/fan/off)
                + temp: `22C` (string) - previous non off command

+ Response 400 (application/json)
    + Attributes
        + message: `Failed` - error message

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

## Meter Data Overview [/meter_data/overview]


### Get Meter Data Overview [GET]

[Front-end] Get meter data overview.

<pre>
curl "http://netdb.udc-service.io:10150/meter_data/overview" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR'
</pre>

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Authentication Bearer Token

+ Response 200 (application/json)
    + Attributes
        + total: 100.0 (number, required) - total power consumption
        + data
            + 602: 60.0 (number, required) - 602 power consumption
            + 608: 40.0 (number, required) - 608 power consumption

+ Response 400 (application/json)
    + Attributes
        + message: `Failed` - error message

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message

# Group Service

## Service Health check [/health]

### GET Service Check [GET]

Return basic response, used to check service status

<pre>
curl "http://netdb.udc-service.io:10150/health"
</pre>

+ Response 200 (application/json)
    + Attributes
        + message: `Success` - Service responses successfully

## Raw Meter Data [/raw/meter_data]

Raw Meter Data

### Get Raw Meter Data [GET /raw/meter_data{?sensor,start,end}]

Get Raw meter data.

<pre>
curl "http://netdb.udc-service.io:10150/meter_data?" \
     -H 'Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR'
</pre>

+ Parameters
    + `sensor`: `sensor name` (string) - sensor name
    + `start`: `2021-01-01T00:00:00` (string) - start time
    + `end`: `2021-01-02T00:00:00` (string) - end time

+ Request (application/json)
    + Headers

            Authorization: Bearer OXBiogjCfdKb7m9CEOPhpbjjv0n5OtfltzgMJbSxbP7jVFY8XUNzHqkGidDumQSR - Authentication Bearer Token

+ Response 200 (application/json)
    + Attributes
        + created: 2021-01-01T00:00:00 (string, required) - Raw data created time
        + power: 10 (number, required) - Power (Watt)

+ Response 400 (application/json)
    + Attributes
        + message: `Failed` - error message

+ Response 401 (application/json)
    + Attributes
        + error: `Access Denied` - error message