==============
RINOR Overview
==============

Use REST for test
=================
You can execute a REST request from a console using the *wget* command. 
For example you can run: ::

    $ wget -qO- http://127.0.0.1:40405/account/user/list

This will run the request and show you the results (thanks to the *-qO-* parameter).

Configuration section in /etc/domogik/domogik.cfg 
=================================================
In Domogik configuration file, there are several options about REST in **[rest]** section:

* rest_server_ip (default : 127.0.0.1) : ip of REST HTTP server 
* rest_server_port (default : 40405) : port of REST HTTP server
* rest_use_ssl (default : False) : use (True) or not (False) HTTPS instead of HTTP
* rest_ssl_certificate (default : empty) : path of certificate file (.pem)

How to use REST with SSL?
=========================
Generate certificate 
--------------------
First, generate a self-signed certificate compounded of a certificate and a private key for your REST server with the following command (both certificate and key are put in a single file : domogik.pem): ::

    $ openssl req -new -x509 -keyout domogik.pem -out domogik.pem -days 365 -nodes

This certificate is valid for one year. Adapt the *days* parameter (-days 365) to change this.

Configure REST
--------------
Then, set **rest_use_ssl** parameter to True and **rest_ssl_certificate** with the path to your certificate file.

Restart REST server.

Test it 
-------
If REST is on 127.0.0.1:40405, try a request on https://127.0.0.1:40405/ with your favorite browser. You should obtain something like: ::

    {
        "status" : "OK",
        "code" : 0,
        "description" : "None",
        "rest" : [
            {"Version" : "0.1"},
            {"Description" : "REST module is part of Domogik project. See http://trac.domogik.org/domogik/wiki/modules/REST.en for REST API documentation"},
            {"SSL" : "True"}
        ]
    }


If this is OK with **"SSL" : "True"**, it works :)

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 returnd:
    code = 204
    data = Empty

REST interacts with other Domogik parts
===========================================
.. image:: interactions-EN.png

How REST starts
===============
.. image:: startup-EN.png

How REST process an Url
=======================
.. image:: process-url-EN.png