API 接口设计规范

我们的平台是一个完全开放的平台，各类开发者都可以使用我们的接口来开发各式应用。我们的接口总体上使用RESTful架构，其 URI 格式为：

https://api.ticos.cn/<method>

举例：POST https://api.ticos.cn/devices/ 代表将创建一个新设备。

为了最大程度地保证数据的安全，我们只提供 HTTPS 格式的访问地址，不提供 HTTP 的访问地址。如果需要回调，回调的地址也必须为 HTTPS 域名。

Content Type

所有的请求都必须使用 JSON 格式，并在请求头中的 Content-Type 字段指定内容格式。

Content-Type: application/json

所有的响应也使用 JSON 格式返回。

版本

默认情况下，所有访问 https://api.ticos.cn 的请求都会默认使用最新版本接口。我们会尽最大的努力来保证接口的向后兼容，如需调用特定版本，请在 Content-Type 字段指定特定的版本，如：

Content-Type: application/vnd.ticos.v1+json

如需访问 v2 版本的接口，则把以上示例的vnd.ticos.v1替换为vnd.ticos.v2即可。

权限验证

每个 REST API 请求头需包含Authorization字段。Authorization 字段必须是一个 API令牌或者Bearer令牌。

API 令牌可以在 Ticos 项目里颁发，并且和用户关联。其关联的用户权限决定了调用者的访问权限。

Bearer 令牌是和 Ticos 的用户账号关联的。API 调用者的访问权限和与之关联的用户权限一致。

Authorization: Bearer $ACCESS_TOKEN

请使用 https://iam.ticos.cn 提供的鉴权服务来获取访问令牌。因为不同的用户账号对应不同的访问权限，因此一个合法的访问令牌并不代表就可以访问到所有的资源。

如果鉴权失败, 服务端将返回 401 错误码。

如果没有访问权限，服务端会返回 403 错误码。

短暂禁用

如果在短时间内受到大量失败的鉴权请求，服务端将暂时为该用户停止鉴权请求并返回 403 Forbidden （这段时间内包括带正确验证信息的鉴权请求也会被拒绝）。

HTTP 请求方法

服务端会尽可能对所有合适的 HTTP 请求方法做出正确响应。

请求方法	描述
HEAD	只获取 HTTP 头部信息。
GET	资源获取。
POST	创建资源，或执行某特定操作。
PUT	更新资源。如果没有请求体，请将 Content-Length 设为 0。
DELETE	删除资源。

错误处理

所有的错误都应该打印的错误信息，并附上合适的错误码。

如果HTTP标准返回码（如 404 表示无法找到资源）不足以表达问题细节，那么请在响应体中添加如下格式的错误信息：

{
  code: <Error-Code>
  detail: "<Detailed Error Message>"
}

错误信息只支持英文。这些错误信息也不建议直接展示给最终用户。

通用的错误码

错误码	描述	HTTP 状态码
400	客户端请求的语法错误，服务器无法理解	400 Bad Request
401	要求用户身份认证	401 Unauthorized
403	无访问权限	403 Forbidden
404	无法找到请求的资源	404 Not Found
412	请求信息的先决条件错误	412 Precondition failed.
422	请求语义错误，无法响应	422 Unprocessable Entity
429	太多请求	429 Too Many Requests
500	服务器内部错误，无法完成请求	500 Internal Server Error

列表数据

排序

集合查询的结果可以根据属性值进行排序。该属性由$orderBy查询参数的值确定。

$orderBy参数的值包含一个逗号分隔的表达式列表，用于对结果进行排序。

表达式可以包含用于升序的后缀asc或用于降序的desc，属性名称之间用一个或多个空格分隔。如果未指定asc或desc，则默认以指定属性的升序排列。

返回结果按第一个表达式的值排序，然后按第二个表达式的值排序，依此类推。

例如：

GET https://api.ticos.cn/products?$orderBy=name

将返回按名称升序排序的所有产品。

例如：

GET https://api.ticos.cn/products?$orderBy=name desc

将返回按名称降序排序的所有产品。

子排序可以通过以逗号分隔的属性名称列表来指定。

例如：

GET https://api.ticos.cn/products?$orderBy=name desc,createdTime

将返回按名称降序，生成时间升序的所有产品。

过滤

客户端可以使用$filter查询字符串参数来过滤请求的资源。使用$filter指定的表达式会针对集合中的每个资源进行计算，并且只有表达式计算结果为true 的条目才会包含在响应中。表达式计算结果为false或null的资源，或者由于权限而不可访问的资源，将不包含在返回结果中。

示例：返回所有在t1，t2，或者t3项目中的产品

GET https://api.ticos.cn/products?$filter=project=in=(t1,t2,t3)

$filter表达式遵循 RSQL (RESTful Service Query Language) 的约定。

过滤操作符

操作符	描述	例子
比较运算符
==	等于	city=='Shanghai'
!=	不等于	city!='Hangzhou'
>	大于	price>20
>=	大于或等于	price>=10
<	小于	price<20
<=	小于或等于	price<=100
=in=	包含	project=in=(t1,t2,t3)
逻辑运算符
and	与	price<200 and price>3.5
or	或	price<3.5 or price>200

运算符示例

示例：名称等于"T1"的所有产品

 GET https://api.ticos.cn/products?$filter=name=='T1'

示例：名称不等于"T1"的所有产品

GET https://api.ticos.cn/products?$filter=name!='T1'

示例：名称为"T1"且通讯协议为"BLE"的所有产品：

GET https://api.ticos.cn/products?$filter=name=='T1' and protocol=='BLE'

分页

客户端可以使用$top和$skip查询参数来指定要返回的结果数量和偏移量。

当同时包含$top和$skip时，首先在集合上应用$skip然后$top。

例子：

GET  http://api.ticos.cn/products?$top=5&$skip=2

限流

我们会限制每个用户一段时间内的最大请求数。不同的用户拥有不同的最大请求数上限。我们通过在 HTTP 头设置如下信息来达成限流的目的。

请求头	描述
X-RateLimit-Limit	每分钟最大请求数。
X-RateLimit-Remaining	在当前限制窗口内所剩的请求额度。
X-RateLimit-Reset	当前的请求数限制何时会被重置，为 UTC 时间戳格式。

如果超过最大请求数限制，服务端将返回 429 错误码。

Status: 429 Too Many Requests