曾经，优秀的 API 设计被 API 团队认为是“锦上添花”。但在当今的 API 经济中——API 是业务战略的驱动力，API 的可用性使组织能够更好地从单体架构过渡到微服务架构——优秀的设计从未如此重要。
理解 API 设计
API 设计意味着提供一个有效的接口，帮助你的 API 的消费者（内部和外部）更好地理解、使用和集成它们，同时帮助你有效地维护它。 一般来说，一个设计良好的 API 应该是：
- 易于阅读和使用：一个设计良好的 API 将易于使用，并且其资源和相关操作可以很容易地被最终消费者理解。
- 难以误用：实施和集成一个设计良好的 API 将是一个直接的过程，并且编写错误的代码将不太可能发生。
- 完整且简洁：一个完整的 API 将使开发人员能够根据你公开的数据制作完整的应用程序。
良好的 API 设计的目标应该是使最终消费者在使用你的 API 时尽可能地成功。对于内部 API，改进的可用性将提高开发人员通过你的 API 使用服务的生产力。它还可以在开发 API 后端并创建其支持文档时提供更好的工作流程。 对于面向外部的 API，良好的 API 设计将导致用户采用率的提高，并且最终消费者更容易理解你的 API 提供的价值。
OAS 在 API 设计中的作用
对 API 设计的日益关注导致 API 描述格式的采用激增——RESTful API 的标准格式是 OpenAPI (Swagger) 规范。OAS 提供了一种与语言无关的格式来描述你的 API，这种格式既可以被人读取也可以被机器读取。 OAS 的机器可读组件允许工具实现和扩展 API 的功能。这可以使用像 SwaggerHub 这样的工具来自动构建漂亮、交互式的 API 文档，同时使用此设计之上构建代码，并为你的 API 生成服务器和客户端库。当你准备好后，此描述还可以用于开始构建 API 的测试用例。 为设计 API 提供人类可读格式的好处更加直接——你的整个团队（开发人员和非开发人员）以及最终消费者都可以轻松理解 API 应该做什么，以及如何最好地使用 API。它通过为你的团队在开始编码之前协作设计 API 提供了一个单一的焦点，从而打开了设计过程。
设置设计流程
如今，数千个 API 团队使用 OAS 和 Swagger 工具来设计 API。团队实施和维护 API 设计所遵循的流程会因多种因素而异，包括：最终消费者、API 的数量以及 API 计划的战略和业务目标。 对于那些 API 设计之旅早期阶段的团队来说，建立可扩展的 API 设计流程不会是一个主要考虑因素。但是随着你的 API 计划的发展，可能会出现一些挑战。我们从团队那里听到的一些最常见的设计挑战包括：
- 托管和维护 API 设计文件：许多团队会依赖内部解决方案或像 GitHub 这样的源代码控制工具，这些工具是为存储代码而构建的，而不是设计文件。
- 处理 API 设计的版本控制：团队需要一个解决方案来处理多个 API 版本，并确保最新版本可用并在使用中。
- 跨团队迭代 API 设计：当不同的团队处理现有 API 的开发和文档时，处理现有 API 的设计更改至关重要。
- 设置和强制执行样式指南：如何确保你的团队遵循你为内部和外部 API 设置的设计标准？
感谢阅读！正在寻找更多 API 资源吗？订阅 Swagger 新闻通讯。每月收到一封包含我们最好的 API 文章、培训、教程等的电子邮件。订阅