设计原则

API 设计良好的要求

  • 跨平台/跨终端 即任何操作系统(win/linux/unix/mac)任何应用终端(chrome/postman/python)都可以访问。 但是客户端Client 需要满足和API服务Service 约定好的交互数据结构(json/xml等)。
  • 透明性 即server端的功能修改不能影响客户端的使用。 功能修改 增删改 所有功能以及功能参数都应该设置为可发现。

REST

表述性状态转移(Representational State Transfer) 2000 年Roy Fielding 基于超媒体构建分布式系统的架构风格。 独立于任何基础协议，但是最常见的Rest实现就是使用HTTP作为应用层协议。

RESTful API 设计原则

  1. 围绕资源设计 资源 客户端可以访问的任何类型的对象、数据、服务。不过设计的时候最好偏重于单个业务实体，尽管实现的过程中可能需要多个表的关联操作。尽量不爆露内部实现细节。 资源应该按照层级和集合来设计，层级就是指资源与子类资源的关系，上层资源应该由检索子类资源的功能，同时子类资源也应该由自己的URI，集合即是分类资源的设计，不同集合之间的关系。
  2. API的URI 应该是与资源 一一对应。 每个资源的标识符也就是URI，应该是唯一的。
  3. 客户端使用API服务的方式表现为资源(数据)交换。 在表现形式上，是通过资源交换进行的。
  4. 使用统一接口。 HTTP GET(获取)/POST(修改)/DELETE(删除)/PUT(新建) 约定好接口与功能要求 返回码应该与http一致。比如说新建 就应该是返回码201， 更新成功返回200，删除成功204，异步请求202（接受请求但没有处理完成），更新失败400等。具体参考http的返回码。
  5. 无状态请求模型 API独立 可以任意顺序访问。

注意点

  1. 异步处理 当接受到一个异步处理时， 应该返回202，接受请求但没有处理完成。同时还要提供查询处理状态的api，使得客户端可以通过轮询的方式来监控处理状态。
  2. 数据筛选和分页 API应当接受筛选器，简单的操作（比如说排序）来作为参数，以及提供分页功能（通常是使用limit和offset两个参数控制），同时为了安全考虑，应当对这两个参数进行限制。 如果数据列比较庞大，也可以提供列筛选器来减少返回数据内容。 所有参数都应当设置合理的默认值。
  3. 关于二进制资源 图片 文件等应该接受部分响应。设置header Accept-Ranges，代表GET操作支持部分请求。

设计流程

  1. 罗列API列表。
    • 考虑业务上的功能点，罗列客户端可能需要的资源列表。
    • 根据资源类型，按照集合和分级的方式划分资源。
    • 将划分好的资源借助工具直观地表示出来。（可选） e.g. Index —Header —Body Header —Blog —About …

  2. 上一步的表示只包含了资源之间的一层关系，所以我们还需要有一个更为直观的表示，来清楚资源间的关系，这里的关系主要是状态转移的方向。

  3. 选择技术架构。
    • 媒体类型（现大多是json）
    • Web框架（好的Web框架能够事半功倍）

  4. 实现。

  5. 发布。到这个阶段就已经完成了整体的后端部分。选择一种方式将自己的成果展示出来。
    • 直接发布。（无客户端）
    • 构建web前端。
    • 构建桌面版客户端。

注意点

  1. 在做的过程中多看看设计原则。/捂脸
  2. 需求是一直在变的，做好版本控制。
  3. 命名。 尽可能贴近业务上的资源实体