写点什么

设计一款“实践派”的 REST API

用户头像
余朋飞
关注
发布于: 2021 年 07 月 21 日
设计一款“实践派”的REST API

Roy Thomas Fielding 博士在其著名的论文 Architectural Styles andthe Design of Network-based Software Architectures 中,详细描述了几种常见的软件架构风格,其中第 5 章 Representational State Transfer 就是大名鼎鼎的 REST 风格。


随着 Web 2.0 和微服务的兴起,以及 SOAP Web Services 的没落,REST API 开始大行其道,在 JSON 紧凑、易读、高效率的加持下,使得该 API 风格几乎成为现代 Remoting 通信技术的事实标准。

一万个人眼中就有一万个哈姆雷特。对 REST API 风格的的理解和应用,历来存在许多分歧和五花八门的使用方式,出现了譬如“学院派“设计,一切都要遵循理论并与之严格对齐,当然也涌现了不少反范式的民间设计。


本文结合实际的生产环境经验,试图说明如何设计一款“实践派“的 REST  API。

以资源为中心

和面向 RPC 的 SOAP Web Services 不同,REST  API 的核心是资源(Resource),掌握了资源就相当于牵住了牛鼻子。


资源是一个广义的概念,可以是业务实体,也可以是一个事件或动作,资源一般用 URI 来描述。


资源的分类及描述,一般和业务领域建模很相似。以电商行业为例,资源可以是用户(User)、商品(Product)、订单(Order)、结算(Checkout)、运输(Shipment)等;


REST API 的核心理念就是围绕资源而进行的一系列操作及状态变化。

公共参数

一款好的 REST  API 应该将公共参数和业务参数分离设计,并支持独立变化。公共参数建议以 header 或 query_string 的方式来进行传递。常见的公共参数有:


客户端相关:

·       app_key,后端下发给客户端的唯一标识;

·       app_secret,与 app_key 强相关,一般不在网络中传输;

·       platform,Android|iOS|Web 等 API 使用方的平台识别码;

·       channel,安装包渠道编号,一般用于 APP 客户端;


设备相关:

·       device_id,客户端的设备号;

·       device_os,客户端的设备操作系统;

·       device_version,客户端的设备版本;

·       androidid/imei/idfa,Android|iOS 等客户端的标识;

·       device_mac,网卡物理地址;


用户相关:

·       uid,公司统一用户 ID;


版本相关:

·       app_version,APP 正式版本;

·       gray_version,APP 灰度版本;

·       internal_version,APP 内部版本;


地理相关:

·       ip,外网 IP 地址,一般客户端拿不到,需服务端从负载均衡获取;

·       longitude,GPS 经度;

·       latitude,GPS 纬度;


国际化相关:

·       language,用户的语言;

·       country,用户的国家;

·       currency,用户的货币;


网络相关:

·       net_status,网络状态,如 3G/4G/5G/Wifi 等;


安全相关:

·       signature,API 摘要,防止伪造请求,签名最好加入 app_secret 增加破解难度;

·       access_token,用户 token,防止伪造身份,一般由公司 SSO 下发且带 TTL;

·       timestamp,时间戳,防止重放;

 

命名风格

从最佳实践角度来说,URL 命名风格建议遵循以下一些原则:

·       以名词命名。如/api/products,/api/orders,/api/users。

·       以复数命名。这只是一种约定俗成的风格,便于潜在的扩展需要。

·       需要有统一的 API 根。如/api/business1,/api/business2。这样的好处是能做好望文生义,见到 API 即可了解该接口来自哪个服务,也便于监控和日志统计。在微服务的架构设计准则下,API 根尤为重要。

·       尽可能采用蛇形(snake_case)而不是驼峰(camelCase)来命名 URL;

·       采用 HTTP Method 来操作资源。通常采用 GET 来读取资源,POST 创建资源,PUT 创建或全量更新资源,PATCH 局部更新资源,DELETE 删除资源。


值得注意的是,在实际使用场景中,我们并不是真的要坚持这些“理论派“,完全可以不必拘泥于这些约束,可以灵活变通,比如:

·       有些场景没法通过名词来描绘 ,如用户登录。这时可以使用/api/users/login 来命名;

·       PUT 和 PATCH 有相似之处,是否可以用 PUT 来代替 PATCH?也未尝不可,更有甚者,可以采用 POST 来代替;

 

安全性

