<markdown>
URI Definition
===============================================================================

Basic Specification
-------------------------------------------------------------------------------

Network host of Control Server is normally **"localhost (127.0.0.1)"**.
Its port is decided by `port` property written in **config.json**. (Default value is 17264.)

The server provides REST API.
Thus, anyone can use each resource and command using following syntax.

```
http://<HOST>:<PORT>/<VERSION>/<INSTANCE>/...(/<METHOD>)
```

`<VERSION>` is string of API version.
Basically its keeps pace to major version of the application.
(For-instance: In **ControlServer_Win_v2.0.1**, `<VERSION>` is **v2**.)

### Returned JSON Format When Get a Resource

When you create GET request, the server returns JSON like below.

```json
{
    "resource": <RESOURCE_NAME:string>,
    "data": <DATA:json>
}
```

### Returned JSON Format When a Command Runs

When you create HTTP request (not GET) or call each command, the server returns JSON like below.

```json
{
    "resource": <RESOURCE_NAME:string>,
    "data": {
        "command": <COMMAND_NAME:string>,
        "result": <RESULT:boolean>
    }
}
```


Resources List
-------------------------------------------------------------------------------

### Command-line Stream (cmdstream)

Could be gotten WebSocket based stream resource that controls PLEN.

Sending command name and each argument with **/ (slash)** as separator,
you can call directly commands implemented by Python.
([See also...](https://github.com/plenprojectcompany/plen-ControlServer/blob/master/control_server/drivers/abstract.py))

```javascript
var socket = new WebSocket('ws://localhost:17264/v2/cmdstream');

socket.send('<METHOD_NAME>/<PARAM_0>/<PARAM_1>/...');
```

Returned value is stringified returned value on Python runtime environment.

### Motion (motions)

Could be gotten motion resource that defines PLEN's movement.
Please set slot number you want to access to `<SLOT:integer>`.

```
http://localhost:17264/v2/motions/<SLOT:integer>
```

|HTTP Request|Operation                                                   |
|:-----------|:-----------------------------------------------------------|
|**GET**     |Get a motion resource.                                      |
|**DELETE**  |Delete a motion resource. (Overwrite empty motion actually.)|
|**PUT**     |Overwrite a motion resource.                                |

```
http://localhost:17264/v2/motions/<SLOT:integer>/play
http://localhost:17264/v2/motions/stop
```

|Commands|Operation     |
|:-------|:-------------|
|**play**|Play a motion.|
|**stop**|Stop a motion.|

### Version Information (version)

Could be gotten version information resource.

```
http://localhost:17264/v2/version
```

|HTTP Request|Operation                       |
|:-----------|:-------------------------------|
|**GET**     |Get version information of PLEN.|

### Construction Information of the Server (metadata)

Could be gotten server information resources below.

- API version
- Required firmware version of PLEN

```
http://localhost:17264/v2/metadata
```

|HTTP Request|Operation                                  |
|:-----------|:------------------------------------------|
|**GET**     |Get construction information of the server.|


Commands List (Doable by Itself)
-------------------------------------------------------------------------------

### Connect to PLEN (connect)

```
http://localhost:17264/v2/connect
```

### Disconnect from PLEN (disconnect)

```
http://localhost:17264/v2/disconnect
```
</markdown>