(转）这样设计 RESTFul API，也许能让你效率倍增

在目前移动端、前端趋于统一的大背景下，基于 RESTFul 的 API 也大放异彩，我们需要越来越多的与 API 打交到，设计可扩展，易于维护的 API 在我们的工作中也变得更加重要。那么，有没有可能，通过一定测策略与指导方法，让 API 的设计更规范，更有章可循，高效率的设计出好用的 API 呢？本文尝试总结笔者在这方面的思考，希望对读者有所启发。

在开始之前，我们先做一个定义，那就是什么样的 API 能够算得上优秀的 API，如下是笔者认为优秀 API 需要满足的四个要素：

1. 遵循业界最佳实践
2. 高度的统一性和一致性，优秀的 API 一定是高度一致和统一的，遵循一定的共性和约定
3. 基于深刻理解业务的合理抽象
4. 探索业务共性，总结规范

这四个要素层层递进，亦可以作为我们进行 API 设计的指导方法，下面详细介绍笔者对这四个要素的理解，必要的时候提供案例进行说明。

遵循业界最佳实践

遵循业界最佳实践我觉得是优秀 API 应具备最基本的一个要素，它能让相关人员最快的理解，建立统一的基础认知，如果我们的 API 对外的，这就显得更加重要。

就本文而言，笔者所说的业内最佳实践指的是基于 HTTP 的 RESTful API。它用 URI 表示资源，用 HTTP Verb 表示操作，要设计好 RESTFul API，很大程度上需要处理好对资源的抽象。

至于 RESTFul API 更具体是个什么东西，有哪些原则，本文不做更多探讨，互联网上相关的资料很多。

高度的统一性和一致性

如果说遵循业界最佳实践是基础，那么保持 API 的统一性和一致性就是设计合格 API 的保障。如果我们的 API 不统一、不一致，缺少必要约定，使用者必然会感到困惑，学习成本与维护成本必然大大增加。

下面是保证 API 高度统一和一致性需要考虑的一个列表，也许并不完整：

1. 授权与鉴权方式的统一
2. 每个 API 分页方式与对应参数的统一
3. 排序参数与对应行为的统一一致
4. 查询条件的写法经事先约定且保持一致
5. 考虑存在于全局的参数，形成基础认知
6. 等等等

深度理解业务的高度抽象

如果我们的 API 满足了前面两个要素，那它应该基本算是合格了，能够满足日常业务的需要，但对于优秀的 API，这才刚刚开始。

许多人在设计 API 的时候，没有大局观，仅仅为界面而设计，只有前台界面一变化，API 可能又需要重新设计，从而导致 API 扩展性差，频繁修改。

所以，我们在设计 API 的时候，就需要站在更高的维度，在深入理解业务的前提下，抽象出更高层次的 API。这样的 API 一般是界面无关的，即便界面变化，只要不是业务的调整，影响也不会很大。

优秀的 API 就像优秀的产品，不在于提供了多少 API （功能），而在于解决了多少问题。一个优秀的 API 能直接解决多个一般 API 才能解决的问题。

下面举一个例子：

假如，我们有这样一个需求，在一个博客系统中，我们需要获取全站访问最多和访问最少的文章，各n篇文章，应该怎样设计 API 呢？
有下面两个版本：

版本一:

提供两个API，如下：

GET /posts/most-viewed?limit=10 - 获取访问最多的文章
GET /posts/least-viewed?limit=10 - 获取访问最少的文章
版本二：
提供一个API，使用sort参数排序，间接实现需求

GET /posts?sort=total_views desc&limit=10 - 获取访问最多的文章
GET /posts?sort=total_views asc&limit=10 - 获取访问最少的文章
笔者认为，版本二会更好一些，直接使用已有 API 加排序完成需求，扩展性和抽象层次都更高。
探索业务共性，总结规范

每个业务都可能有它的共性，如果把这些共性提炼出来，形成规范，就会极大的提高 API 的设计及开发效率，API 的使用也会因此受益，因为整体 API 的理解会容易许多。

就比如笔者目前所在的公司，面临许多 toB 业务，有许许多多的聚合统计需求，如果把每个统计需求都写成单独的API，那 API 的数量恐怕浩如烟海，也很难维护。

所以，我们就在思考，如何把这些共性的统计需求就行抽象，总结成规范，变成 API 设计规范的一部分，从而指导 API 设计。

比如说，我们有如下的业务需求：

用户的状态（status）有 active, disabled 和 achieved 三种，需要统计满足条件用户三个状态各自的数量。
在我们目前API设计规范下，我们会用如下的方式解决这个需求，而非提供新的 API：

GET /users?kw=foo&$aggregate=status 按 status 就行聚合统计，kw是查询参数
这里我们引入了 $aggregate 的聚合方法，在不添加新 API 的情况下解决该需求，该方式也变成解决该类问题规范。

设计优秀 API 的四个要素介绍完了，希望对你有所帮助，以后笔者会再分享 API 规范的设计思路~

2017年2月18日