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