Skip to content

API

Jump to bottom
Oliver Pennery edited this page May 11, 2021 · 28 revisions

API Page

  1. Auth
    1. Check
    2. Login
  2. Building
    1. GET
    2. POST
    3. PUT
    4. DEL
  3. Room
    1. GET
    2. POST
    3. PUT
    4. DEL
  4. Sensor
    1. GET
    2. POST
    3. PUT
    4. DEL
  5. Reading
    1. GET
    2. DEL

Authorisation

Syntax Data Type Description
Username String Username
Password String Password

url/api/v1/auth

Check

GET: url/api/v1/auth

with a bearer token header

'Authorization': 'Bearer ' + token

Will return 403 if token is bad

Login

Login to get a token

curl -X POST url/api/v1/auth -H 'Content-type:application/json' -d '{"username": "foo", "password": "bar"}'

Will return a bearer token

token: yJhbGciOiJIUzI1N.....

Building

Syntax Data Type Description
ID Long Primary Key
Name String Name of building
Links Object links to self and children

GET:

Retrieve a List of Buildings

GET: url/api/v1/buildings

[
  {
    "id": 0,
    "name": "MVB",
    "links": {
      "self": "http://foo/api/v1/buildings/0",
      "children": "http://foo/api/v1/buildings/0/rooms"
    }
  },
  {
    "id": 1,
    "name": "Queens",
    "links": {
      "self": "http://foo/api/v1/buildings/1",
      "children": "http://foo/api/v1/buildings/1/rooms"
    }
  }
]

Get a Building

GET: url/api/v1/buildings/:id

{
    "id": 1,
    "links": {
        "self": "http://foo/api/v1/buildings/1",
        "child": "http://foo/api/v1/buildings/1/rooms"
    },
    "name": "MVB"
}

Show all kids

/?kids=true

will return the whole tree for the building including readings

POST

Add a building

curl -X POST url/api/v1/buildings -H 'Content-type:application/json' -d '{"name": "foo"}'

returns the newly created building

{"id":3,"links":{"self":"","child":""},"name":"foo"}

PUT

Edit a building

$ curl -X PUT url/api/v1/buildings/3 -H 'Content-type:application/json' -d '{"name": "bar"}'

returns the edited building

{"id":3,"links":{"child":"","self":""},"name":"bar"}

Delete

Delete a building

curl -X DELETE url/api/v1/buildings/1

Room

Syntax Data Type Description
ID Int Primary Key
Name String Name of room
Links Object links to self and children

There are 2 allowed ways to query rooms

url/api/v1/rooms/:id

or

url/api/v1/buildings/:id/rooms/:id

NOTE, which url you query with will change the links to that format!

GET

Retrieve a List of Rooms

GET: url/api/v1/buildings/:id/rooms

if you have the building id it will only show rooms within the building otherwise it will list all rooms

[
  {
    "id": 0,
    "name": "1.1",
    "links": {
      "self": "http://foo/api/v1/buildings/:id/rooms/0",
      "children": "http://foo/api/v1/buildings/:id/rooms/0/sensors"
    }
  },
  {
    "id": 1,
    "name": "2.3",
    "links": {
      "self": "http://foo/api/v1/buildings/:id/rooms/1",
      "children": "http://foo/api/v1/buildings/:id/rooms/1/sensors"
    }
  }
]

Get a Room

GET: url/api/v1/rooms/:id

or

GET: url/api/v1/buildings/:id/rooms/:id

{
    "id": 1,
    "links": {
        "child": "http://foo/api/v1/buildings/1/rooms/1/sensors",
        "self": "http://foo/api/v1/buildings/1/rooms/1"
    },
    "name": "1.1"
}

Show all kids

/?kids=true

will return the whole tree for the room including readings

POST

Add a room

curl -X POST url/api/v1/buildings/1/rooms -H 'Content-type:application/json' -d '{"name": "foo"}'

