Restful API 设计原则

前言

网络应用程序分为前端和后端两个部分。

当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面电脑、其他专用设备……），这也就意味着前端的开发代码、开发框架变得多种多样。因此，必须有一种统一的机制，方便不同的前端代码与后端进行通信。

这就导致了API构架的流行。REST是目前比较成熟的一套互联网应用程序的API设计理论。 它可以降低开发的复杂度，提高系统的可伸缩性，增强系统的可扩展性，简化应用系统之间的集成。

在这篇文照中，我整理了一些RESTful API的设计细节，探讨如何设计一套合理、好用的API。

注意：这篇文章只讨论设计原则，不是强制的要求或者标准（API 设计者可以根据实际情况实现部分内容，甚至实现出和某些原则相反的内容）。

定义

下面是一些本文中可能要使用的名词：

• Resource（资源）：单个实例对象，例如一只动物
  
  • 一个资源可以是一份文档、一张图片、一个与时间相关的服务（例如：洛杉矶今天的天气）等等。Roy Thomas Fielding认为资源是实体的概念性映射，而不是实体本身；我个人觉得资源是一种在网络上的抽象概念，更像是一种数据信息。
• Collection（集合）：集合是一组同类的实例对象，例如一群动物。
• HTTP：一种网络的通信协议
• 客户端：可以创建HTTP请求的客户端应用程序
• 第三方开发者：将使用你的数据的开发者。
• 服务器：一个HTTP服务器或者应用程序，客户端可以跨网络访问它
• Endpoint（端点）：服务器提供的一个URL，它标识了一个资源（Resource）或者集合（Collection）
• Idempotent（幂等性）：多次重复操作得到的结果一样
• URL段：在URL里面用斜杠分隔的内容

使用 HTTPS

不使用SSL/TLS的HTTP通信，就是不加密的通信。所有信息明文传播，带来了三大风险。

• 窃听风险（eavesdropping）：第三方可以获知通信内容。
• 篡改风险（tampering）：第三方可以修改通信内容。
• 冒充风险（pretending）：第三方可以冒充他人身份参与通信。

SSL/TLS协议是为了解决这三大风险而设计的，希望达到：

• 所有信息都是加密传播，第三方无法窃听。
• 具有校验机制，一旦被篡改，通信双方会立刻发现。
• 配备身份证书，防止身份被冒充。

使用HTTP或者HTTPS和Restful API本身没有很大的关系，但是对于增加网站的安全是非常重要的。特别如果提供的是公开 API，用户的信息泄露或者被攻击会严重影响网站的信誉。

使用SSL可以减少鉴权的成本：你只需要一个简单的令牌（token）就可以鉴权了，而不是每次让用户对每次请求签名。

NOTE：不要让非SSL的url访问重定向到SSL的url。

API 域名和版本

无论你在设计什么系统，也不管你事先做了多么详尽的计划，随着时间的推移和业务的发展，你的程序总会发生变化，数据关系也会发生变化，资源可能会被添加或者删除一些属性。

但是在Restful的设计思想中，资源描述和资源实体是分开的，而设计REST API是基于资源描述。当资源实体发生变更时，只要修改资源描述和资源实体的映射，就能保证资源描述不变，进而保证所设计的API不变，所有使用API的第三方程序也不需要做任何修改。

在 url 中指定 API 的版本是个很好地做法。如果 API 变化比较大，应该尽量把 API 设计为子域名，比如

https://api.github.com/v3

如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下，比如：

https://example.com/api

当然还有另一个常用的解决办法就是把版本号放在请求首部中（HTTP请求的accept字段），根据多年与第三方开发人员打交道的经验，把版本号放在URL里要比放在请求的首部中更容易实现和使用，如上面所示，github就是采用将版本号放到URL的方法。

资源与端点

上文中提到，在 REST 构架的设计中，系统中的所有事物都被抽象为资源，而URI是这个资源的唯一标识。

• 在一个文档系统中，文档，目录，注释，草稿，等等，是组成系统的资源。
• 在一个银行系统中，客户信息，理财产品，利率信息，网点信息，等等，是组成系统的资源。
• 在一个航空客票系统中，旅客信息，机票订单，航班信息，机场信息，等等，是组成系统的资源。

我们会注意到，这些资源，在描述了某种事物的同时，还有可能存在一定的层次结构关系。比如，文档从属于某个目录，注释从属于文档；旅客信息可以从属于机票订单，也可以从属于某个航班。

