先买后付——Arazzo 规范的用例示例

API 经济的持续增长为我们带来了越来越多的 API，我们将其用于构建系统和开展业务。随着 API 数量的增加，复杂性也随之而来。我们发现自己需要调用来自同一提供商以及多个 API 提供商的多个 API 来执行给定的业务功能。API 操作相互依赖性的增长创造了对以编程方式描述 API 调用序列的需求，这就是为什么我们的工作流程特殊兴趣小组创建了Arazzo 规范

Arazzo 是一种描述语言，可以引用多个 API，每个 API 都用 OpenAPI 描述或另一个 Arazzo 描述来描述，为 API 消费者提供了对复杂多步骤工作流程的丰富视图。Arazzo 支持描述动态值，允许 API 提供商或 API 市场指示 API 操作如何相互关联以及可以在每个步骤之间传递的输出和输入。在适当工具的支持下，这可以显着缩短 API 消费者的实现时间，并确保他们能够更准确地处理 API 请求序列。

Arazzo 描述的用例几乎可以应用于任何行业或垂直领域。例如，金融服务 API 演示了这种编排需求如何在整个生态系统中增长，其中需要按顺序调用的 API 示例在帐户开户和支付等操作中很常见。先买后付 (BNPL) 就是一个这样的用例，因为它通常需要多次 API 调用才能在购买时获得贷款。步骤序列可以概括如下

1. 产品资格检查：客户在结账时选择 BNPL 选项。一个 API 调用被用来将客户购物车中的商品与 BNPL 融资选项进行关联。然后将 BNPL 选项显示给客户。
2. 客户选择：客户从显示的列表中选择一个优惠。然后进行一个 API 调用来检索条款和条件。
3. 资格验证：一旦客户选择了产品并接受了条款和条件，可能需要进行资格/信用检查，这可能涉及将客户注册到 BNPL 平台上。
4. 启动 BNPL 交易：产品选择和资格完成后，BNPL 交易开始。结账提供商使用订单详细信息和客户信息向 BNPL 平台发出 API 调用。
5. 身份验证和授权：然后可能要求客户在 BNPL 提供商处进行身份验证并授权交易。这可能通过重定向到 BNPL 平台来实现。
6. 完成付款计划：交易验证和客户身份验证后，结账将检索贷款的最终详细信息，包括付款时间表、利率等。
7. 订单确认：然后通过 API 调用发出 BNPL 交易和付款计划接受确认信号。
8. 更新订单状态：随着融资的到位，电子商务平台将继续履行并向 BNPL 平台确认履行。
9. 付款更新：可选地，对于基于订阅的产品，BNPL 平台可能会通过回调或 Webhook 向电子商务平台进行持续更新，包括未付款或贷款完成等事件。

下面的序列图反映了上面描述的步骤 1 到 8

这个例子反映了可组合软件服务是如何成为现实的，以及我们如何根据大量可用的 API 提供商来定制我们的平台。步骤和序列图展示了这种业务流程的典型复杂性，尤其是在电子商务领域，这正是 Arazzo 试图解决的问题。Arazzo 描述旨在帮助平台提供商描述他们 API 中的流程，并消除将它们拼接在一起的猜测。这对 API 消费者来说是一个巨大的优势，因为他们获得了所需步骤的结构化、版本化描述，他们可以使用这些描述来实现他们的集成。这为 API 消费者提供了一个参考点，他们可以依靠它来确保他们的工作流程按预期实施并正常工作。

为了帮助将这个例子变为现实，我们在 Arazzo 规范存储库中创建了一个 BNPL Arazzo 描述 和 OpenAPI 描述。

BNPL 描述包括上面描述的序列的输入，定义为 工作流程对象

- workflowId: ApplyForLoanAtCheckout
  summary: Apply for a loan at checkout using a BNPL platform
  description: Describes the steps to secure a loan at checkout from a BNPL platform. It is a multistep process that requires multiple API calls across several API providers to be completed successfully.
  inputs:
    type: object
    required:
      - customer
      - products
    properties:
      customer:
        # Customer properties
      products:
        # Product properties

工作流程对象定义了启动流程所需的参数，在本例中，包括执行第一个 API 调用以检查产品资格以及稍后检查客户贷款资格的参数。此工作流程的输入是

• 客户详细信息，可以是完整详细信息，也可以是指示现有客户资源的 URL（如果客户已在 BNPL 平台上注册）。
• 产品数组，用于评估客户购物车资格以获得 BNPL 平台上的结账贷款。

然后，序列中的所有其他参数都是使用来自每个 API 调用的响应属性来获取的。这些由 步骤对象 表示，步骤对象定义了序列、指示步骤成功的条件以及指向可以在步骤之间传递的动态值的指针。

例如，我们 BNPL 用例中的第一步是检查客户购物车中符合贷款资格的产品。这在下面的步骤对象中封装

- stepId: checkLoanCanBeProvided
  description: |
    Call the BNPL API to filter the basket for products qualifying for checkout loans. Pass in the array of products from the workflow input as the payload for the API call.

    Act on the response payload:

    - If a list of qualifying products is returned then submit customer choices.
    - If the list of qualifying products is empty then end the workflow
  operationId: findEligibleProducts
  requestBody:
    contentType: application/json
    payload: |
      {
        "customer": "{$inputs.customer}",
        "products": "{$inputs.products}"
      }
  successCriteria:
    - condition: $statusCode == 200
  onSuccess:
    - name: existingCustomerNotEligible
      type: end
      criteria:
        - condition: $statusCode == 200
        - condition: $response.body.existingCustomerNotEligible == false
    - name: qualifyingProductsFound
      type: goto
      stepId: getCustomerTermsAndConditions
      criteria:
        - condition: $statusCode == 200
        - context: $response.body
          type: jsonpath
          condition: $[?count(@.products) > 0]
    - name: qualifyingProductsNotFound
      type: end
      criteria:
        - condition: $statusCode == 200
        - context: $response.body
          type: jsonpath
          condition: $[?count(@.products) == 0]
  outputs:
    eligibilityCheckRequired: $response.body.eligibilityCheckRequired
    eligibleProducts: $response.body.products
    totalLoanAmount: $response.body.totalAmount

步骤对象定义提供了

• 定义的唯一标识符。
• 对目标 OpenAPI 描述中关联操作的 operationId 值的引用。
• 请求体对象，用于描述步骤的输入，其中可能包括在工作流程对象中定义的外部输入。在本例中，我们引用了客户购物车中的产品及其客户详细信息。
• 定义步骤是否成功的成功条件。这通过使用 HTTP 返回码和响应体属性（使用 JSON Path 引用）评估的一个或多个条件来表达。
• 关于 API 调用成功时该做什么的指示。在本例中，如果返回零个符合资格的产品，工作流程将结束。
• 步骤的输出，允许将动态值传递给后续步骤。在我们的示例中，这些包括可以显示给客户的已过滤产品详细信息，以指示哪些产品符合 BNPL 贷款资格以及是否需要进行客户资格检查。

因此，Arazzo 规范旨在提供一种简单、声明式的方法来描述 API 调用序列，以提供 API 提供商的灵活性并简化 API 消费者的使用。您可以按照上面的链接使用完整的示例，了解有关 Arazzo 规范如何帮助您描述复杂的、多步骤的 API 调用序列的更多信息。

如果您有兴趣了解更多关于 Arazzo 的信息，请阅读规范，访问我们的讨论或加入我们的Slack。非常欢迎您对 Arazzo 规范的反馈！