客户端（包括浏览器）通过HTTP协议与服务端交换数据的描述

发起请求

http method

• 写请求使用POST
• 读请求使用GET

参数提交

• 提交一个普通对象，使用键值对参数

  x-www-form-urlencoed

• 当同名参数有多个值时，使用http表单数组的方式
  • options[]:a
  • options[]:b
  • options[]:c

    …

• 当参数对应的值是复杂对象或多维数组时，json序列化该对象/多维数组

处理服务端响应

预先准备

根据业务需求，确定当前响应返回的是业务数据，还是系统消息。（此步骤不是代码处理）

代码处理

1. 检查http状态码。在检查状态码（例如：200。必须根据实际需求决定，此处只是举例）后可能不再需要进一步处理并就此结束处理流程。
2. 如果响应返回的是业务数据，当http状态码表明响应成功时，可从http body中读取。
3. 如果响应返回的是系统消息，可使用消息代码来确定消息种类，再根据实际需求决定是否使用消息描述及有效载荷。

API签名机制

不需要签名的会以 SignFree 标记。

1. 用请求参数生成键值对，键值对为“参数名=参数值”；其中上传文件的参数值为文件内容sha1结果的小写形式。
2. 所有键值对按照键自然排序，然后用“&”连接为内容字符串。
3. 使用内容字符串生成待签名字符串，如“内容" role="presentation" style="font-size: 100%; display: inline-block; position: relative;">内容内容{应用ID}时间戳" role="presentation" style="font-size: 100%; display: inline-block; position: relative;">时间戳时间戳{应用密钥}”。
   

   注意：${}表示占位符。

4. 待签名字符串用sha1生成签名，结果忽略大小写。

操作结果状态说明

http状态码

• 200 操作成功
• 400 请求有问题；如：表单验证失败、请求签名验证失败等
• 401 认证失败。
• 403 无访问权限。
• 409 请求处理完成但因为业务规则限制或其他原因并未真正成功的响应
• 500 服务器错误
• 503 服务器维护中

消息结构

{"code":CODE,"msg":MSG,"payload":PAYLOAD}

• CODE：消息代码。字符串，肯定不为空。对一个API来说，消息代码用于区分消息的种类，一旦确定就不再改变。
• MSG：消息描述。字符串。
• PAYLOAD：有效载荷。JSON对象或数组。

返回结果约定

• 凡是应该返回集合的操作，无结果时返回空集
• 均用JSON表示

安全防护

不是完全必须的，根据业务需求而定。

CSRF（跨站请求伪造） Token提交

1. 读取服务端返回的名为 XSRF-TOKEN 的Cookie
2. 提交请求时，携带Token值
   • 通过HTTP header，X-XSRF-TOKEN
   • 通过系统级参数，_xsrf_token

应用ID、时间戳、签名提交

1. ID

   通过HTTP header ，X-CLIENT-ID。

   通过系统级参数，_clientId。

2. 时间戳

   通过HTTP header ，X-TIMESTAMP。

   通过系统级参数，_timestamp。

3. 签名

   通过HTTP header ，X-CLIENT-SIGN。

   通过系统级参数，_clientSign。