曾几何时，良好的 API 设计被认为是 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 文章、培训、教程等的电子邮件。 订阅