智能家居云平台API文档

更新日期：2014-06-01

基本说明

1、所有对用户的信息、设备、传感器、数据点的操作都需要验证APIKEY，请在HTTP请求（http request）的头部（header）添加APIKEY字段，并附加相应地值。

如：Apikey: 1a39ad4c87ba09ef861ead97f010df7b

2、接口的URL由HOST和URI共同组成。其中URL，Universal Resource Location，统一资源定位符；URI，Universal Resource Identifier，统一资源标识符；HOST，服务器IP地址+端口号。

URI与URL的区别：

URI用于标记资源；

URL提供了找到该资源的方法，且包含了URI，可以说URL=HOST+URI；

在HTTP请求中，是没有URL的，只有URI和HOST，其中URI包含在请求的第一行。

3、云平台测试服务器地址与账号：

云平台服务器地址（HOST）：218.244.138.146:8000

云平台测试用账号及密码：linpcloud + 1234

4、请求成功与失败的标识：以HTTP响应码来标识请求成功与失败；以200为成功的标识，400为云平台系统的错误标识，其它错误参考HTTP协议；返回信息以及错误提示信息均以JSON格式传回，置于info键下。

5、HTTP响应：正常的系统输出和系统已捕捉的错误，都是以JSON格式字符串返回，即：Content-Type: application/json

服务器（Apache或Nginx）与编程环境（PHP）的错误，根据环境的配置返回响应的数据，这是云平台系统以外的错误，不会以JSON格式返回错误信息。客户端应根据响应的HTTP相应码给出响应的错误信息。

API接口及说明

一、用户类

1、  用户登录

使用用户名和密码进行登录，登录成功返回用户ID和APIKEY，用于后续操作。

请求

方法：POST

URI：/api/login

参数：

请求正文示例：

username=<username>&password=<password>

响应

返回值：关键的用户信息

参数：

响应正文实例：

{

    "info": "Login Success",

    "userid": "10000",

    "username": "linpcloud",

    "apikey": "1a39ad4c87ba09ef861ead97f010df7b"

}

2、  获取用户信息

获取个人用户信息。

请求

方法：GET

URI：/api/user

参数：无

响应

返回值：JSON格式的用户信息

参数：

响应正文实例：

{

    "id": "10000",

    "username": "linpcloud",

    "password": "81dc9bdb52d04dc20036dbd8313ed055",

    "email": "linpcloud@linpcloud.com",

    "token": "1234567890",

    "token_exptime": "0",

    "status": "1",

    "regtime": "0",

    "apikey": "1a39ad4c87ba09ef861ead97f010df7b",

    "about": "linpcloud test user"

}

3、  修改用户信息

4、  获取APIKEY

5、  更换APIKEY

二、设备类

1、  创建设备

根据所填信息，创建一个新的设备。

请求

方法：POST

URI：/api/devices

参数：

请求正文示例：

name=device_instance&tags=tags_instance&locate=Wuhan&about=This+is+a+example+device

响应

返回值：新创建的设备的ID

参数：

响应正文示例：

{

    "device_id": 10007

}

2、  获取设备列表

获取该用户下所有的设备信息。

请求

方法：GET

URI：/api/devices

参数：无

响应

返回值：JSON对象数组

参数：

响应正文示例：

[

    {

        "id": "10006",

        "name": "device from Postman",

        "tags": "any tags?",

        "about": "This is a device created by Postman",

        "locate": "Wuhan",

        "user_id": "10000",

        "create_time": "1399717930",

        "update_time": "1399717930",

        "status": "1"

    },

    {

        "id": "10007",

        "name": "示例设备",

        "tags": "示例标签",

        "about": "这是示例设备",

        "locate": "武汉",

        "user_id": "10000",

        "create_time": "1399738659",

        "update_time": "1399738659",

        "status": "1"

    }

]

3、  获取设备信息

获取某个具体设备的详细信息。

请求

方法：GET

URI：/api/device/<device_id>

参数：

响应

返回值：JSON格式的设备信息

参数：

返回正文示例：

{

    "id": "10007",

    "name": "示例设备",

    "tags": "示例标签",

    "about": "这是示例设备",

    "locate": "武汉",

    "user_id": "10000",

    "create_time": "1399738659",

    "update_time": "1399738659",

    "status": "1"

}

4、  修改设备信息

先获取设备信息，再进行少量修改。

请求

方法：PUT

URI：/api/device/<device_id>

参数：

响应

返回值：修改成功或失败的信息

响应示例：

{

    "info": "update info success"

}

5、  删除设备

删除某个具体设备。

请求

方法：DELETE

URI：/api/device/<device_id>

参数：

响应

返回值：成功或失败的信息

响应示例：

{

    "info": "delete success",

    "device_id": "10007"

}

三、传感器类

1、  添加传感器

根据所填信息，创建一个新的传感器。

请求

方法：POST

URI：/api/sensors