当我们的资源有这种层次关系的时候，我们不妨在URI模式的设计中，用复合的URI来帮助开发者更好的理解和设计资源。

比如，针对一个文档的评论，他的URI模式可以设计成如下：/ 文件夹 / [ 文件夹名 ] / 文件 / [ 文件名 ] / 评论 / [ 评论唯一标示 ]。 这样，在构造和解析URI的过程中， 可以帮助开发者更好的理解系统，设计程序。

NOTE: URI是一个资源的唯一标识，而URL是URI的子集，在网络应用中通常使用URL来唯一标识一个资源。

而端点是URL中，最后一段用于标识一个特定资源或资源集合的URL片段。

URI规范

• 不用大写；
  
  • 根据RFC3986定义，URL是大小写敏感的。所以为了避免歧义，尽量使用小写字母。
• 用中杠-不用下杠_；
• 参数列表要encode；
• URI中的名词表示资源集合，使用复数形式。

虽然看起来使用复数来描述某一个资源实例看起来别扭，但是统一所有的端点，使用复数使得你的URL更加规整。这让API使用者更加容易理解，对开发者来说也更容易实现。

假如你想构建用于表示多个动物园资源的API，其中，每个动物园都包含很多动物（每个动物只能属于一个动物园），顾员（他们可以在多个动物园工作），并且需要跟踪每个动物的详细信息，那么这些API的端点可能如下所示（加粗部分为端点）：

• https://api.example.com/v1/zoos
• https://api.example.com/v1/animals
• https://api.example.com/v1/employees

避免层级过深的URI

一般根据id导航。过深的导航容易导致url膨胀，不易维护。尽量使用查询参数代替路径中的实体导航。

相对不好的设计
GET /zoos/1/areas/3/animals/4
相对好的设计
GET /animals?zoo=1&area=3；

对Composite资源的访问

它的生命周期完全依赖父实体，无法独立存在，不直接对应表，也无id。服务器端的组合实体必须在uri中通过父实体的id导航访问。

一个常见的例子是 User — Address，Address是对User表中zipCode/country/city三个字段的简单抽象，无法独立于User存在。

必须通过User索引到Address：GET /user/1/addresses

URI失效

应该添加301到新地址，或者有一个错误提示。

HTTP动词

对于资源的具体操作类型，由HTTP动词表示。

常用的HTTP动词有下面几个。

• GET：从服务器取出资源（一项或多项）。
• POST：在服务器新建一个资源。
• PUT：在服务器更新资源（客户端提供改变后的完整资源）。
• PATCH：在服务器更新资源（客户端提供改变的属性）。
• DELETE：从服务器删除资源。
• HEAD：获取资源的元数据。
• OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

下面是一些例子。

GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

针对不同操作，服务器向用户返回的结果应该符合以下规范。

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档

不符合 CRUD 的情况

在实际资源操作中，总会有一些不符合 CRUD（Create-Read-Update-Delete） 的情况，一般有几种处理方法。

使用 POST

重构你的行为action。当你的行为不需要参数的时候，为需要的动作增加一个 endpoint，使用 POST 来执行动作，比如POST /resend重新发送邮件。

增加控制参数

添加动作相关的参数，通过修改参数来控制动作。

比如一个博客网站，会有把写好的文章“发布”的功能，可以用上面的POST /articles/{:id}/publish方法，也可以在文章中增加published:boolean字段，发布的时候就是更新该字段PUT /articles/{:id}?published=true

把动作转换成资源

把动作转换成可以执行 CRUD 操作的子资源， github 就是用了这种方法。

比如“喜欢”一个 gist，就增加一个/gists/:id/star子资源，然后对其进行操作：“喜欢”使用PUT /gists/:id/star，“取消喜欢”使用DELETE /gists/:id/star。

另外一个例子是 Fork，这也是一个动作，但是在 gist 下面增加 forks资源，就能把动作变成 CRUD 兼容的：POST /gists/:id/forks可以执行用户 fork 的动作。

结果过滤，排序，搜索

url最好越简短越好，和结果过滤，排序，搜索相关的功能都应该通过参数实现(并且也很容易实现)。

过滤

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

下面是一些常见的参数。

• ?limit=10：指定返回记录的数量
• ?offset=10：指定返回记录的开始位置。
• ?page=2&per_page=100：指定第几页，以及每页的记录数。
• ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
• ?animal_type_id=1：指定筛选条件

