【翻译】What is API Design (And Why Does It Matter?)

最新推荐文章于 2022-05-17 19:29:25 发布

Mikemax

最新推荐文章于 2022-05-17 19:29:25 发布

阅读量162

点赞数

原文链接：https://my.oschina.net/u/2422879/blog/2051863

版权

构建API很难。除了需要和业务相关者进行长时间的讨论，选择合适的技术栈已经构建合适的数据分发模型外，还有许多细节可以忽略不计。在21世纪伟大的API运动之后 - 随着社交媒体的出现和移动技术的普及，组织已经意识到API的增长机会。

但你要注意你的API。它可能是你最好的朋友，也可能成为你最大的负担。在使用API时，糟糕的用户体验将导致无休止的服务支持甚至是扯皮，接着声誉就会败坏，这一切将导致你的服务不可靠。因此，在实际开始实施API之前，进行更多计划，规划和计划非常重要。这就是RESTful API描述格式的设计和惊人的实力，如OpenAPI规范和API蓝图。

定义API设计

当我第一次听到这个词的时候，我以为它的意思是用一种美观的方式来编写语法和代码。虽然这是一部分，但API设计涉及的远不止您编写语法的方式。设计API意味着提供一个有效的接口，帮助您的API使用者更好地理解、使用和集成API，同时帮助您有效地维护它。每个产品都需要使用手册，您的API也不例外。 API设计应包含：

资源结构
资源文档

有许多与上述相关的良好实践，我将在后续的博客文章中介绍。现在，让我们首先了解为什么您的API应该具有出色的设计的重要性。

有助于更好地实施

API的设计是您希望实现的API的坚实蓝图，并全面概述了与每个端点相关的所有端点和对应的CRUD操作。一个有效的API设计可以极大地帮助实现和防止复杂的配置。设计过程还将帮助您准确地考虑您的数据将如何分布以及您的核心产品将如何工作。

促进增量开发

API开发是一个持续的过程。任何不这么认为的公司都没有充分利用API的潜力。随着您的产品和服务的发展，您的API也应如此。拥有清晰的设计有助于您的组织和团队确切地知道需要更新哪些资源或子资源，从而避免混淆和混乱。API越大，管理它就越困难。精心设计的API可以防止重复工作，并帮助开发人员确切地知道哪些资源需要更新以及哪些资源应该停用。

促进更好的文档

文档对于构建使用API的接口至关重要。在许多情况下，只有在映射出API的资源和响应请求周期之后，才能全面完成文档。强大的初始结构，将帮助负责处理文档的人员能够更快地记录API，减少错误。通过优秀的设计可以让文档的流程自我优化，从而构建全面的接口。

改善开发者体验

开发者体验（DX）至关重要。如果您是一名开发人员，你很有可能使用和集成一个让您抓狂到要摔电脑的服务。我们都经历过一次让我们在StackOverflow和Reddit上花费无数小时的网络服务，试图找出如何使用它。良好的API设计使终端开发人员的生活变得轻松。它可以快速地理解所有资源组织、与之交互的乐趣和轻松的视觉效果，因此使用您的API的人可以获得完美的使用体验。