Journey Explorer guide

Enable your consumers to understand the API workflow sequence to complete an operation by using our Journey Explorer. We drive this solution through Open API workflow specs, use the guide below to create and upload your own.

Our Developer Portal features a Journey Explorer that enables developers, business users, and decision-makers to visualize API workflows in an interactive environment. This functionality is powered by Open API specs and Open API workflow specs. By moving beyond individual API endpoints, users can see how they work together to execute specific workflows.

To learn more about Arazzo, the rendering tool that supports the Journey Explorer, visit the Arazzo documentation.

Getting Started

Enabling the Journey Explorer for your API will include 3 steps:

Ensure your Open API spec is in the portal.
Complete a workflow configuration file by providing information on endpoint order.
Optional: Upload the related images to enable UI exploration.

Below is a step-by-step guide describing how to upload your Open API specs, create your workflow specs and upload UI exploration images.

Upload all required Open API specs to the portal

All APIs required in the workflow journey will need to have an Open API spec uploaded to the portal. E.g. If your journey contains Acquisition and Customer steps, the Acquisition and Customer API specs must be available in the portal. The specs must pass the linter to ensure all the relevant information is present. To upload Open API specs to the portal, see the onboarding guide.

Generate a workflow spec

The final workflow spec, as you see it in the journey explorer, is completely generated by our parsing process. What you will need, however, is to create the basic structure of the workflow in question. Use the following code template to create it:

Key Fields:

Field	Purpose
workflowId	Unique ID for the workflow (used in URLs)
summary	Title for the workflow
description	Description of a workflow
steps.stepId	Unique ID for each step (no spaces)
steps.operationId	Operation ID for the API endpoint. Should use a source name as a prefix to the actual endpoint’s `operationId`
steps.description	Description of the step’s purpose
steps.image	Optional: Image for UI
steps.enumFilter	Optional: Filters for state and substate enum values
steps.contentLink	Widget steps only: Provides a link to the widget content for widget steps
steps.requestSamples	Widget steps only: Provides code snippets for widget steps
steps.outputs	Widget steps only: Describes the expected outputs for widget steps

The rest of the information will be sourced by the OpenAPI that your Journey uses.

To recap, you will need to do the following:

Start with the example workflow spec, which defines a group of workflows.
Populate the workflow group specific info and x-pub-settings.
Define the OpenAPI sources.
Create a workflow in the workflows array with the following in mind:
- summary for the workflow title.
- workflowId for its url.
- description for its description.
For each step define:
- stepId for the step title (please don’t use spaces here).
- operationId using the source name as a prefix to the actual endpoint’s operationId. Steps without an operationId (widget steps) are not parsed for OpenAPI validation. Instead, they are copied as-is into the parsed output to ensure no critical information is lost.
- description for its description.
- Optional: image for defining a step image.
- Optional: enumFilter to filter state and substate enum values.
- For widget steps: contentLink, requestSamples and outputs
Upload the file to internal/external -> workflows -> <file-name>.

Upload UI exploration images

You will need to provide images to drive the UI exploration feature. If you provide no images the ‘User Interface’ section will not render, but you can still run Journeys without these. Follow the steps below to provide the images:

Create a figma demo of your journey.
Create png screeenshots of the UI before each API call.
Upload these to the file internal/external -> workflows -> images.