排序

和过滤一样，一个好的排序参数应该能够描述排序规则，而不业务相关。复杂的排序规则应该通过组合实现：

• GET /ticketssort=-priority : Retrieves a list of tickets in descending order of priority
• GET /ticketssort=-priority,created_at : Retrieves a list of tickets in descending order of priority. Within a specific priority, older tickets are ordered first

这里第二条查询中，排序规则有多个rule以逗号间隔组合而成。

搜索

有些时候简单的排序是不够的。我们可以使用搜索技术（ElasticSearch和Lucene）来实现（依旧可以作为url的参数）。

• GET /ticketsq=return&state=open&sort=-priority,created_at- Retrieve the highest priority open tickets mentioning the word ‘return’

对于经常使用的搜索查询，我们可以为他们设立别名,这样会让API更加优雅。例如：

get /ticketsq=recently_closed -> get /tickets/recently_closed。

限制API返回值的域

有时候API使用者不需要所有的结果，在进行横向限制的时候（例如值返回API结果的前十项）还应该可以进行纵向限制。并且这个功能能有效的提高网络带宽使用率和速度。可以使用fields查询参数来限制返回的域例如：

GET /ticketsfields=id,subject,customer_name,updated_at&state=open&sort=-updated_at

分页 Pagination

当返回某个资源的列表时，如果要返回的数目特别多，比如 github 的 /users，就需要使用分页分批次按照需要来返回特定数量的结果。

分页的实现会用到上面提到的 url query，通过两个参数来控制要返回的资源结果：

• per_page：每页返回多少资源，如果没提供会使用预设的默认值；这个数量也是有一个最大值，不然用户把它设置成一个非常大的值（比如 99999999）也失去了设计的初衷
• page：要获取哪一页的资源，默认是第一页

返回的资源列表为 [(page-1)*per_page, page*per_page]。github API 文档中还提到一个很好的点，相关的分页信息还可以存放到Link头部，这样客户端可以直接得到诸如下一页、最后一页、上一页等内容的 url 地址，而不是自己手动去计算和拼接。

选择合适的状态码

HTTP 应答中，需要带一个很重要的字段：status code。它说明了请求的大致情况，是否正常完成、需要进一步处理、出现了什么错误，对于客户端非常重要。状态码都是三位的整数，大概分成了几个区间：

• 2XX：请求正常处理并返回
• 3XX：重定向，请求的资源位置发生变化
• 4XX：客户端发送的请求有错误
• 5XX：服务器端错误

使用 HTTP 头处理缓存和并发

缓存和并发处理，从来是大型软件系统设计中的重要组成部分。

使用 HTTP 头进行缓存处理

在 REST 的构架中，我们除了在与后台的数据交换中，需要有一个良好的缓存机制外，针对 REST API 请求都是在远端用 HTTP 发起这一特点，还需要为网络缓存进行更多考虑。通过减少 HTTP 响应内容，避免不必要的 HTTP 连接等方式，达到提高 REST API 使用效率的目的。

HTTP 头中，有多个字段可以用于缓存处理。比较常用的有缓存控制和条件请求。

缓存控制：

缓存控制通常是需要客户端，缓存服务器 / 代理服务器与业务服务器一起发生作用。

HTTP 头中有“Cache-control”字段来控制如何使用缓存，常见的取值有 private、no-cache、max-age、must-revalidate 等。比如当你给返回的数据内容设置 max-age=600，那么当用户隔了 30 秒再次请求的时候，就不会导致重新请求后台数据。

另外，也可以通过“Expires”字段来指定内容过期时间，在此时间前的请求都不会导致后台程序重新请求数据。

下图展示了 max-age 是如何工作的。

条件请求与电子标签：

很多时候，数据内容可能会几个小时甚至几天都不会发生变动，这个时候根据请求时间间隔来控制缓存，就不能满足系统的需求了。通过支持条件请求与电子标签，可以帮助我们来解决这个问题。

当用户请求数据内容时，系统在返回数据的同时，在 HTTP 头中，将返回根据服务器内容的最后修改时间 Last-Modified，或者根据服务器内容生成电子标签 ETag。 当用户再次请求数据时，就可以在 HTTP 请求中使用 If-Modified-Since 或者 If-None-Match 头信息，把上次请求得到的时间戳或者电子标签传给服务器。当收到一个有条件请求的 HTTP 头的 REST 请求的时候，我们的程序需要将收到的时间戳或者电子标签与当前内容作比较，就可以很容易的知道用户请求的数据内容在这段时间是否发生过修改，并根据比较结果返回给用户最新内容，或者用 HTTP 响应码 304 告知用户，内容没有变化。