参数：

响应

返回值：新创建的传感器的ID

参数：

响应正文示例：

{

    "sensor_id": 10004

}

2、  获取传感器列表

获取某个设备下所属的所有传感器的信息，返回一个JSON对象数组。

请求

方法：GET

URI：/api/sensors/<device_id>

参数：

响应

参数：见获取传感器信息

响应正文示例：

[

    {

        "id": "100004",

        "name": "传感器实例",

        "type": "1",

        "tags": "标签",

        "about": "这是一个示例",

        "device_id": "10007",

        "last_update": "1399740484",

        "last_data": null,

        "status": "1"

    }

]

3、  获取传感器信息

获取某个指定的传感器的信息，后续可用于修改信息。

请求

方法：GET

URI：/api/sensor/<sensor_id>

参数：

响应

返回值：JSON格式的对象，内容为传感器的信息

参数：

响应实例：

{

    "id": "100004",

    "name": "传感器实例",

    "type": "1",

    "tags": "标签",

    "about": "这是一个示例",

    "device_id": "10007",

    "last_update": "1399740484",

    "last_data": null,

    "status": "1"

}

4、  修改传感器信息

先获取传感器信息，再修改其基础的信息，如同类型以及所属设备这样的字段一般是不允许更改的。

请求

方法：PUT

URI：/api/sensor/<sensor_id>

参数：

响应

返回值：成功或失败的信息

响应实例：

{

    "info": "sensor `100004` update success"

}

5、  删除传感器

删除某个具体的传感器，（或许会添加回收功能）

请求

方法：DELETE

URI：/api/sensor/<sensor_id>

参数：

响应

返回值：删除成功或失败的信息

响应实例：

{

    "info": "delete sensor `100004` success"

}

四、数据点类

1、  上传数据

为指定的传感器创建一个数据点（上传一个数据）。

请求

方法：POST

URI：/api/datapoint

参数：

响应

返回值：添加成功或失败的信息

响应实例：

{

    "info": "create datapoint success",

    "datapoint_id": 1044

}

2、  获取数据

获取某个传感器的最新数据（last_data）。

请求

方法：GET

URI：/api/datapoint/<sensor_id>

参数：

响应

返回值：传感器最新数据

响应实例：

{

    "sensor_id": "100005",

    "timestamp": "1401553001",

    "value": "123456"

}

3、  批量上传数据（适用于网关）

批量上传某个设备下传感器的数据，并激活该设备（设置设备的最后活动时间，通过判断这个值来确定设备是否在线）。

请求

方法：POST

URI：/api/datapoints/<device_id>

参数：

请求示例：json=[{"sensor_id":100005,"value":"000000"}]

urlencode之后：json=%5B%7B%22sensor_id%22%3A100005%2C%22value%22%3A%22000000%22%7D%5D

响应

返回值：添加成功或失败的信息

响应实例：

{

    "info": "Datapoint created success"

}

4、批量获取数据（设计用于控制终端）

用于获取某个设备下所有传感器的最新数据。

请求

方法：GET

URI：/api/datapoints/device/<device_id>

参数：

响应

返回值：JSON格式的对象数组，数组每一项包含一个传感器的最新数据。

响应实例：

[

    {

        "id": "100005",

        "last_update": "1401553452",

        "last_data": "000000"

    },

    {

        "id": "100006",

        "last_update": "1400502382",

        "last_data": "30%"

    },

    {

        "id": "100007",

        "last_update": "1400502382",

        "last_data": "1"

    },

    {

        "id": "100009",

        "last_update": "1400595887",

        "last_data": "hello world"

    }

]

5、获取历史数据

用于获取某个传感器的历史数据。

请求

方法：GET

URI：/api/datapoints/sensor/<sensor_id>

参数：

所有参数在不设置时，云平台会使用默认值：开始时间为现在时间的一小时前，结束时间为当前的时间，时间间隔为30s。

请求URL示例：/api/datapoints/sensor/100005?start=12345&interval=60

响应

返回值：JSON格式的对象数组，数组每一项包含传感器的一个数据点。

响应实例：

[

    {

        "id": "1020",

        "sensor_id": "100005",

        "timestamp": "1399906997",

        "value": "66ffcc"

    },

    {

        "id": "1035",

        "sensor_id": "100005",

        "timestamp": "1400502382",

        "value": "ffffff"

    },

    {

        "id": "1045",

        "sensor_id": "100005",

        "timestamp": "1401553452",

        "value": "000000"

    }

]

五、辅助类

1、  获取MD5

获取一个字符串的MD5值。

请求

方法：GET

URI：/helper/md5/<string>

参数：

2、  获取SHA1

使用参考“获取MD5”，返回制定字符串的SHA1值。

方法：GET

URI：/helper/sha1/<string>

3、  获取当前时间戳

获取当前时间的时间戳。

请求

方法：GET

URI：/helper/timestamp

附件列表