REST Overview¶
Todo
- description
- pictures/charts about startup, url processing, MQ dialogs
- …
Overview¶
REST is a web server which handle request in REST format. It is used by the user interfaces to get informations about devices, sensor history, send commands, …
How to test REST requests¶
wget method¶
You can execute a REST GET request from a console using the wget command. For example you can run:
$ wget -qO- http://127.0.0.1:40405/device/1
This will run the request and show you the results (thanks to the -qO- parameter).
FireFox RESTClient¶
This Firefox plugin will allow you to send easily POST, DELETE and other requests.
Install FF plugin from here: https://addons.mozilla.org/en-us/firefox/addon/restclient/.
Lauch with Tools > RestClient
In this example we will use RESTClient for testing POST url
In the RESTClient interface menu go in Headers > Custom Header and :
- Create a header with name: ‘Content-Type’, value: ‘application/x-www-form-urlencoded’
- You may tick Save to favorites for the next time
Next, go back on the RESTClient main interface and fill the fields. Example for creating a new device:
- method: ‘POST’, url: ‘http://xxxxx:40405/device/’
- body : name=device%20name&type=plugin&id=diskfree&host=darkstar&description=desc&reference=ref&device_type=diskfree.disk_usage
Then, click on Send
Configuration section in /etc/domogik/domogik.cfg¶
In Domogik configuration file, there are several options about REST in [rest] section:
- interfaces : the network interface to use : eth0, lo, …
- port : the port for the rest service : 40405
- use_ssl : use ssl (True) or not (False)
- ssl_certificate : The ssl .crt file
- ssl_key : The ssl .key file
- clean_json : display a clean json result (indentation, carriage return) (True) or a raw result (False)
How to use REST with SSL?¶
Please read the installation documentation.
Status¶
Rest uses http status codes to identify the error:
- get:
code = 200
data = the returned data from the get request (json)
delete:
code = 204
data = empty
put (update):
code = 200
data = the updated object (json)
post (create):
code = 201
data = the new object (json)
error:
code = 400
data = {msg: “string describing the error”}
action ok, no content returned:
code = 204
data = Empty