下面是一个来自 IBM developerWorks 的 API 样例，尝试请求该 API，你可以看到该 API 会在 HTTP 头中返回电子标签和缓存处理信息。

清单 4. IBM developerWorks 的带有电子标签的文件服务 API

REST API 请求：
GET  https://www.ibm.com/developerworks/mydeveloperworks
/form/anonymous/api/communitylibrary 
/7e2e8015-bf72-43b6-bacd-36565b67febc/document 
/ddc0ef4e-224e-449c-bb2c-f919fafb17d2 
/entry?acls=true&includeRecommendation=true 
&includeTags=false&includeLibraryInfo=true&format=xml

使用 HTTP 头进行并发处理

上文我们提到了使用条件请求控制缓存，其实我们还可以使用条件请求进行并发处理。

比如当用户 Alice 和 Bob 通过 REST 获取了一篇文档。Bob 阅读文档之后，通过 PUT 来修改文档；而此前几分钟，Alice 刚刚修改了这篇文档，于是 Bob 就在毫不知情的情况下不慎覆盖了 Alice 的修改。

通过在写操作中支持条件请求，我们可以更好的处理并发修改。用户在发出修改请求的同时，在 HTTP 请求中使用 If-Not-Modified-Since 或者 If-Match 头信息，把获取数据时得到的时间戳或者电子标签传给服务器；我们的程序通过与服务器当前内容的比较，就可以知道，这个修改请求是否是针对当前内容提出的。当服务器发现内容已经被其他用户修改过了，就不会执行修改请求，并返回 HTTP 响应码 412（未满足前提条件）给用户。

下图展示了使用条件请求和电子标签进行并发处理是如何工作的

速度限制

如果对访问的次数不加控制，很可能会造成 API 被滥用，甚至被 DDos 攻击。根据使用者不同的身份对其进行限流，可以防止这些情况，减少服务器的压力。为此 RFC 6585 引入了HTTP状态码429（too many requests）。加入速度设置之后，应该提示用户，至于如何提示标准上没有说明，不过流行的方法是使用HTTP的返回头。

对用户的请求限流之后，要有方法告诉用户它的请求使用情况，Github API 使用的三个相关的头部：

• X-RateLimit-Limit: 用户每个小时允许发送请求的最大值
• X-RateLimit-Remaining：当前时间窗口剩下的可用请求数目
• X-RateLimit-Rest: 时间窗口重置的时候，到这个时间点可用的请求数量就会变成X-RateLimit-Limit的值

如果允许没有登录的用户使用 API（可以让用户试用），可以把 X-RateLimit-Limit 的值设置得很小，比如 Github 使用的 60。没有登录的用户是按照请求的 IP 来确定的，而登录的用户按照认证后的信息来确定身份。

对于超过流量的请求，可以返回429 Too many requests状态码，并附带错误信息。而 Github API 返回的是403 Forbidden，虽然没有 429 更准确，也是可以理解的。

Github 更进一步，提供了不影响当然 RateLimit 的请求查看当前 RateLimit 的接口GET /rate_limit。

Hypermedia API

Restful API 的设计最好做到 Hypermedia：在返回结果中提供相关资源的链接。这种设计也被称为 HATEOAS。这样做的好处是，用户可以根据返回结果就能得到后续操作需要访问的地址。

比如访问 api.github.com，就可以看到 Github API 支持的资源操作。

编写优秀的文档

API 最终是给人使用的，不管是公司内部，还是公开的 API 都是一样。即使我们遵循了上面提到的所有规范，设计的 API 非常优雅，用户还是不知道怎么使用我们的 API。最后一步，但非常重要的一步是：为你的 API 编写优秀的文档。

对每个请求以及返回的参数给出说明，最好给出一个详细而完整地示例，提醒用户需要注意的地方……反正目标就是用户可以根据你的文档就能直接使用 API，而不是要发邮件给你，或者跑到你的座位上问你一堆问题。

参考资料

1. RESTful API 设计最佳实践
2. 跟着 Github 学习 Restful HTTP API 设计
3. 最佳实践：更好的设计你的 REST API