先买后付 – 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 调用才能在购买时获得贷款。步骤序列可以概括如下

产品资格检查：客户在结账时选择 BNPL 选项。系统会进行 API 调用，将客户购物篮中的商品与 BNPL 融资选项相关联。然后将 BNPL 选项显示给客户。
客户选择：客户从显示的列表中选择一项优惠。然后进行 API 调用以检索条款和条件。
资格验证：客户选择产品并接受条款和条件后，可能需要进行资格/信用检查，这可能涉及将客户注册到 BNPL 平台上。
启动 BNPL 交易：产品选择和资格检查完成后，BNPL 交易随即开始。结账提供商会向 BNPL 平台发出 API 调用，其中包含订单详细信息和客户信息。
身份验证和授权：然后可能需要客户在 BNPL 提供商处进行身份验证并授权交易。这可能通过重定向到 BNPL 平台来实现。
完成付款计划：交易得到验证且客户完成身份验证后，结账将检索贷款的最终详细信息，包括付款时间表、利率等。
订单确认：然后通过 API 调用发出 BNPL 交易和付款计划接受确认的信号。
更新订单状态：获得融资后，电子商务平台将继续履行订单，并将履行确认发送回 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，如果客户已在 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 规范提出反馈！

Arazzo 的先买后付用例

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