API 设计 — 优化团队的 API 设计流程
2024年11月7日
在之前 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 设计流程等内容感兴趣，我们在 E+ 有更深入的讨论，会讨论 API 测试、API 设计指南、API 文件化等议题。有兴趣的读者，欢迎加入 E+ 成长计划。，
本文为 E+ 成长计划的深度内容，截取前三分之一开放免费阅读。欢迎加入 E+ 成长计划阅读完整版本 (点此了解 E+ 的详细介绍)