如何设计出优美的Web API？

Posted 2021-03-16

1. 概述

WEB API的应用场景非常丰富，例如：将已有系统的功能或数据开放给合作伙伴或生态圈；对外发布可嵌入到其他网页的微件；构建前后端分离的WEB应用；开发跨不同终端的移动应用；集成公司内部不同系统等等。在上述场景里，你可能是WEB API的使用者，也可能是设计者，但你知道如何评判WEB API的优劣吗？

2. 评判标准

我们可以从三个维度来评判一个WEB API的优劣：

• 易于使用：WEB API的用户是程序还是人？我觉得首先是人，然后是程序。为什么这么说呢？是否采用某个WEB API的决定是人做出的，一个好的WEB API必须符合人的审美，例如：简短易记、通俗易懂、便于输入等。从程序角度看，WEB API应该遵循行业规范，在调用时不需要做特殊化处理，有利于复用已有的代码或工具。
• 便于更改：一个WEB API发布上线之后，免不了要根据真实用户的反馈或者业务发展的需要做更新修改，这些更新修改必须尽量不影响用户。要么提供多版本支持，要么给用户提供切实可行的更新策略等等。
• 健壮稳定：对外公开的WEB API存在被***的风险，以及无法准确预估的访问量等，一个好的WEB API必须要有防注入、防篡改、防重放等安全机制，还要在访问量急剧上涨时避免服务被击穿。

做到了上述三个方面，我们才有底气将一个WEB API对外开放，接受公众的检验。好的WEB API不仅方便使用，还助于提升个人或企业的技术影响力，从而形成正向循环，带来越来越多的业务价值。为了设计出优美的WEB API，我们需要了解与之相关的设计规范和事实标准，并且在设计开发过程中尽量遵循它们。

3. 设计规范

3.1 URI

• 便于输入的URI，简短不冗余。每个WEB API都是一个服务，那下面反例当中的“service”就是冗余的，而且“api”也重复出现了两次，这种冗余都不利于记忆和输入：

反例：http://api.example.com/service/api/users
正例：http://api.example.com/users

• 容易读懂的URI，不要随意采用缩写，缩写必须要符合国际标准规范，不要凭空发明创造，例如：国家代码定义（ISO3166）。反例中出现了两处缩写“sv”、“u”，在没有附加说明的情况下，用户压根不知道含义：

反例：http://api.example.com/sv/u

• 没有大小写混用的URI。HTTP协议（RFC7230）规定：除了模式（schema）和主机名以外，URI的其他信息都要区分字母的大小写。下述两个反例大小写混用，不方便记忆。

反例：http://api.example.com/Users/12345
反例：http://example.com/API/getUserName

• 易于修改的URI，命名存在可预见的规律。下述正例我们可以很容易猜测改变最后的ID就可以访问其他商品的信息。

正例：http://api.example.com/v1/items/123456

• 不会暴露服务端架构的URI，URI只需要体现功能、数据结构和含义，无需暴露服务端如何运作的信息。这些信息对用户来说没有意义，还存在潜在的风险，恶意用户或者会利用这些信息来寻找漏洞，发起对服务的。

反例：http://api.example.com/cgi-bin/get_user.php?user=100

• 规则统一的URI，确保采用统一的规则和风格，方便用户记忆和使用。下述反例中第一个URI采用了查询参数，第二个URI采用了路径参数，这两者没有保持一致，容易造成混乱。

反例：获取好友信息，http://api.example.com/friends?id=100
反例：发送消息，http://api.example.com/friend/100/messages
正例：获取好友信息，http://api.example.com/friends/100
正例：发送消息，http://api.example.com/friends/100/messages