不安全的 REST  API 会导致信息泄露,给不法分子可乘之机,严重的还会损害公司信誉和形象。


一个安全的 REST API 需要具备哪些因素呢?这里列出几种比较实用的安全设计准则:


采用 HTTPS

从现在开始,全体 API 就应该采用 HTTPS 传输。完全不用担心由此带来的资源消耗和耗时增加。API 网关做 SSL 卸载所带来的额外 CPU 开销,完全可以通过增加更多的服务器,通过水平扩展来分摊压力。而耗时的增加相对于业务层延迟来说,几乎可以忽略不计,这种情况更多应该在应用层做耗时调优,而不用理会接入层的开销。


摘要(Digest)

REST API 摘要本质上是一种不可逆的指纹,目的是实现 API 请求不可篡改。


REST API 摘要有时候也被通俗的称为接口签名,注意这里和密码学上的数字签名严格上说意义不太一样,数字签名是指利用私钥加密签发,接收方用公钥解密。


这里介绍一种实用的摘要算法:

·       API 提供方(Provider)提供 app_key 和 app_secret 给 API 使用方(Consumer);

·       API 使用方将请求参数和 app_key、app_secret、时间戳(timestamp)等按一定的算法进行混合、排序,生成一个字符串;

·       API 使用方对上一步生成的字符串,按常见的摘要算法(如 MD5、SHA-256 等)进行哈希计算,得到指纹;

·       API 使用方将上一步得到的指纹,以 signature=<摘要>的形式,追加到请求参数中;

·       API 提供方接收到请求后,采用同样的方式,进行哈希计算,再和 signature 进行比较,从而达到验证签名的目的;


值得注意的是,app_secret 在 API 使用方仅参与摘要计算,起到一个随机盐的作用,但不随请求传输。这样的好处是防止被截获。另外 API 提供方已经存在 app_secret,自然不需要请求方再次传递。


好了,上面的摘要算法真的固若金汤、牢不可破吗?答案是否定的,没有绝对的安全。


最常见的威胁就是重放攻击。尽管我们已经设置了 timestamp 时间戳,服务端也完全可以利用 timestamp 和当前时间的间隔来限制重复请求,但也会存在两个问题:客户端和服务端可能会存在时钟不一致,另外在有效的时间窗口内依然可以重放。


解决方案有多种,从本质上说应该业务层面做好幂等,限制重复请求带来的副作用。另外也可以考虑服务端给调用方分配一个计数,并在内部记录和校验,该计数只可以递增,每次攻击者试图重放 API 就必须递增该计数,然而摘要算法是不公开的,这就使得重放无法实现。


另外的问题就是如果 API 使用方的代码被反编译,摘要算法和 app_secret 被同时破解,黑客就可以随意伪造 API 请求了。


解决方案是采用动态随机盐,由 API 提供方为每个设备或用户生成动态随机盐并周期性刷新,记录到数据库中进行校验。即使代码被破解,攻击者也无计可施。


认证(Authentication)

REST  API 的认证是为了验明用户身份,实现用户身份的不可抵赖。


一种比较实用的做法是采用令牌(access_token)机制。即用户登录后,由 API 提供方(通常是用户或 Passport 中心)颁发一个令牌给使用方,该 token 安全级别较高,全局唯一,不可逆,可周期性更新或支持续借(renew)。


当 API 调用方将 access_token 加入到 API 请求后,API 提供方会将读取该参数,并查询后台进行用户身份确认,从而实现认证功能。


为什么采用 token 机制呢?原因很简单,用户身份一般由用户名和密码构成,API 客户端不可能将这些信息频繁传到服务端,这会增加信息泄密的风险。而 token 是不可理解的密文,且可以更新,故安全级别能得到较大提升。


鉴权(Authorization)

仅身份认证是不够的,REST  API 的鉴权是为了解决用户权限问题。

假如没有鉴权,则用户可以操作任何资源,这显然是不安全的。常见做法是检查用户的权限与角色,确认对资源的操作权限。如普通用户只能删除、修改自己发布的内容,管理员则可以操作任何用户的数据。

国际化

在一些国际化的业务中,如跨境电商,往往需要 REST API 支持国际化。常见的实用做法是 API 调用方采集用户的国际化属性,加入 API 请求参数。API 提供方读取这些属性,存储到后台,或是直接在业务层面使用。

常见的国际化属性有:

·       语言。通常会采用 language = EN | ZH | FR 等形式进行参数传递;

