概述

一般原则

HTTP 请求方式

CASE服务尽量坚持尽可能接近标准HTTP和REST

请求方法 用法
GET 取回资源
POST 创建一个新的资源或查询一个资源
PUT 更新一个存在的资源
DELETE 删除一个存在的资源

分页

CASE服务需要分页返回的对象会符合以下报文格式

参数 类型 可选 描述
paging Object true 分页对象
paging.pageNum Integer true 页码
paging.pageSize Integer true 页码大小
paging.total Long true 总数

HTTP 状态码

CASE服务尽量坚持尽可能接近标准HTTP和REST

状态码 用法
200 OK HTTP请求成功的标准响应。实际的响应将取决于请求的方法。在GET请求，响应将包含对应于请求的资源实体。在POST请求，响应将包含一个实体的描述或包含的行动的结果。
201 Created 该请求已完成，并导致一个新的资源被创建。
204 No Content 服务器成功处理了请求，但未返回任何内容。
400 Bad Request 由于客户端错误（例如，错误的请求语法，无效的请求消息帧，或欺骗性请求路由），服务器不能或不会处理请求。
401 Unauthorized 未认证。
404 Not Found 找不到请求的资源，但将来可能再次可用。客户的后续请求是允许的。
500 Internal Server Error 服务器内部错误。

调用地址

格式

https://km.udesk.cn/api/v1/{relative address}?{URL params}&email={administrator email}&timestamp={timestamp}&sign={signature}

其中括号包含的部分含义如下:

变量 说明
relative address: 接口相对地址 API的相对URL
URL params: URL参数 请求接口所需参数
administrator email: 管理员邮箱 超级管理员邮箱
timestamp: 时间戳 发起请求时的时间戳，'1970-01-01 00:00:00'至今的秒数。如无特别说明，默认过期时间五分钟
signature: 签名 身份认证签名，除非特别说明，否则每次API请求均需要附加此参数，详细生成算法请查阅鉴权方法

参数 三种参数类型:

类型 说明
Path parameters 作为请求URL Path的一部分，如/leads/:id中的:id
Query parameters 请求接口时的参数，如/leads?page=10中的page
Request fields 请求体（Request Body）

返回 UTF-8编码JSON字符串

鉴权方法

公式

sign=SHA1(email&api_token&timestamp)

其中:

示例

https://km.udesk.cn/api/v1/leads

鉴权所需数据:

名称 值
email email@udesk.cn
api_token 221b368d7f5f597867f525971f28ff75
timestamp 1496631984

计算签名:

sha1("email@udesk.cn&221b368d7f5f597867f525971f28ff75&1496631984") -> a32be53bb42314850715f8b9ab92542f5ed54c5e

请求URL:

https://km.udesk.cn/api/v1/leads?email=email@udesk.cn&timestamp=1496631984&sign=a32be53bb42314850715f8b9ab92542f5ed54c5e