构建 API 并非易事。除了与业务利益相关者进行冗长的会议、选择合适的技术栈以及构建适当的数据分发模型之外，还有许多细枝末节容易被忽视。在 21 世纪的 API 运动浪潮之后——随着社交媒体的兴起和移动技术普及的爆炸式增长—— 各组织已经意识到 API 所带来的增长机遇。
但要小心您的 API。 API 既可以是您最好的朋友，也可能成为您最大的负担。糟糕的 API 使用体验会导致无休止的支持电话，继而损害声誉，这足以使您的服务变得不可靠。因此，在实际着手实施 API 之前，进行充分的规划至关重要。 这里正是设计以及 RESTful API 描述格式（如 OpenAPI 规范 和 API Blueprint）的强大之处发挥作用的地方。
定义 API 设计
当我第一次听到这个术语时，我以为它指的是以一种美观的方式编写语法和代码。虽然这是其中一部分，但 API 设计所包含的远不止您编写语法的方式。设计 API 意味着提供一个有效的接口，帮助您的 API 消费者更好地理解、使用和集成它们，同时帮助您有效地维护它。每个产品都需要一份使用手册，您的 API 也不例外。 API 设计应包含：
- 资源的结构
- 您的资源的文档
上述内容有许多相关的良好实践，我将在后续的博客文章中进行介绍。现在，我们首先来理解为什么您的 API 应该有一个出色的设计的重要性。
有助于更好的实现
API 的设计是一个坚实的蓝图，它描绘了您的 API 想要实现的目标，并提供了所有端点及其关联的 CRUD 操作的全面概述。 有效的 API 设计可以极大地帮助实现，并避免复杂的配置、类中命名方案的一致性问题，以及其他可能让您几天睡不着觉的问题。设计过程还将帮助您仔细思考数据将如何分发以及您的核心产品将如何运作。
有利于增量开发
API 开发是一个持续的过程。任何持不同看法的公司都没有充分利用 API 的全部潜力。随着您的产品和服务的演进，您的 API 也应如此。拥有清晰的设计可以帮助您的组织和团队准确地知道哪些资源或子资源需要更新，从而避免混乱。 API 规模越大，管理起来就越困难。精心设计的 API 可以避免重复工作，并帮助开发人员准确了解哪些资源需要更新，哪些应该被淘汰。
有利于更好的文档
文档对于构建让您的 API 得以被消费的接口至关重要。在许多情况下，全面的文档工作只有在 API 的资源和响应-请求周期被映射出来之后才能完成。 一个坚实的初始结构使得负责处理文档的人员能够更快、更少出错地编写 API 文档。通过出色的设计作为基础来构建全面的接口，文档过程可以实现更好的自我优化。
改善开发者体验
开发者体验（DX）至关重要。如果您是一名开发者，您很可能曾经不得不使用并集成某个让您想砸电脑的服务。我们都曾遇到过那种让您在 StackOverflow 和 Reddit 上花费无数小时来试图弄清楚如何使用的网络服务。 一个好的 API 设计让最终开发者的生活变得轻松。它易于理解，所有资源都井井有条，交互起来很有趣，并且界面友好，因此使用您 API 的人将拥有完美无瑕的体验。
结论
良好的 API 设计能提高 API 的可用性，从而带来更高的采用率、减少麻烦，并为您的 API 工作带来更好的成功机会。虽然我已经阐述了 API 设计的重要性，但将其付诸实践可能很困难。高效的设计需要练习。在我接下来的博客文章中，我将尝试阐述一些设计 API 时的良好实践。
感谢阅读！寻找更多 API 资源？订阅 Swagger 时事通讯。每月通过电子邮件获取我们最好的 API 文章、培训、教程等。