当开始创建一个新系统，或参与一个新团队或项目时，都会面临一个简单却深刻的问题：这个系统（Web Server）的 API 是否有设计规范？

image by stable difussion, prompt by alswl

这个问题困扰了我很长时间，始于我求学时期，每一次都需要与团队成员进行交流和讨论。 从最初的自由风格到后来的 REST，我经常向项目组引用 Github v3 和 Foursqure API（已经无法访问，暴露年龄） 文档。 然而，在实践过程中，仍然会有一些与实际工作或公司通用规范不匹配的情况， 这时候我需要做一些补充工作。最终，我会撰写一个简要的 DEVELOPMENT.md 文档，以描述设计方案。

但我对该文档一直有更多的想法，它还不够完善。因此，我想整理出一份简单（Simple）而实用（Pragmatic）的 Web API 最佳实践，也就是本文。

为什么我们需要 API 统一规范

这个问题似乎很明显，但是深入剖析涉及团队协作效率和工程设计哲学。

API（Application Programming Interface，应用程序编程接口）是不同软件系统之间交互的桥梁。在不同软件系统之间进行通信时， API 可以通过标准化的方式进行数据传输和处理，从而实现各种应用程序的集成。

当我们开始撰写 API 文档时，就会出现一个范式（Design Pattern），这是显式还是隐式的， 是每个人一套还是公用同一套。这就像我们使用统一的 USB 接口一样，统一降低了成本，避免了可能存在的错误。具体来说，这有以下几个原因：

• 容易理解，提高效率：服务提供方和消费方使用统一形式、结构和使用方式，以及统一的生产消费协议，从而减少沟通成本。
• 专家经验：它包含最佳的工程实践，常见场景都有对应的解决方案，避免了每个人都要重新思考整个 API 系统。 例如，如何处理 API 缓存？如何进行鉴权？如何进行数据格式处理？
• 面向未来的扩展，需要稳定的协议：协议是抽象的、独立于实现的，不是每个人都具备 设计面向不确定系统的能力，一些广泛使用的技术则为更广泛的场景做了规划。

image by alswl

虽然使用统一规范确实有一些成本，需要框架性的了解和推广，但我相信在大部分场景下， 统一规范所带来的收益远远高于这些成本。

然而，并非所有的情况下都需要考虑 API 规范。对于一些短生命周期的项目、影响面非常小的内部项目和产品， 可能并不需要过多关注规范。 此外，在一些特殊的业务场景下， 协议底层可能会发生变化，这时候既有的规范可能不再适用。但即使如此，我仍然建议重新起草新的规范，而不是放弃规范不顾。

规范的原则

在制定 API 规范时，我们应该遵循一些基本原则，以应对技术上的分歧，我总结了三个获得广泛认可的原则：

• 简洁：简洁是抵抗复杂性的最直接和最有效的策略，利用简洁原则降低复杂度，避免复杂性的滋生和扩散；
• 一致性：统一的设计模式和延续的设计风格有助于降低工程成本和工程师的心理负担；