linux验证restapi接口,REST API

服务端 API

注意 本页面已停止维护，新上线智慧照明系统，功能更丰富：

便捷APP控制，一键配网，更好的用户体验与界面

语音控制对接，常见智能音箱对接，远控设备

固件功能丰富，如有需求可定制

概述

本文是 ESPush IoT 服务器的开发者接入手册，API 使用类似 REST API 风格描述，使用 HTTP 方式调用，使您尽快完成接入。

协议描述

domain，请求地址的HOST && PORT，应为 espush.cn，自行部署版本请自行处理；

api/server，固定值，照填即可；

class，具体调用方法URL，参考下文的接口列表；

params，公共请求参数，参考下文请求参数；

请求方式

公共请求头，公共请求参数有 Key，Timestamp，Sign三个，请将其置于 HTTP API 接口的请求头中。其中 Key 在产品管理中，Timestamp为本请求的unix时间戳，用于确认请求的有效期，以秒为单位，请求时间戳与服务器时间(北京时间)偏差大于7200秒则会被拒绝；Sign 串的计算方式见下文；

URL内参数，本文档部分接口URL中包含可变字段，如 /devices/:devid 接口中，devid 为URL内参数，需要对应填值，具体参考下文接口列表；

POST请求参数，对于本文档中的POST接口，传递的参数必须使用JSON格式，公共请求参数仍置于URL中，具体方式可参考下文的代码示例；

认证方式

请求使用公共参数Sign字段进行认证，Sign字段的具体生成步骤列举如下：

提取本次请求的方法，将其字符串(如GET、POST、DELETE等)记为M；

提取请求的URL信息中的PATH部分，意即整体URL中，去除了http://IP，去除了请求参数后的部分，如/api/server/devices即为请求的PATH，记为P；

提取公共请求参数Key与Timestamp，并按此固定排列key=%vtimestamp=%v，其中 %v 代表对应值，记为C；

提取Key对应的Password，记为字符串K；

组合以上所有结果，直接连接在一起，并取其小写字符表示，记为S，使用公式表达为 S=lower(M+P+C+K)

取字符串S的MD5，记为字符串R，R的小写表示即为最终的sign串，使用公式表达为 sign=lower(md5(lower(M+P+C+K)))

返回结果

API接口使用标准http返回码，只有2XX的返回才是正确的返回，下面是可能的返回码汇总

200，请求成功，具体请求结果参考响应内容json值；

400，多数情况下是请求参数错误，或请求不合法；

401，sign值计算错误，或APP已被删除；

404，设备或对应的APP信息不存在，将返回NotFound错误；

50X，服务器错误，服务器内部数据或逻辑有误，返回此错误；

接口列表

以下所有接口，均配置 CURL 请求示例，其示例的 APPKEY 与 PASSWORD 均为演示之用，请勿使用在自己的产品中。所有 CURL 命令，均在 Linux 操作系统中进行过测试，如果使用 windows 系统，请对应调整命令行中的特殊字符转义规则。如果使用了自行部署，请更换URL中的 Host 部分。

APPKEY:4836822619100005

PASSWORD:f784cfd3ea4a40af8df36c62d9d0f0de

设备列表

描述 获取所有已注册的设备ID列表

路径 /devices

方法 GET

参数 page, count

CURL 请求示例

curl -X GET https://espush.cn/api/server/devices -H "Key: 4836822619100005" -H "Timestamp: 1529051966" -H "Sign: 123123123123"

设备详细信息查询

描述 获取指定设备详细信息

路径 /devices/:deviceid

方法 GET

参数 无

CURL 请求示例

curl -X GET https://espush.cn/api/server/devices -H "Key: 4836822619100005" -H "Timestamp: 1529051966" -H "Sign: 123123123123"

更新设备信息

描述 为设备更名，或禁用/恢复设备

路径 /devices/:deviceid

方法 PUT

参数 无

CURL 请求示例

curl -X GET https://espush.cn/api/server/devices -H "Key: 4836822619100005" -H "Timestamp: 1529051966" -H "Sign: 123123123123"

获取设备数据

描述 获取设备上行的数据，需要传入分页参数

路径 /up/messages

方法 GET

参数 无

CURL 请求示例

curl -X GET https://espush.cn/api/server/devices -H "Key: 4836822619100005" -H "Timestamp: 1529051966" -H "Sign: 123123123123"

为设备下发数据

描述 下设备下发透传数据

路径 /devices/:deviceid

方法 PUT

参数 无

CURL 请求示例

curl -X GET https://espush.cn/api/server/devices -H "Key: 4836822619100005" -H "Timestamp: 1529051966" -H "Sign: 123123123123"