今天，我们该根据之前所学，来谈谈具体怎样设计 Web API 接口了。我们围绕的核心，是**“权衡”（trade-off）**这两个字，事实上，它不只是 Web API 接口设计的核心，还是软件绝大多数设计问题的核心。
我们说“没有银弹”，是因为没有一种技术可以百搭，没有一种解决方案是完美的，但一个优秀的全栈工程师，是可以从琳琅满目的同类技术中，因地制宜地选择出最适合的那一个。
普通的 API 要包括 功能、性能、入参、返回值…… 的特性，在 Web API 中也全都存在。而且，因为 Web 的特性，它还具备我们谈论普通 API 时不太涉及的内容：
正是有了 Web API，网络中的不同应用才能互相协作，分布式系统才能正常工作，互联网才能如此蓬勃发展。而我们，不能只停留在“知道”的层面，还要去深入了解它们。
关于Web API 的设计步骤，不同人有不同的理解，争论不少，涉及到的内容也非常广泛。这里我综合了自己的经验和观点进行介绍，希望你能有所启发
和普通的 API 设计、程序的库设计一样，Web API 并不是东打一枪，西打一炮的。想想写代码的时候，我们还要让同类型的方法，以某种方式组织在类和对象中，实现功能上的内聚呢，一个类还要遵循单一职责的原则呢
因此，一组 Web API，就是要专注于一类问题，核心问题必须是最重要的一个。
这里有两件事情需要你考虑，一个是需求，一个是限制。我们虽然经常这样分开说，但严格来说，限制也是需求的一种。比方说，如果对网络传输的效率要求很高，时延要求很短，这就是需求，而且是非功能性的需求
大多数功能性的需求大家都能意识到，但是一些非功能性的需求，或者一些“限制”就容易被忽略了。比如说，向前的兼容性，不同版本同时运行，鉴权和访问控制，库依赖限制，易测试性和可维护性，平滑发布（如新老接口并行），等等。
再来说说承载技术。承载技术指的是实现接口，以及它的请求响应传输所需要使用到的技术集合，比如 HTTP + JSON。我们前面提到的要求网络传输效率高、时延短，Protobuf 就是一个值得考察的技术；但有时候，我们更需要消息直观、易读，那么显然 Protobuf 就不是一个适合的技术。这里我们通过分析技术优劣来做选择，这就是权衡。
虽说 Web API 主要的工作在服务端，但在技术分析时还需要考虑客户端。特别是一些技术要求自动生成客户端，而有些技术则允许通过一定方式“定制”客户端（例如使用 DSL，Domain Specific Language，领域特定语言）。
“风格”包含的内容很多，大到怎样划分功能，小到接口的命名，都包括在内。在实际设计中，我们很少正面地去谈论具体的风格，但我们都有意无意地将其考虑在内。这里我举几个比较重要的例子，通过它，你会了解到权衡其实无处不在。
角度一：易用性和通用性的平衡，或者说是设计“人本接口”还是“最简接口”。
比如一个图书管理的接口，一种设计是让其返回“流行书籍”，实际的规则是根据出版日期、借阅人数、引进数量等等做了复杂的查询而得出；而另一种设计则是让用户来自行决定和传入这几个参数，服务端不理解业务含义，接口本身保持通用。
前者偏向“易用”，更接近人的思维；后者偏向“通用”，提供了最简化的接口。 虽说多数情况下我们还是会见到后者多一些，但二者却不能说谁对谁错，它们实际代表了不同的风格，各有优劣。
角度二：接口粒度的划分。
比如用户还书的过程包括：还书排队登记、检查书本状况、图书入库，这一系列过程是设计成一个大的接口一并完成，还是设计成三个单独的接口分别调用完成？
其实，这二者各有优劣。设计成大接口往往可以增加易用性，便于内部优化提高性能（而且只需调用一次）；设计成小接口可以增加可重用性，便于功能的组合。
两种方式都保留，让用户去选择不行吗？
行，但那样给双方带来好处的同时，也带来了更多的问题，除了风格的不一致，接口也不再是正交的，而是有一定重叠性的，并且更多的接口意味着更多的开发和维护工作。这些接口要像是一个人设计出来的，而不是简单的组合添加，风格统一也是一致性的一种表现。因此，多数情况下我们不那么做。你看，这又是权衡。
但是，我说的是“多数情况下”我们不那么做。在一些极端情况下，我们是会牺牲掉一致性，保留冗余的。
在上面这三步通用和共性的步骤完成之后，我们就可以正式跳进具体的接口定义中，去确定 URL、参数、返回和异常等通用而具体的形式了。还记得前文中对 REST 请求发送要点的分解吗？在它的基础上，我们将继续以 REST 风格为例，进行更深刻的讨论。
我们在前文的例子中使用 HTTP GET 请求从图书馆获取书本信息，从而完成增删改查中的“查”操作：
/books/123
/books/123/price分别查询了 ID 为 123 的图书的全部属性，和该图书的价格信息。
但是，实际的查所包含的内容可远比这个例子多，比如不是通过 ID 查询，而是通过条件查询：
/books?author=Smith&page=2&pageSize=10&sortBy=name&order=desc除了使用 Query String（问号后的参数）来传递查询条件，多级路径也是一种常见的设计，这种设计让条件的层级关系更清晰。比如：
/category/456/books?author=Smith它表示查询图书分类为“艺术”（编号为 456）的图书，并且作者是 Smith。看到这里，你可能会产生这样两个疑问。
疑问一：使用 ID 多不直观啊，我们能使用具体名称吗？
当然可以！可以使用具备业务意义的字段来代替没有可读性的 ID，但是这个字段不可重复，也不宜过长，比如例子中的 category 就可以使用名称，而图书，则可以使用国际标准书号 ISBN。于是 URI 就变成了：
/category/Arts/books?author=Smith疑问二：category 可以通过 Query String 传入吗？比如下面这样：
/books?author=Smith&category=Arts当然可以！“category”可以放置在路径中，也可以放置在查询参数串中。这是 REST 设计中的一个关于设计上合理冗余的典型例子，可以通过不同的方式来完成相同的查询。如果你学过 Perl，你可能听过“There’s more than one way to do it”这样的俗语，这是一样的道理，也是 REST 风格的一部分。
当然，从这也可以看出前文我们提到过的，REST 在统一性、一致性方面的约束力较弱。
有时候我们还需要传递消息正文，比如当我们使用 POST 请求创建对象，和使用 PUT 请求修改对象的时候，我们可以选择使用一种技术来封装它，例如 JSON 和 XML。通常来说，既然我们选择了 REST 风格，我们在相关技术的选择上也可以继续保持简约的一致性，因此 JSON 是更为常见的那一个。
{
"name": "...",
"category": "Arts",
"authorId": 999,
"price": {
"currency": "CNY",
"value": 12.99
},
"ISBN": "...",
"quantity": 100,
...
}上面的消息体内容就反映了一本书的属性，但是，在设置属性的时候，往往牵涉到对象关联，上面这个小小的例子就包含了其中三种典型的方式：
HTTP 协议中规定了返回的状态码，我想你可能知道一些常见的返回码，大致上，它们分为这样五类：
错误处理是 Web API 设计中很重要的一部分，我们需要告知用户是哪个请求出错了，什么时间出错了，以及为什么出错。比如：
{
"errorCode": 543,
"timeStamp": 12345678,
"message": "The requested book is not found.",
"detailedInformation": "...",
"reference": "https://...",
"requestId": "..."
}在这个例子中，你可以看到上面提到的要素都具备了，注意这里的 errorCode 不是响应中的 HTTP 状态码，而是一个具备业务意义的内部定义的错误码。在有些设计里面，也会把 HTTP 状态码放到这个正文中，以方便客户端处理，这种冗余的设计当然也是可以的
除了 URL、参数与状态码，还有两个设计决策需要在接口定义阶段明确：
Idempotency-Key 请求头 + 服务端去重）来兜底。/v1/books，最直观、最常见）、Query 参数（/books?version=1）或请求头协商（Accept: application/vnd.example.v1+json）。同一服务内只保留一种版本化策略，避免风格分裂。