Restful API 设计原则

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的端点可能如下所示(加粗部分为端点):

避免层级过深的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
展开阅读全文

Git 实用技巧

11-24
这几年越来越多的开发团队使用了Git,掌握Git的使用已经越来越重要,已经是一个开发者必备的一项技能;但很多人在刚开始学习Git的时候会遇到很多疑问,比如之前使用过SVN的开发者想不通Git提交代码为什么需要先commit然后再去push,而不是一条命令一次性搞定; 更多的开发者对Git已经入门,不过在遇到一些代码冲突、需要恢复Git代码时候就不知所措,这个时候哪些对 Git掌握得比较好的少数人,就像团队中的神一样,在队友遇到 Git 相关的问题的时候用各种流利的操作来帮助队友于水火。 我去年刚加入新团队,发现一些同事对Git的常规操作没太大问题,但对Git的理解还是比较生疏,比如说分支和分支之间的关联关系、合并代码时候的冲突解决、提交代码前未拉取新代码导致冲突问题的处理等,我在协助处理这些问题的时候也记录各种问题的解决办法,希望整理后通过教程帮助到更多对Git操作进阶的开发者。 本期教程学习方法分为“掌握基础——稳步进阶——熟悉协作”三个层次。从掌握基础的 Git的推送和拉取开始,以案例进行演示,分析每一个步骤的操作方式和原理,从理解Git 工具的操作到学会代码存储结构、演示不同场景下Git遇到问题的不同处理方案。循序渐进让同学们掌握Git工具在团队协作中的整体协作流程。 在教程中会通过大量案例进行分析,案例会模拟在工作中遇到的问题,从最基础的代码提交和拉取、代码冲突解决、代码仓库的数据维护、Git服务端搭建等。为了让同学们容易理解,对Git简单易懂,文章中详细记录了详细的操作步骤,提供大量演示截图和解析。在教程的最后部分,会从提升团队整体效率的角度对Git工具进行讲解,包括规范操作、Gitlab的搭建、钩子事件的应用等。 为了让同学们可以利用碎片化时间来灵活学习,在教程文章中大程度降低了上下文的依赖,让大家可以在工作之余进行学习与实战,并同时掌握里面涉及的Git不常见操作的相关知识,理解Git工具在工作遇到的问题解决思路和方法,相信一定会对大家的前端技能进阶大有帮助。
©️2020 CSDN 皮肤主题: 大白 设计师: CSDN官方博客 返回首页
实付0元
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值