• URI最好由名词组成。URI的全称是统一资源定位符（Uniform?Resource?Identifier），用于标识资源在互联网上的位置，类似于邮寄地址，而地址都是由名词组成的。在名词使用上也有一些需要注意的事项：其一，使用名词复数形式；其二，尽量采用多数API中使用的表示相同含义的单词；其三，通过尽可能少的单词来表示；其四，尽可能不用奇怪的缩略语等。
• 不使用空格及需要编码的字符，例如在URI中使用中文等。
• 使用连接符（-）来连接多个单词，推荐脊柱法：首先，URI里的主机名（域名）允许使用连字符而禁止使用下划线，且不区分大小写。其次，点字符具有特殊含义，为了与主机名的规则保持一致。

脊柱法：http://api.example.com/v1/users/12345/profile-image
蛇形法：http://api.example.com/v1/users/12345/profile_image
驼峰法：http://api.example.com/v1/users/12345/profileImage

3.2 查询参数

• 许多场景下需要通过API分批次获取数据，我们会经常纠结采用什么样的查询参数，业界有两种常用的参数设计（per-page与page、limit与offset），用于标识每次获取的数据量和起始位置。在分批次获取数据的过程中，数据集合中的记录可能发生增删改变，我们需要注意采用相对位置或绝对位置所带来的不同效果。

风格1：http://api.example.com/friends?per-page=50&page=3
风格2：http://api.example.com/friends?limit=50&offset=100

• 在设计过滤的参数时，业界也有一些事实标准可供参考。如果我们期望查询结果的特定属性取值跟过滤参数的取值完全相同，那过滤参数的名称通常为属性名；如果我们期望查询结果任意属性部分包含过滤参数的取值，那过滤参数的名称通常为“q”。

完全符合：http://api.example.com/v1/users?name=ken
全文搜索：http://api.example.com/v1/users?q=ken

• URI是否可以包含动词“search”？通常以搜索为主的在线服务API可以包含，除此之外建议采用名词复数形式。常用英文单词“search”和“find”都有查找的含义，但两者还是有一些细微的差别，其中“search”用于模糊搜索，而“find”用于精准查询。

模糊搜索：http://yboss.yahooapis.com/ysearch/web?q=ipod

• 某个属性究竟是作为URI路径的构成元素还是作为查询参数呢？我们可以按照以下规则来判断：如果该属性信息可以唯一定位资源，那么它就适合作为路径构成元素，否则就作为查询参数；如果该属性可以省略，那么它就是适合作为查询参数。

路径元素：http://api.example.com/v1/users/{id}
查询参数：http://api.example.com/v1/users?name=ken

3.3 HTTP方法

按照HTTP协议设计的本意，URI用于标识目标对象（资源），而HTTP方法则是表示操作方法。基于HTTP协议的简单对象访问协议SOAP逐渐被RESTful的原生HTTP协议取代，我们也没有必要画蛇添足，最好就是吃透HTTP协议，充分利用它的特性。

GET /v1/users/123 HTTP/1.1
Host: api.example.com

• GET，获取资源
• POST，新增资源
• PUT，更新已有资源
• DELETE，删除资源
• PATCH，更新部分资源
• HEAD，获取资源的元信息

如果遇到上述HTTP方法无法覆盖的场景，那通常是资源的设计粒度太大了，我们可以把粗粒度的资源分解成多个细粒度的资源。在使用HTTP协议设计WEB API的专业能力上，业界将其划分为四个层级，LEVEL3相对较理想化，缺乏实施的基础，LEVEL2是切实可行的：

• LEVEL 0：使用HTTP
• LEVEL 1：引入资源的概念
• LEVEL 2：引入HTTP动词（GET/POST/PUT/DELETE等）
• LEVEL 3：引入HATEOAS概念

3.4 响应数据

常用的数据格式有：html、XML、JSON、YAML等，如果我们的服务在响应时支持不同类型的数据格式，那应用在调用服务时如何获得期望格式的响应数据呢？通常我们可以考虑采用下述几种指定数据格式的方法：

• 使用查询参数的方法：

示例：https://api.example.com/v1/users?format=xml

