设计出色API的最佳实践与原则 - James


API 设计的核心是有效的沟通,不仅是开发人员之间的沟通,还包括将产品思维、业务和技术融为一体的沟通。
James Higginbotham 是《Web API 设计原理》的作者和执行 API 顾问。James 还推荐 API Design-First 方法——一种快速且轻量级的基于结果的 API 设计过程——成功设计和交付 API,包括 ADDR 过程和建立 API 边界(与 DDD 相关)。
   
原则 1:永远不应孤立地设计 API
从设计角度和编码角度重新思考我们处理 API 的方式。放慢脚步,与那些有意见、主题专业知识的各方会面,让他们与我们一起参与 API 设计,而不仅仅是推进代码。而是借此机会将其转变为以更多以产品为导向的体验为中心的东西。
 
原则 2:基于结果的关注
谁将使用 API 以及他们正在尝试做什么
 
原则 3:与需求相匹配的设计元素
是否使用 Rest API 风格?我使用 GraphQL 吗?gRPC 怎么样?当我们考虑 API 的设计元素时,我们需要考虑人们将如何使用 API。他们将在什么环境下使用它?它主要来自网络浏览设备、手机、平板电脑、笔记本电脑等吗?是基于语音的吗?是不是我们要与其他系统集成,所以我们需要一些事件?

  • GraphQL:它非常适合它的响应深入塑造加工方面,可以制作一个看起来很像数据库复杂的查询,并且我可以非常具体地说明我想要的元素。
  • 如果你有一个非常深的资源结构,你有很多嵌套的资源,你不想在查询时进行查询以越来越深入,团队会选择使用 REST 作为基础,并辅以一些 GraphQL。
  • 那么也许如果他们需要一些高性能服务来服务通信,他们会决定去 gRPC。通过内置的代码生成加快开发过程,并通过 gRPC 利用 HTTP/2 的一些性能改进来加速开发过程。一些标头和其他内置内容的压缩,以及双向通信。

 
原则 4:API 文档作为开发人员的 UI
  • 作为正在寻找全新 API 的开发人员,参考文档非常重要。参考文档是我们花费大部分时间的地方。

 
原则 5:API 是永恒的
  • 当我们考虑 Web API 时,我们不能只考虑可以重构和更改事物的代码库。只要这一切都开始编译并再次运行,我们就没事了。我们谈论的是分布式系统,其中的许多系统都不受使用它的其他人的控制。因此,那些使用您的 Web API 的人无法控制您作为提供者所做的事情,反之亦然。
  • 我们必须制定有关如何管理版本控制(以及)如何处理它的策略,确保我们不会破坏人们,并确保我们不会每周或每个月都创建全新版本的 API。
  • 通过不间断更改、附加更改来增强 API 非常棒。那些类型的东西很棒。但是删除东西,重命名东西,那些会破坏使用该操作的人的东西,那些在响应中使用该特定字段的人。
  • 重构最终会改变你的 Web API,因为你没有将 Web API 契约与你的实现细节分开,所以你无法让它仍然按照设计的方式工作,即使你已经在内部改变了一些东西。如果您开始引入重大变化,那么您将带来客户流失的机会。

 
API 设计优先方法
  • 相对于代码优先的方法,想想我们如何做一个轻量级、快速的 API 设计优先方法,让我们更接近正确的标记,防止我们编写或设计一个不正确或与真正需要的不匹配的 API,并且仍然快速获得反馈,以便我们并不是在自己的角落里完全孤立地做这件事,而且做出这些改变太昂贵或太晚了。
  • 对齐:我们如何确保我们设计的 API 与将要使用 API 的开发人员以及将间接使用该 API 的最终用户对齐?首先要确保我们所有的假设都得到处理,我们不会编写包含错误假设的代码。我们不会设计一个同样具有错误假设的 API。我们了解需求是什么,结果是什么。我们将这些分解到下一个层次,并逐步了解我们需要做什么。然后 API 设计将随之发展。然后我们应用一种或多种 API 样式来设计 API。因此,我们可能会对我们的大部分操作应用 REST 方法。也许提供一个 GraphQL。全部使用定义阶段的输出。一个 API 配置文件,它定义了 API 应该在高层次上做什么。

 
API 边界和 DDD

  • 引入边界,我们可以在其中分割 API 的各个部分。这并不一定意味着您拥有多个 API 产品。这意味着您正在寻找具有凝聚力的不同 API 或不同操作。
  • 花时间评估 API 的边界位置将使您更高效,将范围很大的产品或 API 操作的表面区域分解为更容易消化、更易于管理且更易于分解的更小的边界区域由 API 提供商提供。
  • 我们使用 EventStorming 作为发现我们可以布置特定流程的好方法,从我们的事件开始,然后开始扩展并找到生成这些事件的命令,然后识别聚合,并详细说明事件风暴过程。通常,这些聚合确实很好地暗示了 API 边界在哪里。
  • 我们必须牢记许多 Web API,因为它们通过网络必须比我们的 DDD 代码库更粗粒度,后者往往更细粒度并且可以在进程中运行。因此,当您使用具有 Web API 的分布式架构时,我们不希望有太多的网络流量。我们不想太健谈。所以我们必须开始研究我们如何通过网络进行交互,这是一种不同于我们如何构建独立代码库和流程的架构风格。
  • 看看 DDD,我们真的想首先关注聚合,然后让聚合来帮助驱动 API 操作。