·       国家。通常采用 country = CN | US | BR 等形式;

·       货币。通常采用 currency = USD | CNY | EUR 等形式;

·       时区。通常采用 time_zone = GMT+8:00 形式;

 

兼容性

兼容性是 REST  API 开发者的必备素质,很多线上回归错误(往往还很隐晦)都是由于 API 没有考虑向下兼容造成的。因此需要考虑一些设计准则:

·       只加字段,不删除字段,不修改字段名称;

·       任何时候开发新功能,需要考虑到版本控制,即新功能只限于新版本,除非明确老版本也能使用而不受影响;

 

幂等性

幂等性并不是绝对的。

我们考虑下 HTTP 常见 Method 的幂等性,如 GET /PUT/PATHCH/DELETE,这些操作天然具备幂等性语义,即多次操作,不会产生副作用。而 POST 操作,默认在多次操作下会多次创建资源,因此不是幂等的。

然而,业务实现是靠技术人员实现的,因此完全可以人为控制幂等性。所以,这里并不建议过于教条,而应该根据实际情况来决定幂等性语义。

过滤

一个设计良好的 REST  API 应该具备过滤能力。一种实用的做法就是通过传业务参数来控制过滤逻辑,如 id=123456,user_name=xxx 等。

另外一种层面的过滤是指返回的字段,应该可以由 API 调用方来控制,如 fields=user_name, user_age, user_city 等。

这样做的好处是显而易见的,一方面可以减少服务端的资源消耗,特别是存储的查询压力,另一方面也可以减少网络带宽的占用和 API 使用方的反序列化成本。

 

排序

业务场景往往会有排序的诉求,如商品展示可以按发布时间、热度、销售量进行排序。REST  API 应该能支持灵活易用的排序方式。

一种常见的最佳实践就是在 API 请求中增加 sort 字段,并且支持多维度排序。如按时间正向排序,且按积分反向排序,就可以表示成:sort=+time,-score。

 

分页

几乎所有的产品形态都需要分页,分页功能看似简单,实际上做起来很复杂。比如:

·       如何保证每一页的数据不存在重复或丢失?

·       大数据量的集合(千万级别),如何实现深度分页,且效率不受影响?

·       如何实现跳页,即随机读取某一页数据?

这些问题不在本文讨论范围内,感兴趣的读者可以自行搜寻答案。这里介绍两种常见的分页请求参数方式。

·       采用页码方式,如 offset/limit 或 page_no/page_size。这种方式很常见,通常对于大的数据量来说,随着页码的增加分页效率会递减。当然也可以采用一些优化的技巧,如 MySQL 采用覆盖索引的子查询;

·       采用游标方式,如 cursor。这种方式相对简单,适合单维度、固定排序的数据分页。好处是时间复杂度可以是常量级别,弊端是不可以随机读取,只能从头顺序访问,当然也可以通过其他方式拿到 cursor 直接去访问下一页;

 

状态码

REST  API 基于 HTTP,自然需要定义响应的状态码,常见的预定义状态码大致可参考:

 

在实际 REST API 设计中,可以灵活运用这些状态码,当然也大可不必拘泥于这些预设的状态码并咬文嚼字。常见的以 200 和 4XX、5XX 使用较多。

除此之外,还可以自定义一些非保留状态码如 6XX、7XX,用于一些特殊使用场景。

 

业务码

业务码是非常重要的信息表达方式,API 使用方肯定不希望在出错时,只是看到一个笼统的提示:“出错了”,而是可以读取到具体的错误码和对应的提示。

通常,REST API 返回报文会使用一个固定的格式,常见的有:

其中 code 和 messaage 就是业务码和提示信息发挥作用的地方。我们可以定义一个业务码字典和对应的提示信息。如 E000001 代表缺少参数 xxx,E000002 代表订单已被删除等等。

谨记几条原则:

·       永远不要把程序内部异常或错误抛给 API 调用方,而是采用业务码优雅的提示;

·       当输出错误码时,HTTP 状态码也应该同步调整,比如输出 5XX,这样可以让监控系统快速发现问题;

 

发布于: 2021 年 07 月 21 日阅读数: 109
用户头像

余朋飞

关注

还未添加个人签名 2018.08.18 加入

程序员,技术Leader。长期专注于软件开发和技术管理,乐于分享。

评论

发布
暂无评论
设计一款“实践派”的REST API