• 使用扩展名的方法：

示例：https://api.example.com/v1/users.json

• 使用在请求首部指定媒体类型的方法，优先推荐此种方法：

GET /v1/users
Host: api.example.com
Accept: application/json

响应数据应该包含哪些信息呢？是否越多越好？亦或越少越好，仅仅包含ID？建议是按需返回，根据业务功能所需返回相应的数据。如果一个WEB API需要提供给不同业务场景使用，不同业务场景对数据属性信息的要求不同，或多或少，这种情况我们可以让用户来选择响应的内容，选择方法就是通过查询参数指定：

示例：http://api.example.com/v1/users/123?fields=name,age

响应数据的结构应该尽量扁平化，不要嵌套太深，减少没有具体含义的信息载荷，这样既可以压缩报文尺寸，又可以节省带宽的。当然，如果层级结构更具优势，也可以采用。

3.5 出错信息

建议通过HTTP协议首部的状态码来表示出错信息，而不是再封装一层，遵守协议规范的好处是可以减少沟通的成本，也可以利用许多成熟的软硬件产品来处理异常出错信息。HTTP协议定了了五种类型的状态码：

• 1XX：消息
• 2XX：成功
• 3XX：重定向
• 4XX：客户端原因引起的错误
• 5XX：服务器端原因引起的错误

我们需要每种状态码的使用场景，确保正确使用状态码。除此之外，服务还需要向客户端返回详细的出错信息，我们通常可以采用下述两种方法来传递详细的出错信息：

• 方法1：定义私有的首部，将其填入响应消息的首部。
• 方法2：将详细的出错信息放入消息体。

3.6 版本管理

随着业务的发展，每个发布上线的WEB API都存在更新修改的可能，那就需要引入版本管理的机制。业界有三种常见的标注WEB API版本的方法：

• 在URI中嵌入版本编号：

示例：http://api.linkedin.com/v1/people

• 在查询字符串里加入版本信息：

示例：http://api.example.com/users/123?v=2

• 通过媒体类型来指定版本信息

Accept: application/vnd.github.v3+json
Content-Type: application/vnd.github.v3+json

同样，版本编号也存在业界规范：语义化版本控制（Semantic Versioning）规范，网站地址：http://semver.org。版本编号由点号连接的3个数字组成，例如：1.2.3，分别表示主版本编号、次版本编号、补丁版本编号，版本编号的增加遵循下述规则：

• 在对软件进行不向下兼容的变更时，增加主版本编号；
• 在对软件进行向下兼容的变更或废除某些特定的功能时，增加次版本编号；
• 如果软件的API没有发生变更，只是修正了部分bug，则增加补丁版本编号。

按照版本编号增长的规则，WEB API的版本编号只需要标注主版本编号就可以了，因为次版本编号、补丁版本编号的增加都可以做到向下兼容，不会影响用户使用，唯有主版本编号增加才需要用户更新升级。除了标注版本信息之外，我们在对外发布WEB API时还需要设计好版本变更的策略，例如：老版本提供多久的过渡期、同时兼容多少个版本、特定版本的终止日期等等。

4. 总结

何为优美？就是符合大众审美的，对于WEB API来说，就是符合标准规范的，这有利于降低用户学习和使用的成本，便于交流，不存在隐没成本。通常，业界存在的标准规范和事实标准都是经过实践筛选出来的，从遵循模仿开始，然后再找机会创新，而不是一上来就重复发明轮子。

WEB API设计领域的标准规范就是URI、HTTP等，我们要最大程度地利用这些协议规范，让每个WEB API都是用户友好（易于使用）、技术友好（支持缓存、易于更改）的。除此之外，我们还需要考虑WEB API的健壮性，下一次我们再来谈一谈如何设计健壮的WEB API，欢迎大家找我讨论交流相关话题。

今天先分享到这里，坚持原创不易，如果你觉得有价值，麻烦动动手指点下文 「