[WIP] HTTP API 2.0

en/getting-started/program-the-robot.md

@@ -3,7 +3,7 @@
 Poppy robots are designed to be easily programmed. They are three main options presented here:
 * using [Snap!](#using-snap), a variant of Scratch the visual programming language,
 * using [Python](#using-python) and leveraging the power of the whole API,
-* through the  [REST API](#through-the-rest-api) which let you  interface Poppy robots with other devices or any programming language.
+* through the  [HTTP API](#through-the-http-api) which let you  interface Poppy robots with other devices, other software, or any programming language.
 
 >**Info** As for the rest of the project, all our libraries are open source and available on [GitHub](https://github.com/poppy-project).
 
@@ -41,22 +41,22 @@ jr.m3.goal_position = 30
 We are also big fan of the [Jupyter Project](http://jupyter.org) and notebooks. Notebooks are documents which contain both Python code and rich text elements like equations, pictures, videos. They can be edited from the Jupyter Web interface which allow users to program Poppy robots directly from a website hosted on the robot computer. We think that this is a powerful tool permitting the creation and sharing of live code, results visualizations and explanatory text combined in a single document.
 
 
- <img src="../img/logo/jupyter.png" alt="Jupyter Logo" width="100"> 
+ <img src="../img/logo/jupyter.png" alt="Jupyter Logo" width="100">
 
 Most of the tutorials, experiments or pedagogical activities that we and the community develop are available as notebooks.
 
 ![Notebook example](../img/notebook-example.png)
 
 > **Info** An updated gallery of notebooks can be found [here](../programming/notebooks.md). Contribtions welcomed!
 
-### Through the REST API
+### Through the HTTP API
 
-On top of the Snap_!_ and Python options, we wanted to provide another way of accessing and controlling your robot from any device or language. Poppy robots are providing a REST API. The most important features of the robot can be access through HTTP GET/POST requests.
+On top of the Snap_!_ and Python options, we wanted to provide a generic way of accessing and controlling your robot, from any device, software or language. Poppy robots are providing an [HTTP API](http://docs.pypot.apiary.io/). The most important features (motors, sensors, primitives) of the robot can be access through HTTP requests.
 
 From a more practical point of view, this allows you to:
 
+* Make your **robot interact with other connected devices** such as a smartphone, intelligent sensors, other robots...
+* **Design web apps** connected to your robot, such as the [monitor interface](https://github.com/poppy-project/poppy-monitor) (also a contribution!) or **interact with the robot from other software**: for instance from your twitter account.
 * **Write bridges to control Poppy robot in any language** (awesome contributors have already written [Matlab](https://github.com/joelortizsosa/Connection-Poppy-Matlab) and [Ruby](https://github.com/poppy-project/pypot/tree/master/samples/REST/ruby) wrappers).
-* **Design web apps** connected to your robot, such as the [monitor interface](https://github.com/poppy-project/poppy-monitor) (also a contribution!).
-* Make your **robot interact with other connected devices** such as a smartphone, intelligent sensors, or even your twitter account...
 
-> **Caution** The REST API is still a work in progress, will change and is clearly ill documented! For more information you can have a look [here](https://github.com/poppy-project/pypot/blob/master/REST-APIs.md) our on the [forum](https://forum.poppy-project.org). A well designed, stable and well documented REST API is expected for the next major software release.
+The documentation of the HTTP API can be found on http://docs.pypot.apiary.io/ Examples of requests and responses are provided. You can find more detailed and concrete examples of uses in the chapter [Use the HTTP API to control a robot](#use-the-http-api-to-interact-with-a-poppy-robot).

en/programming/rest.md

@@ -1,3 +1,127 @@
-# Use the REST API to control a Poppy Robot
+# Use the HTTP API to interact with a Poppy Robot
 
-> **Caution** This page is not currently written. Your help is welcome to fulfill it !
+## Introduction
+
+Poppy robots have been developed as an open platform. Their design is based on modularity, diversity and transparency. Another key feature in this direction is to allow for open communication so they can "talk" with other devices (IoT), or other softwares and languages.
+
+HTTP API are a great solution for this. The HTTP protocol is a standard used everywhere and can be easily accessed from any connected device and from the vast majority of existing languages.
+
+The Poppy robots are embedding a simple webserver (based on the framework [flask](http://flask.pocoo.org)) that let you interact with the robot through HTTP requests. For instance, assuming your robot is connected to the network and uses the hostname *poppy*, if you go with your favorite webbrowser to **http://poppy.local:6969/devices/m1/registers/present_position** you should see a JSON response indicating that in our case the motor *m1* is in position 0.0.
+```
+{
+  "register": {
+    "name": "present_position",
+    "value": 0.0
+  }
+}
+```
+
+On top of letting you retrieve current state of the robot, the HTTP API also allows you to send commands, start behaviors, etc... The entire list of existing possible requests is described in http://docs.pypot.apiary.io/ Examples of requests and responses are also given their.
+
+The communication between Poppy robots and Snap!, the monitor or the visualisator are all done using the HTTP API.
+
+## Start the HTTP API server
+
+Starting from pypot>=3.0 the webserver for the HTTP API is started by default when using a Poppy creature. Except if you manually disabled it, it is launched automatically when the robot starts. It is bind to the port *6969*. If you want to manually starts it to another port (let's say *4242*), you can use the following python code:
+
+```python
+from pypot.creatures import PoppyErgoJr
+
+jr = PoppyErgoJr(serve_http_api=True,  # True by default
+                 http_api_port=4242)
+```
+
+## Simple commands examples
+
+* To retrieve the state of a device: ```[GET] /devices/<device_name>/registers``` will give you something like:
+```{
+      "registers": {
+        "present_position": 60.3,
+        "present_speed": 1.2,
+        "present_load": 55.5,
+        "present_temperature": 123.4,
+        "angle_limits": {
+          "min": -30,
+          "max": 30
+        },
+        "led_color": "EECC44"
+      }
+}
+```
+
+* To modify the present position of a motor: #TODO:
+
+* To start a *dance* primitive: ```[GET] /primitives/dance/methods/start```
+
+## Expose a new device or a custom primitives
+
+The idea behind Poppy robot HTTP API is to be generic enough so all main features accessible from within your robot should also be directly accessible from the outside world.
+
+Mechanisms are provided so when you create a new device for your Poppy robot, or write a new behavior using a primitive they will be directly accessible with the HTTP API.
+
+For instance, let's assume you have written a primitive to make the Ergo Jr jump. In pseudo code this could look like this:
+
+```python
+from pypot.primitive import Primitive
+
+class Jump(Primitive):
+    def setup(self):
+        # making the Ergo jr ready to jump
+        self.speed = 0.5  # in m/s
+
+    def run(self):
+        # actually jump...
+
+    def teardown(self):
+        # rest a bit to avoid catching fire
+
+    def get_maximum_reached_height(self):
+        # return the maximum height reached by the robot
+```
+
+The basic methods and properties of your primitive will already be accessible via the HTTP API. If you attach it to the robot using the name *my_cool_jump*, you shoud see it in ```/primitives``` and you can start it via ```/primitives/my_cool_jump/methods/start```.
+
+Now, if you want to make the custom *speed* property and the *get_maximum_reached_height* method, you simply have to add two lines to your class definition:
+
+```python
+from pypot.primitive import Primitive
+
+class Jump(Primitive):
+    properties = Primitive.properties + ['speed']
+    methods = Primitive.methods + ['get_maximum_reached_height']
+
+    def setup(self):
+        # making the Ergo jr ready to jump
+        self.speed = 0.5  # in m/s
+
+    def run(self):
+        # actually jump...
+
+    def teardown(self):
+        # rest a bit to avoid catching fire
+
+    def get_maximum_reached_height(self):
+        # return the maximum height reached by the robot
+```
+
+If you request ```/primitives/my_cool_jump/properties```you should also see the *speed* properties now.
+
+Similarly, to expose registers of a device:
+
+```python
+
+class MyCoolHeightSensor(Sensor):
+    registers = Sensor.registers + ['height']
+
+    ...
+```
+
+## Des exemples concrets plus avancés
+
+## Controler un robot avec un autre robot
+
+* ça serait cool que les GET/PUT soient symétriques et qu'on puisse passer au PUT le résultat du GET simplement en transformant les present par des goal.
+
+## Robot qui tweet et qui follow twitter
+
+@damien