构建 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) 至关重要。如果你是一名开发者，你很可能不得不与让你想砸电脑的服务进行工作和集成。我们都经历过这样一个 Web 服务，它让我们在 StackOverflow 和 Reddit 上花费了无数个小时来试图弄清楚如何使用它。 良好的 API 设计使最终开发人员的生活变得轻松。它易于理解，所有资源都组织良好，交互有趣且赏心悦目，因此使用您的 API 的人们可以获得完美的工作体验。
结论
良好的 API 设计提高了 API 的可用性，从而提高了采用率、减少了麻烦，并为您的 API 努力带来了更好的成功机会。虽然我已经阐述了 API 设计的重要性，但将其付诸实践可能很困难。高效的设计需要实践。在我即将发布的博客文章中，我将尝试列出一些设计 API 时的良好实践。
感谢您的阅读！正在寻找更多 API 资源？订阅 Swagger 新闻通讯。每月收到一封电子邮件，其中包含我们最好的 API 文章、培训、教程等。