接口方案

接口按照 RESTful 风格设计和实现，主体遵循 RESTful 的常见约定，主要包括以下几项：

协议

接口与调用方，采用 HTTP(S) 通讯；

路径

1. URL 避免使用大写，使用连字符（-）而不是下划线（-）；
2. URL 表示资源，使用名词、避免使用动词；

动作

使用 HTTP 方法来表示对资源的各种操作，本规范主要使用以下五种：

1. GET 从平台读取资源；
2. POST 向平台添加资源或修改平台上已经存在的资源；
3. PUT 向平台添加资源或替换平台上的现有资源；
4. PATCH 修改平台上现有资源的部分属性；
5. DELETE 删除平台上的资源或使平台上现有资源失效；

具体约定如下：

• GET http://api.example.com/foo/?param=value 获取一组 foo 对象
• GET http://api.example.com/foo/1 获取标识为 1 的 foo 对象
• POST http://api.example.com/foo/ 添加或修改 foo 对象
• DELETE http://api.example.com/foo/1,2 删除标识为 1 和 2 的 foo 对象
• PUT http://api.example.com/foo/1 添加或替换标识为 1 的 foo 对象
• PATCH http://api.example.com/foo/1 修改标识为 1 的 foo 对象的某些属性

内容协商

支持通过 HTTP 内容协商请求同一资源的不同展现形式，目前支持 JSON 和 XML。例如：

GET http://api.example.com/foo/1
Accept: application/xml

返回 XML 格式的数据，大致如下：

<Foo>
    <id>1</id>
    <name>foo</name>
</Foo>

而

GET http://api.example.com/foo/1
Accept: application/json

返回 JSON 格式的数据，大致如下：

{
  "id": 1,
  "name": "foo"
}

除此之外，也支持通过查询参数指定资源的展现形式，例如：

GET http://api.example.com/foo/1?format=xml

返回 XML 格式的数据，而

GET http://api.example.com/foo/1?format=json

返回 JSON 格式的数据