如何有效链接 API 请求

自从有了 API 以来，就一直需要链接 API 请求。API 支持可组合的软件架构，自然会促进系统及其支持的操作的分布。组织或企业的“功能”往往成为对分布式系统的多个 API 调用的集合。

有一种观点认为，如果你正在实施 REST，那么链接 API 请求应该是不必要的，尤其是考虑到超媒体在提供请求之间的上下文方面所起的作用。然而，系统的互联性以及（无论对错）跨平台架构风格的普遍混合使得依靠单一、范围明确的 API 调用来完成某件事变得越来越困难。将来自一个或多个 API 提供商的 API 请求结合在一起对于交付正常运行的软件系统至关重要。

但是，有一点很重要。我们应该考虑到链接 API 请求是一项设计时活动。无数平台允许实施者协调一系列 API 请求，但很少有平台发布使这些平台以编程方式工作所需的信息。当 API 提供商发布操作时，他们应该考虑不同操作之间的关系，并将这些信息提供给 API 消费者。API 提供商显然可以在API 门户和文档中做到这一点。然而，在自动化和 AI 足迹不断增加的世界中，提供机器可读文档是一种用例。

在这篇文章中，我们将介绍 API 提供商提供 API 请求如何链接在一起的描述的几种方式。我们研究了 API 经济早期的标准，以便为问题空间提供一些背景信息。然后，我们讨论了通过 OpenAPI Initiative (OAI) 规范提供设计时链接的两种方法。

集成架构和链接 API 请求

链接请求的目标已经在集成架构中多次得到解决。随着软件和系统架构变得分布式，任务也从单片计算系统转移，越来越需要以合理的方式将活动拼接在一起。解决方案往往遵循当今突出的集成架构。

一个例子是业务流程执行语言(BPEL)，它与Web 服务和面向软件的架构 (SOA)相关。BPEL 被视为一种编排语言，因为它描述的是软件组件控制的一系列活动，而不是（如编排所描述的）软件组件与之交互的一系列事件。

BPEL 的显著特点是它提供了一系列活动的机器可读描述。当我们在 API 规范语言的背景下考虑机器可读描述时，它们在 API 世界中非常重要，API 规范语言是提供有关给定 API 的信息的关键部分。

然而，从 API 经济的角度来看，BPEL 并未为 API 消费者提供有效链接 API 请求的方法。这是因为流程是在服务器端执行的，工作流服务器负责编排活动，并以 Web 服务描述语言 (WSDL) 符号提供文档来描述操作参数。API 消费者无法自己编排活动，这通常不适合他们的用例。

由于这个原因（以及我们在此不讨论的其他一些原因），BPEL 和 SOA 中的其他类似标准尚未转移到 API 经济中。API 提供商需要其他方法来描述和实现 API 请求之间的链接，而不会剥夺 API 消费者的控制权。如何在设计时实现这一点的一个例子是在 OpenAPI 文档中使用链接。

设计时链接：使用 OpenAPI 中的链接

链接（特别是链接对象）是一种在设计 API 并向 API 使用者提供描述文档时将一个请求链接到另一个请求的方法。规范将链接对象描述为一种描述“…响应与其他操作之间已知的关系和遍历机制”的方法。这对 API 使用者很有帮助，因为他们可以了解以编程方式使用的端点之间的关系，从而让理解链接对象的工具来调解 API 调用之间的数据流。规范使用运行时表达式（我们在最近的AsyncAPI文章中提到过）来描述如何从 API 响应中访问信息以进行后续 API 请求。

这是一个非常简单的例子。以下是 OpenAPI 文档的摘录，其中描述了一个假设的外汇 API 的两个操作：获取报价，然后根据报价执行交易。

paths:

  /quotes:

    post:

      summary: Create a new quote for a given currency pair

      operationId: CreateQuote

      requestBody:

        content:

          application/json:

            schema:

              type: object

              required:

                - tradeType

                - sellCurrency

                - buyCurrency

                - amount

              properties:

                tradeType:

                  type: string

                sellCurrency:

                  type: string

                buyCurrency:

                  type: string

                amount:

                  type: number

      responses:

        201:

          description: Created

          content:

            application/json:

              schema:

                type: object

                required:

                  - quoteId

                properties:

                  quoteId:

                    type: string

            # ... other quote properties

          links:

            executeTradeBasedOnQuote:

              operationId: CreateTrade

              requestBody: $.response.body#quoteId

  /trades:

    post:

      summary: Execute a trade based on a previous quote using quoteId

      operationId: CreateTrade

      requestBody:

        content:

          application/json:

            schema:

              type: object

              required:

                - quoteId

              properties:

                quoteId:

                  type: string

