API 设计 — 优化团队的 API 设计流程

在之前 API 设计的文章，我们谈了 API 设计 — 好的 API 设计有什么特点？、API 设计 — 如何设计稳定可相容的 API。

而在这篇文章中，我们将把视角转换到资深工程师的角度，来谈假如今天你想迈向资深工程师，想要让团队整体的 API 品质可以提升，该如何做到?

我们将会从 API 设计流程、API 设计指南，以及文件化等要点切入。推荐读者可以在读的同时，思考目前所在的团队，有没有某个面向可以优化，并试着推动改善。（完整内容收录在 E+ 成长计划当中）。

API 设计流程

在谈 API 设计流程前，推荐读者自己可以先想一下，在设计 API 时该有哪些阶段? 为什么需要有这些步骤?

探索需求

在回答这个问题前，推荐读者们可以回到本质来思考，API 的存在目的，是为了服务使用 API 的人，帮忙提供某个功能或解决某个问题。因此，API 设计的流程中，最推荐从需求开始。

从需求开始意味着需要取了解使用者、了解使用情境 (use cases)，而要做到这件事的最简单方法，就是去找使用者聊、去与使用者互动。Stripe 前技术长 David Singleton 以及现任 Amazon 技术长 Werner Vogels 都表达过类似的观点。

以 Stripe 来说，前技术长 David Singleton 分享过一个原则，那就是从使用者的角度反过来开发 API (working backward from the consumer of the API)。换句话说，在开发 API 前，会先去深入了解使用者的需求，然后才进行开发，而不是直接从开发者的角度思考后就开发。

具体来说，Stripe 的 API 开发者会参与使用者研究，甚至会坐下来实际跟使用 API 的使用者一起串接 API，然后在过程中观察 API 的使用者有遇到什么困难，在过程中持续收集回馈。David Singleton 谈到在正式发布 API 前，通常会经过几轮的迭代与调整。

更进一步说，从使用者的角度反过来开发 API，也代表在实作前就先把背后还没有实际功能的 API，让使用者试接看看，来了解这样的设计，使用者实际用起来好不好懂、会不会用错。这能够避免，如果已经实作好功能后，才发现设计上不好用、有没考虑到的面向，那这样就白费那些实作的时间。

虽说要去了解使用者的需求，不过要特别注意，跟使用者互动的过程中，不要直接按照使用者说的做。因为很多时候，使用者看的角度只有眼前所见的范畴，但 API 设计者应该要想更远，要去深入思考使用者的表层需求底下，真正的根本需求是什么。

总的来说，了解需求是 API 能否设计好的关键，假如目前所在的团队，在实际设计 API 前，没有针对使用者有完整的研究流程，推荐可以试着在团队中导入。

设计

在了解完使用者的需求后，理论上 API 设计者会清楚知道：

使用者希望透过 API 做到什么 (能够回答为什么使用者需要这个 API)?
什么样的设计会让使用者觉得简单好用 (能够回答如何设计这个 API)?

如果没办法回答这两个问题，推荐先不要进到设计阶段，不然很可能之后要重头来过，浪费宝贵的时间。

如果能清楚回答上述的两个问题，接着会进入 API 的设计阶段。在设计阶段，会根据在前一阶段收敛出的要点，来进行 API 设计。这时会需要详细定义出 API 的规格、用什么风格、会如何测试等等。

在这个阶段，除了 API 的开发团队外，推荐尽可能有跨团队的角色加入，来给予开发团队回馈。

举例来说，目前业界建制比较完整的团队，通常在这个阶段，会找平台工程 (platform engineering)、开发者体验 (developer experience)、安全性 (security) 相关的团队，来给予设计上的回馈。这样可以确保除了功能需求有做到外，重要的非功能需求也能照顾到。

因此，假如你想要让团队的 API 设计整体品质提升，推荐可以试着为团队建立评论小组，去找寻公司内不同的技术专家，主动邀请他们给团队不同面向的回馈。

API 设计 — 优化团队的 API 设计流程

API 设计流程

探索需求

设计

阅读更多

API 系列文