Buy-now, Pay-later – An Example Use Case for the Arazzo Specification

The continued growth of the API economy presents us with an ever-increasing number of APIs we use in building systems and doing business. With this volume of APIs comes complexity. We find ourselves calling multiple APIs, from the same provider and across multiple API providers, to execute a given business function. This growth in the interdependency of API operations has created a need for sequences of API calls to be described programmatically , which is why our Workflows Special Interest Group created the Arazzo Specification

Arazzo is a description language that can reference multiple APIs, each described with an OpenAPI description or another Arazzo description, that provides API consumers with a rich view of complex, multistep workflows. Arazzo supports describing dynamic values, allowing API providers or API marketplaces to indicate how API operations relate to each other and the output and inputs that can be carried between each step. When supported by appropriate tooling this can significantly accelerate implementation time for API consumers and ensure they can handle sequences of API requests more accurately.

The use case for an Arazzo description can be applied across almost any industry or vertical. Financial services APIs, for example, demonstrate how such orchestration needs have grown across an ecosystem, where examples of APIs that need to be called in sequence are common for operations like account opening and payments. Buy-now, pay-later (BNPL) is one such use case, as this generally requires multiple API calls to secure a loan at the point of purchase. The sequence of steps can be generalized as follows:

1. Product Eligibility Check: Customers select the BNPL option at checkout. An API call is made to correlate the items in the customer’s basket with BNPL finance options. The BNPL options are then displayed to the customer.
2. Customer Selection: The customer chooses an offer from the list displayed. An API call is then made to retrieve terms and conditions.
3. Eligibility Verification: Once the customer has selected the product and accepted the terms and conditions, an eligibility/credit check may be required, which may involve enrolling the customer on the BNPL platform.
4. Initiate BNPL Transaction: With product selection and eligibility complete the BNPL transaction then takes place. An API call is made from the checkout provider to the BNPL platform with the order details and customer information.
5. Authentication & Authorization: The customer may then be required to authenticate themselves at the BNPL provider and authorize the transaction. This may happen through redirection to the BNPL platform.
6. Finalize Payment Plan: Once the transaction is validated and the customer authenticated, the checkout will retrieve the finalized details of the loan including the payment schedule, interest rates, and so on.
7. Order Confirmation: Confirmation of the BNPL transaction and payment plan acceptance is then signaled through an API call.
8. Update Order Status: With financing secured the eCommerce platform will proceed with fulfillment and confirm fulfillment back to the BNPL platform.
9. Payment Updates: Optionally, for subscription-based products, there may be ongoing updates over callbacks or webhooks from the BNPL platform to the eCommerce platform, with events such as missed payments or loan completion.

The sequence diagram below reflects the steps 1 to 8 described above:

This example reflects how composable software services have become and how we can tailor our platforms based on the myriad of available API providers. The steps and sequence diagram show the complexity that typifies such business flows, especially in eCommerce and is exactly the scenario Arazzo looks to address. An Arazzo description is designed to help platform providers describe flows across their APIs and take the guesswork out of stitching them together. This is of significant benefit for API consumers as they get a structured, versioned description of the required steps that they can use to implement their integration. This gives API consumers a reference point they can rely on to ensure their workflow is implemented as expected and working correctly.

To help bring this example to life, we’ve created a BNPL Arazzo description and OpenAPI description in the Arazzo Specification repository.

The BNPL description includes the inputs to the sequence described above, defined as a Workflow Object:

- 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

The Workflow Object defines the parameters required to initiate the flow which, in this case, include the parameters to make the first API call to check product eligibility and a later step to check customer eligibility for the loan. The inputs to this workflow are:

• The customer details, which can be the full details or a URL that indicates an existing customer resource if the customer is already enrolled on the BNPL platform.
• An array of products, used to assess the customer basket qualification for a checkout loan at the BNPL platform.

All other arguments in the sequence are then elicited using response properties from each API call. These are represented by Step Objects that define the sequence, the conditions that indicate a step has been successful and pointers to dynamic values that can be passed between steps.

For example, the first step in our BNPL use case was to check products in the customer’s basket that were eligible for a loan. This is encapsulated in the following Step Object:

- 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

The Step object definition provides:

• The unique identifier for the definition.
• A reference to the operationId value of the associated Operation in the target OpenAPI description.
• A Request Body Object to describe the inputs to the step, which can include external inputs defined in the Workflow object. In this case, we reference the products in the customer’s basket and their customer details.
• The success criteria that define whether the step was successful. This is expressed through one or more conditions evaluated using HTTP return codes and properties of the response body, referenced using JSON Path.
• Directives on what to do if the API call was successful. In this case, if zero qualifying products are returned the workflow ends.
• Outputs from the step that allows dynamic values to be passed to subsequent steps. In our example, these include the filtered product details that can be shown to the customer to indicate which products are eligible for a BNPL loan and whether a customer eligibility check is required.

The Arazzo Specification is therefore geared towards providing a simple, declarative approach to describe a sequence of API calls to provide flexibility for the API provider and ease of use for the API consumer. You can follow our full example using the links above to discover more about how the Arazzo Specification can help you describe complex, multistep sequences of API calls.

If you are interested in learning more about Arazzo please read the specification, visit our discussions or join us on Slack. Feedback on the Arazzo Specification is most welcome!

Guest blog post by Donald Atha, Software Architect, BetterCloud

One of the biggest challenges facing IT teams today is the increase in tedious and repetitive tasks driven by the explosive growth in SaaS applications over the last 10 years. Companies are using more and more SaaS products, which presents challenges when it comes to managing employee onboarding and offboarding, managing licenses and permissions, and resolving help desk tickets. At BetterCloud, we give IT teams the tools to reduce the amount of manual work on their plate with automations and configurable workflows. As the number of SaaS applications grows, our customers rely on our library of SaaS integrations to also grow.

Testing OpenAPI Generators for Rapid Integration

Recently the Innovation Team within BetterCloud, a team tasked with discovering and testing new capabilities that accelerate innovations, took on the challenge of prototyping a solution that would allow us to more rapidly integrate with various SaaS applications and scale that solution to onboard hundreds of API providers. The team agreed early on in order to reach the ambitions of the business, we would need to automate much of the process. The team also agreed that this would be possible because much of adding a new integration is the same and that the OpenAPI Specification would allow us to automate pieces of this by using existing community generators. 

To fully understand the problem, it helps to understand what it means to add an integration at Bettercloud and a bit about our product. BetterCloud’s workflow engine automates processes like employee onboarding by detecting when a new employee is hired and subsequently granting access to the various SaaS applications required for their role. This onboarding scenario is just one of many use cases we support. All these use cases invariably necessitate ingesting and storing data from the 3rd party provider and updating the provider’s state. For instance, in the onboarding use case, the ingestion process fetches employee data, detects a change in status, and triggers the onboarding workflow. This workflow calls the provider’s APIs to create accounts or grant access to shared resources for the employee—functionality we internally refer to as “actions.”

When embarking on adding a new integration, BetterCloud begins by validating that the provider has the necessary APIs to support our use cases. This crucial step sets the stage for efficiently accessing required data and assessing whether the provider’s APIs are compatible with our action use cases. The OpenAPI Specification provides a consolidated view of this information.

Reducing the Amount of Code Written by Using the OpenAPI Specification

Once the API is understood, the next phase is implementing the ingestion logic. This phase involves calling the provider’s APIs to fetch and store all necessary data within BetterCloud’s infrastructure. The team has explored two methods to coordinate this, both leveraging the OpenAPI Specification. The intent with both approaches is to reduce the amount of code that a developer must write when adding a new integration. The first involves code-generating an HTTP client in Java using the OpenAPI Java code generator, while the other approach uses extensions to markup the spec, enabling the configuration of the ingestion logic. This marked-up spec feeds into a general-purpose engine that implements the logic based on the extensions. This covers the ingestion of data from the APIs, but once acquired, it must be stored to serve our applications. 

BetterCloud utilizes a SQL database to store the entities we ingest. To create the schemas, the team employs the OpenAPI MySQL generator, Flyway, and Terraform. These tools facilitate the creation and configuration of a database for the new provider. The team was able to slightly modify the existing mustache templates of the MySQL generator in order to add our internal fields such as customer id. Since both the ingestion data models and the MySQL data schemas derive from the OpenAPI Specification’s entities, automation of this process becomes straightforward as the data models are aligned. With just an OpenAPI definition, we can generate a new database and its schemas at the click of a button in all of our environments!

Conclusion – Better Scaling the OpenAPI Specification, Better Value

We anticipate that this approach will allow us to bootstrap the ingestion portion of adding a new integration. By automating and code-genning common elements, the team can concentrate on the unique aspects of each new integration. Much like how we at BetterCloud automate workflows for IT teams to allow them to scale the impact of their work, the OpenAPI Specification has given us the tools to build our own automations that scale the value we can provide to our customers.