https://www.cnblogs.com/itlaobingge/p/12089657.html

概述

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

评判标准

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

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

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

设计规范

URI

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

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

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

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

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

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

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

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

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

1	反例：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 里的主机名（域名）允许使用连字符而禁止使用下划线，且不区分大小写。其次，点字符具有特殊含义，为了与主机名的规则保持一致。

1
2
3

脊柱法：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

查询参数

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

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

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

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

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

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

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

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

HTTP 方法

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

1 2	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 概念

响应数据

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

使用查询参数的方法：

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

使用扩展名的方法：

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

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

1
2
3

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

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

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

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

出错信息

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

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

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

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

版本管理

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

在 URI 中嵌入版本编号：

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

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

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

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

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

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

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

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

总结

何为优美？就是符合大众审美的，对于 WEB API 来说，就是符合标准规范的，这有利于降低用户学习和使用的成本，便于交流，不存在隐没成本。通常，业界存在的标准规范和事实标准都是经过实践筛选出来的，从遵循模仿开始，然后再找机会创新，而不是一上来就重复发明轮子。
WEB API 设计领域的标准规范就是 URI、HTTP 等，我们要最大程度地利用这些协议规范，让每个 WEB API 都是用户友好（易于使用）、技术友好（支持缓存、易于更改）的。

如何设计出优美的 Web API？

概述