开放平台

为什么开放平台大多选择了 RESTful 风格？

APILetter
~ 白宦成 ~ Leave a comment

大型互联网平台会提供一些开放平台，并提供一定的开放能力，帮助开发者基于自己的平台进行二次开发，拓展平台之上的应用生态。而在这些开放平台当中，最常见的便是采用 RESTful 风格的开放平台，比如 GitHub、Microsoft、Google、Twitter、StackOverflow。

如果说用一个偷懒的想法，那我们可以得出一个结论 —— RESTful 一定做对了什么，不然不会这么多平台都愿意选择它。

考虑到我们的 Newsletter 是一个面向开发者、To Dev 业务的产品经理的邮件，就不再详细介绍 RESTful 是什么，如果你感兴趣，可以去看看 Fielding R T. Architectural styles and the design of network-based software architectures[M]. University of California, Irvine, 2000 这篇论文。国内的技术劳模阮一峰老师也有一篇文章阐述 RESTful 架构：理解RESTful架构。

如果用一句话来描述 RESTful 风格做对了什么？我想它应该是「RESTful 风格的 API 通过将方法抽象回资源，面向资源提供操作的方式，简化了 API 的设计，减少使用 API 所需要的上下文，用最简单的方法为我们提供了各种各样不同的操作的可能。」

举个🌰

个简单的对比的理解，以创建一篇博客文章为例，我们所熟悉的 Internal API （应用内部的 API，没有特定的风格）和 RESTful API 的区别如下：

Internal API 下的创建文章

POST /create-post

{
  "title":"xxx",
  "content":"xxx"
}

RESTful API 下的创建文章

POST /posts

{
  "title":"xxx",
  "content":"xxx"
}

看起来，好像也没什么不同，啊哈？那我们再看看根据 ID 获取文章的区别：

Internal API 下的根据 ID 获取文章

POST /get-post-by-id

{
  "id":123
}

RESTful API 下的根据 ID 获取文章

GET /posts/123

{
}

看获取文章，似乎有那么点意思了，显然，我们所习惯使用的 Internal API 比 RESTFul API 的风格的路径更长，也更喜欢用 POST。当然，这也完全可以接受。我们可以再举个例子，既然有根据 ID 获取文章，是不是还可以根据标题来获取文章：

Internal API 下的根据标题获取文章

POST /get-post-by-title

{
  "title":"xxx"
}

RESTful API 下的根据标题获取文章

GET /posts/?title=xxx

{}

你可以看到， 在 Internal API 当中，我们为了提供获取标题的方式，不得不又写了一个新的路径，一个新的方法，来实现类似的功能。而在 RESTful 当中，我们只是在创建文章的路径当中，提供了一个不同的 Query Param，来完成查询。

实际上，如果我们的文章提供了不同的参数，我们又要针对这个文章提供各种不同类型的搜索条件（相信你肯定在各种中后台管理系统当中看到各种各样的筛选器），在 RESTful API 当中，你只需要在同一个路径上叠加不同的 Query Param 即可，而在传统的 Internal API 当中，你可能需要设计不同的方法来实现。

为开发者省时间的 RESTful 风格

RESTful 风格的 API 不再面向具体的操作来设计，而是将具体的操作抽象为不同的资源和对应的资源的操作，来降低开发者实际在使用这些 API 的成本。

在 RESTful 风格下，一个开发者唯一知道的，便是资源的命名，剩下的便都是交给 RESTful 风格的规范来完成的。

  • 如果开发者知道对应的资源是叫 User，那么他就知道获取所有用户使用 GET /users，获取某个用户就是 GET /users/ID，创建用户就是 POST /users，删除一个用户使用DELETE /users/ID。
  • 类似的，如果他需要操作邮件的对象，则是把 URL 当中的 users 替换为emails，仅此而已。

开发者不需要每次打开文档去猜测 API 到底是 camelCase 、snake_case、PascalCase 还是 kebab-case，也无需猜测每个 API 应该使用什么 HTTP 方法发出请求，开发者只需要遵循 RESTful 规范去请求接口即可。

为平台方省设计的 RESTful 风格

对于服务提供来说，RESTFul 风格也提供了简化设计的可能。举个例子来说，假设我们有一个相对比较复杂的用户数据，如果开发者不能很好的抽象，带来的可能是一系列复杂的接口，让我们的维护成本疯狂提升。随着数据结构本身的复杂，要实现、维护的接口的数量也在不断的增多，需要投入的人力也不断的变多。

