Last updated

Understanding workflows and steps

In Arazzo, workflows and steps are your ticket to orchestrating API magic—or in this case, time travel. With the Warp API, we're not just calling endpoints; we're bending time itself. These core concepts let you define what happens, when, and how, turning a collection of time-travel operations into a seamless mission. Let's unpack how workflows and steps work in Arazzo, using the Warp API to jump back to 1889 and snag Tesla's lost blueprint. Buckle up—things are about to get temporal!

What's a workflow?

The workflows section is the mission control of your Arazzo file. It's where you script sequences of API calls to pull off something big—like retrieving a lost invention from the past. Think of it as your time-travel itinerary: a set of instructions that takes you from the present to 1889 and back again.

In Arazzo, workflows is an array, so you can define multiple missions in one file. Each workflow has:

  • workflowId: A unique name for the mission.
  • summary: A quick rundown of what you're trying to achieve.
  • description (optional): Extra details for context.
  • steps: The time-hopping actions that make it happen.

Here's a sneak peek:

workflows:
  - workflowId: "teslaBlueprintMission"
    summary: "Travel to 1889 to retrieve Tesla's blueprint"
    steps:
      # Time travel steps go here

The workflowId is your mission's codename, and summary keeps it clear for anyone (or any time traveler) reading along.

Breaking down steps

Inside a workflow, steps are the individual leaps through time—or API calls—that drive your mission. Each step is a precise instruction, telling Arazzo what to do, how to do it, and what it depends on. A step can include:

  • stepId: A unique label for this action.
  • operationId: Ties to a Warp API operation (e.g., timeTravel).
  • operationPath (alternative): Points to a specific path/method in the OpenAPI file.
  • parameters (optional): Inputs like timeline IDs or tokens.
  • dependsOn (optional): Links to prior steps for data or order.
  • outputs (optional): Data you capture for the next jump.

Steps run in sequence by default, but dependsOn locks in dependencies when timing (or data) matters. Let's see it with the Warp API.

A time-travel example

Imagine we're using the Warp API to retrieve Tesla's lost blueprint from 1889. Our mission: set an anchor, create a timeline, travel back, register the blueprint, and return. Here's how it looks:

arazzo: "1.0.1"
info:
  title: "Tesla Blueprint Retrieval"
  version: "1.0.0"
sourceDescriptions:
  - name: "warpApi"
    url: "https://api.warp.example.com/v1/openapi.yaml"
workflows:
  - workflowId: "teslaBlueprintMission"
    summary: "Travel to 1889 to retrieve Tesla's blueprint"
    steps:
      - stepId: "setHomeAnchor"
        operationId: "setAnchor"
        parameters:
          body:
            timestamp: "2025-02-19T12:00:00Z"
            description: "Home base for return"
        outputs:
          anchorId: "$response.body.id"
      - stepId: "create1889Timeline"
        operationId: "createTimeline"
        parameters:
          body:
            name: "Tesla Mission 1889"
            destination_time: "1889-03-10T23:50:00Z"
        outputs:
          timelineId: "$response.body.id"
      - stepId: "jumpTo1889"
        operationId: "timeTravel"
        dependsOn: "create1889Timeline"
        parameters:
          body:
            destination: "$steps.create1889Timeline.outputs.timelineId"

What's happening?

  1. Workflow: teslaBlueprintMission outlines our time-travel heist.
  2. Step 1: setHomeAnchor
    • Calls setAnchor to mark our present time (Feb 19, 2025).
    • Saves the anchorId from the response ($response.body.id).
  3. Step 2: create1889Timeline
    • Calls createTimeline to set up a jump to 1889.
    • Captures the timelineId for the next step.
  4. Step 3: jumpTo1889
    • Calls timeTravel to leap back, using the timelineId from Step 2.
    • dependsOn ensures the timeline exists before we jump.

The $ runtime expressions are our flux capacitors—they pull data like timelineId dynamically, stitching the steps together across time.

Key concepts in action

Dependencies with dependsOn

In our example, jumpTo1889 relies on create1889Timeline for the timelineId. The dependsOn field makes this explicit—without it, Arazzo assumes steps run in order, but declaring it ensures no time paradoxes sneak in. You can depend on multiple steps if needed:

dependsOn:
  - "setHomeAnchor"
  - "create1889Timeline"

Inputs and outputs

  • Parameters: Can be static (e.g., "2025-02-19T12:00:00Z") or dynamic (e.g., $steps.create1889Timeline.outputs.timelineId). They match the Warp API's expected inputs.
  • Outputs: Name a value (e.g., timelineId) and grab it from the response (e.g., $response.body.id). Later steps use it with $steps.<stepId>.outputs.<outputName>.

Operation references

We're using operationId (e.g., timeTravel) since the Warp API provides unique ones. Alternatively, operationPath could pinpoint a specific endpoint:

operationPath: "warpApi#/paths/~1travels/post"

Tips for success

  • Keep it Linear: Start with a few steps—like anchoring and jumping—to master the flow.
  • Name Clearly: Use stepIds like jumpTo1889, not step1, for readability.
  • Check Outputs: Ensure your API responses match what you expect (e.g., id fields).
  • Test with Tools: Run redocly lint to catch syntax slips before you warp.

Why it matters

With the Warp API, workflows and steps turn time travel from a sci-fi dream into a structured mission. They let you choreograph complex sequences—set anchors, create timelines, jump through history—with precision. Mastering these is your key to bending time (and APIs) to your will.

 
Next page