REST 协议说明 - 开始前必读

什么是 REST

REST，是目前最为流行的一种互联网软件架构。因为它结构清晰、符合标准、易于理解、扩展方便。关于 REST 的详细说明推荐参考 REST - 维基百科

伙伴云 REST 设计

伙伴云在 REST 的设计原则上，根据自身的业务需要，对部分细节做了调整。

如何确定返回的资源

接口的 URL 的第一个单词表示该接口返回的资源。如访问 GET /item/10000 获取指定数据的接口，表示返回的资源是一个数据资源（item）。

如何确定返回是单个资源还是集合

接口的 URL 的第一个单词是单数还是复数表示该接口返回的是单个资源还是集合。如访问 GET /follows/item/1000 获取指定数据下的关注列表，follows 是复数形式，表示返回的是关注对象的集合。再如访问 GET /follow/1000 获取指定关注对象，follow 是单数形式，表示返回的是单个关注对象。

接口不符合 CRUD 操作时如何设计

当操作无法使用简单的 CRUD 来定义时，我们采用统一是用 POST 的方式请求，使用 URL 的最后一个单词表示动作。如筛选数据列表 POST /items/table/1000/find，find 表示操作的动作。

为了避免不同的客户端的不同处理方式，所有的 URL 统一不使用 / 结尾，减少出现错误的 URL 不匹配导致开发者迷惑的问题。如 GET /item/1000/ 不会出现在接口的设计中。

我需要返回资源的部分字段/我需要资源关联其他资源

当我们只需要指定资源的部分字段，或者资源与其他资源有关联关系，我们不希望多次调用接口获取时，可以使用指定接口返回资源的字段的机制实现。设置每个 API 接口请求头部的 X-Huoban-Return-Fields 可以控制该接口资源返回的字段。

关于请求头部的 X-Huoban-Return-Fields 参数，您需要了解以下几点：

该参数必须为可解析的 JSON 字符串，如需要获取表格详情接口只返回表格名字时，只需将 X-Huoban-Return-Fields 设置为 ["name"]。
支持嵌套的其他资源字段，如表格（Table）与工作区（Space）是一对一的包含关系，则在表格资源中可以返回其所在的工作区资源信息，将X-Huoban-Return-Fields 设置为 ["table_id"，"space"]。
返回的资源字段支持通配符 *，表示返回所有该资源默认返回的字段。如在获取表格详情时， X-Huoban-Return-Fields 设置为 ["*"，"space"] 表示在原有表格资源所有默认返回字段以外增加返回工作区资源。
如果关联资源是集合，则使用复数作为资源的字段名称，如表格（Table）包含多个字段（Field），则字段资源的名称为 fields。
控制资源集合的返回字段，需要嵌套一层数组，如表格（Table）包含多个字段（Field），X-Huoban-Return-Fields 设置为 {"fields":[["field_id"，"config"]]}。

假设我们需要获取表格详情，对于表格资源指向要 name 字段。同时，我们需要连带获取表格所在的工作区和表格所有的字段。同时，表格所有字段我们只需要字段的 ID 和名称。我们可以构建以下请求：

GET /v2/table/:table_id HTTP/1.1
Host: api.huoban.com
Content-Type: application/json
X-Huoban-Ticket: {YOUR_TICKET}
X-Huoban-Return-Fields: ["name", {"space":["*"]}, {"fields":[["field_id", "name"]]}]

得到的响应结果如下：

HTTP/1.1 200 OK

{
  "name": "表格",
  "fields": [
    {
      "field_id": 111,
      "name": "字段一"
      }
    }
  ],
  "space": {
    "space_id": 11001,
    "name": "工作区",
    ...
  }
}

开始前必读REST 协议说明

什么是 REST

伙伴云 REST 设计

开始前必读
REST 协议说明