举个例子来说，假设我们的平台上有一个 User 对象，他的结构如下面的 JSON 所示：

{
  "id":1, // ID
  "name":"张三", // 姓名
  "nick_name":"小张", // 昵称
  "former_name":"张老三", // 曾用名
  "login":"zhangsan2022", // slug
  "i18n_names": {
     "en":"Sam Zhang" // 英文名
  },
  "blog":"http://example.com" //个人博客
}

由于使用开放平台的用户可能在开放平台上有各种各样不同的用法和操作，所以我们可能需要为用户提供一系列的方法，来帮助用户实现不同目的下的数据查询。你可能不得不提供一系列的 API：

  • GetUserById
  • GetUserByName
  • GetUserByNickName
  • GetUserByFormerName
  • GetUserByLogin
  • GetUserByBlog
  • …

而同样的问题，放在 RESTful API 当中，只需要一个 /users? 就可以完成了，剩下的便是在 Query Param 当中去叠加各种不同的判断规则，简单但直接。对于一个开放平台来说， RESTful 风格将过去可能需要用 N 个方法才能实现的方式收拢成一个方法，大大降低了持续维护的成本。

不严谨的的 RESTful 风格

说了那么多 RESTFul 风格的好处，也来说一说 RESTful 风格的坏处。

  1. 没有明确的规范，只有一个指导思想：RESTful 风格的提出者 Roy Thomas Fielding 在自己的博士论文Fielding R T. Architectural styles and the design of network-based software architectures[M]. University of California, Irvine, 2000.当中提出了 RESTful 风格的设计，但并未详细的指明具体的设计细节，所以对于实际落实到工业生产环境过程中，往往会衍生出不同的风格，比如 Google 的 RESTful API 规范和 Microsoft 的 RESTful API 规范就并不相同。他 2008 年写的一篇文章轻描淡写的说自己当时没写细则是因为没时间了。但论文发表了 8 年时间，也没见写第二篇论文解释细则。。。
  2. 对于资源的抽象要求非常高，很容易抽象错：RESTful 风格看起来是否简单，面向资源设计是个人就行。但落实到实际应用场景中，就没这么容易了。
    1. 一个最容易引发讨论的点便是：如何表现出数据结构之间的关系？常见的做法是在路径里展示出关系，比如用户的文章是 /users/1/posts ，但在 Roy 2008 年的文章《REST APIs Must be hypertext-drivern》当中给出的答案是，应该抽象出一个更高层的资源来完成这个筛选，路径中不应该包含关系。
    2. 另一个容易引发讨论的点是批量操作：你如何设定一个批量操作？比如批量创建用户，或者是批量发送消息？你可能会单独设计出一个 /message/batch_send 的方法，但在 Roy 2008 年的文章《REST APIs Must be hypertext-drivern》当中给出的答案是，你应该设计一个全新的资源抽象，来确保整个 API 架构是稳定、一致的。

选择 RESTful 风格，归根还是省钱

RESTFul 风格的好处和坏处都很明显 —— 好处是他提供了简化的实现，统一的表现，最小惊讶原则的落实，让开发者只需要知道资源的信息，便可以进行具体的操作，而无需担心众多的 API 存在各种不同的设计风格和设计实现。开发者需要自行编写 SDK 来完成各种不同的操作。毕竟，RESTful 本身就是基础的 HTTP 操作。

而作为一个已经提出了 20 余年的 API 设计风格，RESTful 已经拥有了丰富的开发者共识（大部分开发者可能不熟悉 RESTful API ，但看到了，大多能猜到是 RESTful 风格，也能用起来 RESTful 风格的 API ）、抽象也更统一（RESTful 虽然没定义特别多细节，但一些基础的逻辑也是定义了的，比如 URL 里不能包含动词），对于开放平台这样需要大规模的和外部开发者交互的平台来说，无疑是成本更低的。

评语

RESTful 风格有着其明确的优势，但同样，他的劣势（定义不明确、抽象要求高）使得大部分我们所见的的 RESTful 风格都不那么 RESTful（也并没有人能定义谁更 RESTful），更重要的是，RESTful 的使用体验，并不一定真的就比 Internal API 更好。很多时候，它只是一种无奈的选择。

而未来，能够提供更加丰富的组合能力的 GraphQL ，可能是一个选择。不过，想要做好 GraphQL，你要先做好基础的 RESTful 资源抽象，才好在真正进入 GraphQL 的时代，快速发展。