# Api introduction

Domain request model includes Api and socket(include WeChat socket)

| Type                            | URL                                                       |
| ------------------------------- | --------------------------------------------------------- |
| RESTful Api (api-host)          | <https://api-toilet.seeed.cc>                             |
| Web Socket (skt-host)           | [https://ws-toilet.seeed.cc](https://api-toilet.seeed.cc) |
| WeChat applet socket (skt-host) | wss\://ws-toilet.seeed.cc                                 |

The introduction of the RESTful, [click here](https://doc.api.sensecap.seeed.cc/doc/http-api-access-guides/http-methods)

The introduction to requests and responses, [click here](https://doc.api.sensecap.seeed.cc/doc/http-api-access-guides/untitled)

The introduction of  web socket:

* server use socket.io.
  * socket.io [doc-server](https://socket.io/docs/server-api)
  * socket.io [doc-client](https://socket.io/docs/client-api)

The introduction of the API call relationship

> 1. Get all WC position data for your organization or company via the API - The list of position
> 2. Get all WC cubicles data by the position ID, via the API - The list of cubicles
> 3. Keep long connection for real-time data of the cubicles or meeting rooms via the Socket

## Api - The list of positions

<mark style="color:blue;">`GET`</mark> `{api-host}/v1/lists/positions/:bloc`

Get a list of all the toilet positions in a company or organization.

#### Path Parameters

| Name | Type   | Description                                                                                |
| ---- | ------ | ------------------------------------------------------------------------------------------ |
| bloc | string | <p>the unique flag for the company or organization. <br>for example: bloc=361832720401</p> |

#### Query Parameters

| Name | Type   | Description                                                                                       |
| ---- | ------ | ------------------------------------------------------------------------------------------------- |
| type | string | <p>type=1 , get positions list of the WC.<br>type=2, get positions list of the meeting rooms.</p> |

{% tabs %}
{% tab title="200 " %}

```
{
    "code": "0",
    "data": [
        {
            "id": "32", //  position id, the unique id for the location of a toilet
            "company": "Seeed", // the name of company or organization
            "position": "国际E城G栋9楼" // the name of the toilet
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Api - The list of cubicles

<mark style="color:blue;">`GET`</mark> `{api-host}/v1/lists/cubicles/:position_id`

Get a list of all the toilet cubicles which the position selected.

#### Path Parameters

| Name         | Type   | Description                                                                            |
| ------------ | ------ | -------------------------------------------------------------------------------------- |
| position\_id | string | <p>the unique id from \<The list of positions> api.<br>for example: position\_id=1</p> |

{% tabs %}
{% tab title="200 " %}

```
{
    "code": "0",
    "data": [
        {
            "eui": "sd45fe32", // 设备编号
            "gender": "1", // 性别：1男，2女，3其它（如残疾等）
            "shape": "1", // 隔间马桶形状：1蹲位，2坐型，3其它
            "number": "1", // 隔间编号，如1号隔间
            "use_time": "91" // 单位秒，大于0表示正在使用多少秒，小于0表示空闲多少秒
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Api - The list of meeting rooms

<mark style="color:blue;">`GET`</mark> `{api-host}/v1/lists/meetingrooms/:position_id`

Get a list of all the meeting rooms which the position selected.\
A meeting room maybe includes more than one sensor.

#### Path Parameters

| Name         | Type   | Description                                                                            |
| ------------ | ------ | -------------------------------------------------------------------------------------- |
| position\_id | string | <p>the unique id from \<The list of positions> api.<br>for example: position\_id=2</p> |

{% tabs %}
{% tab title="200 " %}

```
{
    "code": "0",
    "data": [
        {
            "key": "5C8DB3C40626014921540C3581C16306", // 每个会议室有唯一key，该key可能包含多个sensor
            "shape": "3", // 会议室形状，1小会议室，2中型会议室，3大型会议室
            "number": "B区大会议室",
            "eui": [
                {
                    "eui": "6df54c4d",
                    "use_time": "-54637"
                }
            ]
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Socket - Get the real-time status (cubicles or meeting rooms)

<mark style="color:blue;">`GET`</mark> `{skt-api}/v1`

Get real-time status which the position selected.

#### Path Parameters

| Name | Type   | Description                                                          |
| ---- | ------ | -------------------------------------------------------------------- |
| rn   | string | <p>room name = position\_id, <br>for example:  the (client demo)</p> |

{% tabs %}
{% tab title="200 " %}

```javascript
[
  {
    "key": "5C8DB3C40626014921540C3581C16306", // 当eui属于会议室，会返回该key
    "eui": "sd45fe32", // 设备编号
	"use_time": "-1" // 时间秒，大于0使用时长，小于0空闲时长
  }
]
```

{% endtab %}
{% endtabs %}

> client demo (nodejs)
>
> ```javascript
> const io = require('socket.io-client')
>
> // room name
> // the room name is the position_id, get position_id from the api (https://toilet.doc.seeed.cc/ - The list of positions)
> let rn = process.argv[2] || 10
>
> // 客户端需要做好重连策略，如服务端重启服务后，需要客户端主动再连接服务端。
> const skt = io(`https://ws-toilet.seeed.cc/v1`, {
>   query: {
>     // 参数 token
>     token: 'toilet'
>   }
> })
>
> /**
>  * @event connect
>  */
> skt.on('connect', () => {
>   console.log('connect successfully, ', ' Socket ID: ', skt.id)
> })
>
> /**
>  * 加入房间，服务端消息是基于房间发送，加入房间后就能收到消息
>  * @event joinRoom
>  * @param rn: room name
>  * @callback status: err|true
>  */
> skt.emit('joinRoom', rn, function (status) {
>   if (status !== true) {
>     return
>   }
>
>   /**
>    * 离开房间（客户端需要保持长连接的时候，则不需要离开房间）
>    * @event leaveRoom
>    * @param rn: room name
>    * @function status: err|true
>    */
>   skt.emit('leaveRoom', rn, function (status) {
>     if (status !== true) {
>       return
>     }
>
>     // 关闭连接
>     skt.close()
>     skt.disconnect()
>   })
> })
>
> /**
>  * 最新的数据
>  * @event latestCubicle
>  */
> skt.on('latestCubicle', (data) => {
>   console.log('latest cubicle:', data)
> })
>
> /**
>  * 'transport error'
>  * 'server namespace disconnect'
>  */
> skt.on('disconnect', (reason) => {
>   skt.close()
>   console.log('disconnect', reason)
> })
>
> // normal message
> skt.on('message', (data) => {
>   console.log('message:', data)
> })
>
> skt.on('close', function (err) {
>   skt.close()
>   console.log('close', err)
> })
>
> skt.on('error', function (err) {
>   console.log('error', err)
> })
> ```

> If you have any questions, Please contact by the email to `kevin.yang@seeed.cc`