version 1.0
This is a Nodejs (TypeScript 3.x) implementation of REST API for Airduino project on PostgreSQL database.
It implements following resources:
- devices
- devicetypes
- owners
- firmwares
- configurations
- configurationitems
- regiontypes
- regions
- data
- telemetry
- translations
- dictionary
- filters
- filter items
It uses cache for all enabled device's apikeys.
Also, the plan is to implement REST API for resources:
- events
- rules
- actions
Also, plan is to implement session based APIs, SSL and user privileges.
This is server side subproject of Airduino project - air quality measurement based on arduino MCU models. Edge telemetry is on Air Quality Monitor
There are scripts in package.json for easy development.
First ensure clean .js, and .sql folders in /dist folder with clean script:
npm run clean
After cleaning, copy all .sql files:
npm run copy:assets
In development watch and copy in (/src) folder for any changes for .sql files:
npm run watch:assets
Finally, run transpiling on every change of .ts file from development folder (/src) into .js in distribution folder (/dist):
npm run dev
Rules marked with EX are experimental and available only for specific resources.
POST - search and create new objects
- search by id
- create single object
- create multiple objects EX
- copy single objects EX
- copy multiple objects EX
PUT - update existing objects
- update multiple objects by id
- update multiple objects by values EX
DELETE - delete existing objects
- delete multiple objects by id
GET - fields, order and limit in query EX
POST
| url | JSON in body | response type | description |
|---|---|---|---|
| / | { ids } | search objects | |
| / | { ... } | /full, /id, /fast | create single object |
| /multiple | [ {}, {}... ] | /full, /id, /fast | create multiple objects |
| /copy | { ... } | /full, /id, /fast | copy single object |
| /clone | { ids, values } | /full, /id, /fast | copy multiple objects |
PUT
| url | JSON in body | response type | description |
|---|---|---|---|
| / | { ids, values } | /full, /id, /fast | update multiple objects by id |
| /multiple | [ {}, {}... ] | /full, /id, /fast | update multiple objects by values |
DELETE
| url | JSON in body | response type | description |
|---|---|---|---|
| / | { ids } | delete multiple objects by id |
Retrieves all objects with id in ids attribute.
JSON in body
{
"ids": [
{ }, // id of object 1
{ }, // id of object 2
{ }, // id of object 3
]
}
POST <base url><resource>
Request contains values to create an object with. Other values may be auto generated on back-end side.
JSON in body
{ // values of new object
...
}
There're three version for response type:
POST <base url><resource>/full
The reponse contains all the values of the created object.
POST <base url><resource>/id
The reponse contains only id value(s) of the created object.
POST <base url><resource>/fast
The reponse contains only status of the created object ("success": true | false).
If error occurs during creating new object, the response contains error message and false as "success" status.
Create multiple objects with requested values. Similary as in single object creation, request contains object values for creating multiple objects. Objects' values are in array of object's values.
JSON in body
[
{ }, // values of new object 1
{ }, // values of new object 2
{ }, // values of new object 3
...
]
There're three version for response type:
POST <base url><resource>/multiple/full
The reponse contains values of created objects, also in array of values.
POST <base url><resource>/multiple/id
The reponse contains only id value(s) of the created objects in array.
POST <base url><resource>/multiple/fast
The reponse contains only status of the created objects ("status": "ok" | "error") in array, and number of created object in result.created property.
In the following example creation of the first object failed with false in "status" property and error object contains code, detail, and constraint.
To copy an object request should contain id of a object to copy. In addition to the object id, other values that we want to have in the new copied object can be specified.
JSON in body
{ // id of the existing object to copy and values of new object
...
}
There're three version for response type:
POST <base url><resource>/copy/full
The reponse contains values of created object.
In this example request contains object id only.
The reponse contains object id with values of new object.
POST <base url><resource>/copy/id
The reponse contains only id value(s) of the created object.
POST <base url><resource>/copy/fast
The reponse contains only status of the created object ("status": "ok" | "error") in array, and number of created object in result.created property.
To copy multiple objects request should contain id's of objects to copy in "ids" property as array. In "values" property are all values (incuding id attibutes) that we want to have in the new copied objects.
JSON in body
{
"ids": [ // id's of the existing objects to copy
{},
{},
{},
],
"values": { // common values of new copied objects (may include properties of object's id)
...
}
}
There're three version for response type:
POST <base url><resource>/clone/full
The reponse contains values of created object.
POST <base url><resource>/clone/id
The reponse contains only id value(s) of the created object.
POST <base url><resource>/clone/fast
The reponse contains only status of the created object ("status": "ok" | "error") in array, and number of created object in result.created property.
To update multiple objects by id's request should contain id's of objects to update in "ids" property as array. In "values" property are all values (may incude id attibutes) that we want to have in the updated objects.
JSON in body
{
"ids": [ // id's of the existing objects to update
{},
{},
{},
],
"values": { // common values of updated objects (may include properties of object's id)
...
}
}
There're three version for response type:
PUT <base url><resource>/full
The reponse contains values of updated object.
PUT <base url><resource>/id
The reponse contains only id value(s) of the updated object.
PUT <base url><resource>/fast
The reponse contains only status of the updated object ("success": true | false), and number of updated objects in data.updated property.
To update multiple objects by values request should contain array of values of objects including object id to update. It recognizes properties of object id to retrieve object to update and properties of other object values to update these values.
JSON in body
[
{ }, // values of new object 1
{ }, // values of new object 2
{ }, // values of new object 3
...
]
There're three version for response type:
PUT <base url><resource>/multiple/full
The reponse contains values of updated objects in array.
PUT <base url><resource>/multiple/id
The reponse contains only id value(s) of the updated objects in array.
PUT <base url><resource>/multiple/fast
The reponse contains only status of the updated object ("success": true | false), and number of updated objects in data.updated property.
To delete multiple objects request should contain id's of objects to delete in "ids" property as array.
DELETE <base url><resource>
As some objects are not found, data.deleted property in response has number of successfully deleted objects (without error).
To retrieve only specific fields, query should have 'fields' in request's url as:
fields=<list of fields>
example:
fields=id,name
equivalent to:
fields=[id,name]
or
fields[]=id&fields[]=name
Sorting objects by field or fields, query should have 'order' in request's url as:
If field name has '-' (minus, dash) as name prefix then sorting is defined as descending by that field
order=<list of fields>
example:
order=id,-name
equivalent to:
order=[id,-name]
or
order[]=id&order[]=-name
To limitg number of objects, query should have 'limit' in request's url as:
limit=<maximum number of objects>
example:
limit=5
All query keywords (fields, order and limit) can be combined with each other.