Note if you use the other syntax for querying, you have to add the building id to the json like curl -X POST url/api/v1/rooms -H 'Content-type:application/json' -d '{"name": "foo", "building":{"id: 1}}'

returns the newly created rrom

{"id":3,"links":{"self":"","child":""},"name":"foo"}

PUT

Edit a room

$ curl -X PUT url/api/v1/buildings/1/rooms/3 -H 'Content-type:application/json' -d '{"name": "bar"}'

returns the edited room

{"id":3,"links":{"child":"","self":""},"name":"bar"}

Delete

Delete a room

curl -X DELETE url/api/v1/buildings/1/rooms/3

Sensor

Syntax Data Type Description
ID Int Primary Key
Description String Description of device
Links Object links to self and children

There are 2 allowed ways to query rooms

url/api/v1/sensors/:id

or

url/api/v1/buildings/:id/rooms/:id/sensors/:id

NOTE, which url you query with will change the links to that format!

GET

Retrieve a List of sensors

GET: url/api/v1/buildings/:id/rooms/sensors

if you have the room id it will only show sensors within the room otherwise it will list all sensors

[
  {  
  "id": 12600,  
  "description": "Back of room a",  
  "links": {
      "self": "http://foo/api/v1/buildings/:id/rooms/:id/sensors/10",
      "children": "http://foo/api/v1/buildings/:id/rooms/:id/sensors/10/data"
    }  
  },  
  {  
    "id": 9858,  
    "description": "Front of room b",  
    "links": {
      "self": "http://foo/api/v1/buildings/:id/rooms/:id/sensors/10",
      "children": "http://foo/api/v1/buildings/:id/rooms/:id/sensors/10/data"
    }  
  }
]

Get a Sensor

url/api/v1/buildings/:id/rooms/:id/sensors/:id

POST

Add a sensor

curl -X POST url/api/v1/buildings/1/rooms/1/sensors -H 'Content-type:application/json' -d '{"id": 10358, "name": "foo"}'

returns the newly created sensor

{"id":10358,"links":{"self":"","child":""},"name":"foo"}

PUT

Edit a sensor

$ curl -X PUT url/api/v1/buildings/1/rooms/1/sensors/10358 -H 'Content-type:application/json' -d '{"name": "bar"}'

returns the edited sensor

{"id":10358,"links":{"child":"","self":""},"name":"bar"}

Delete

Delete a sensor

curl -X DELETE url/api/v1/sensors/10358

Reading

Syntax Data Type Description
ID Int Primary Key
Date Date Date and time of reading
CO2 Float Amount of CO2

url/api/v1/reading/:id

or

url/api/v1/buildings/:id/rooms/:id/sensors/:id/readings/:id

GET

Get all readings from a sensor

GET: url/api/v1/buildings/:id/rooms/:id/sensors/:id/readings/list

GET: url/api/v1/:id/readings

[
    {
        "id": 1,
        "date": "2021-04-22T17:05:34Z",
        "co2": 1603
    },
    {
        "id": 2,
        "date": "2021-04-22T17:06:34Z",
        "co2": 1556
    }
]

Get the latest reading

GET: url/api/v1/buildings/:id/rooms/:id/sensors/:id/readings/latest

GET: url/api/v1/:id/readings/latest

[
    {
        "id": 45,
        "date": "2021-04-22T17:49:36Z",
        "co2": 1742
    }
]

Get the latest x readings

GET: url/api/v1/buildings/:id/rooms/:id/sensors/:id/readings/latest?amt=x

GET: url/api/v1/:id/readings/latest?amt=x

[
    {
        "id": 45,
        "date": "2021-04-22T17:49:36Z",
        "co2": 1742
    },
    {
        "id": 44,
        "date": "2021-04-22T17:48:36Z",
        "co2": 1748
    }
]

Delete

Delete a reading

curl -X DELETE url/api/v1/reading/:id

Clone this wiki locally