标记为的操作CreateQuote向 API 使用者表明，他们可以根据响应使用该操作执行交易CreateTrade。客户端必须从响应中检索的值quoteId并使用它来填充请求正文。

此示例展示了 API 提供商如何使用 OpenAPI 描述请求之间的链接信息，当使用属性实现时operationRef，它可以在不同的OpenAPI 文档之间建立桥梁。提供此信息是一项非常强大的功能，因为它消除了 API 使用者的猜测，他们可以利用工具自动链接请求。

然而，有时描述来自不同提供商的 API 之间的链接是有意义的。这就是 OAI 工作流可以提供帮助的地方。

跨 API 链接：OpenAPI 工作流

正如我们已经说过的，在平台由各个部分组成并集成许多不同系统以提供特定功能的环境中，跨 API 链接是一个共同目标。软件开发人员通常必须弄清楚如何以正确的顺序进行 API 调用，并在调用之间传递正确的上下文。

虽然这对于简单的 API 来说是可以接受的，但更大、更复杂的序列要求更高，并且可能导致对 API 提供商的支持要求复杂。这就是 OAI 工作流特别兴趣小组 (SIG) 试图通过工作流规范填补这一空白的地方。此规范的理念是提供一份人类和机器都能理解的描述文档，使它们能够无缝地将一系列事件编织在一起。

给定的工作流文档旨在以 API 使用者选择的方式实现（与 BPEL 示例不同），使用他们自己选择的计算和软件。这为 API 使用者在实现方面提供了相当大的“优势”，同时又不损害他们对如何协调多个 API 请求的控制权。

以规范中的示例（基于登录Petstore API 的工作流）为例，工作流提供程序首先描述并唯一标识工作流。在此定义中，它们指定工作流的外部输入，在本例中username为和password：

workflows:

- workflowId: loginUserAndRetrievePet

  summary: Login User and then retrieve pets

  description: This workflow lays out the steps to login a user and then retrieve pets

  inputs:

      type: object

      properties:

          username:

              type: string

          password:

              type: string

然后，工作流提供程序概述了工作流中的步骤（在示例中，后面loginStep跟着getPetStep），使用运行时表达式提供对输入值和要在步骤之间重用的值的引用。例如，username使用表达式引用输入$inputs.username：

  steps:

  - stepId: loginStep

    description: This step demonstrates the user login step

    operationId: loginUser

    parameters:

      # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)

      - name: username

        in: query

        value: $inputs.username

      - name: password

        in: query

        value: $inputs.password

    successCriteria:

      # assertions to determine step was successful

      - condition: $statusCode == 200

    outputs:

      # outputs from this step

      tokenExpires: $response.header.X-Expires-After

      rateLimit: $response.header.X-Rate-Limit

      sessionToken: $response.body

  - stepId: getPetStep

    description: retrieve a pet by status from the GET pets endpoint

    operationRef: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml#/paths/~1pet~1findByStatus/get

    dependsOn: loginStep

    parameters:

      - name: status

        in: query

        value: 'available'

      - name: Authorization

        in: header

        value: $steps.loginUser.outputs.sessionToken

    successCriteria:

      - condition: $statusCode == 200

    outputs:

      # outputs from this step

      availablePets: $response.body

  outputs:

      available: $steps.getPetStep.availablePets

这些步骤还提供了成功标准，让工作流消费者了解在他们的代码中需要注意什么、依赖关系以及每个步骤的输出，这些输出稍后可以使用。

当您考虑使用 Workflow文档帮助 API 使用者实现与多个 API 的集成时，Workflow 规范的优势便会立即显现出来。不过，API 市场中的发布者也有可能利用 Workflow 文档，将来自不同提供商的多个独立 API 的 API 调用序列编织在一起。因此，Workflow 用例虽然并不一定是新的，但具有极大的潜力，可以简化 API 使用者的 API 使用，同时仍允许他们控制使用 API 的方式。