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

API 经济的持续增长为我们带来了越来越多的 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 平台可能会通过回调或来自 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，该 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 规范提出反馈意见！