Learn Arazzo by example

Spec

The arazzo version declaration at the top of the file (e.g. arazzo: 1.0.1)

Info

Similar to OpenAPI, Arazzo uses info to describe the API. It also declares which version of Arazzo is used (even though only version 1.0.x is available at the moment).

Source Descriptions

The sourceDescriptions section is used to describe the sources of the API. It is a list of objects, each containing a name and a url (path to the OpenAPI file). It only supports openapi type at the moment (but is expected to support more types such as asyncapi in the future). We can supply an optional x-serverUrl property to specify a specific server URL of the API.

Workflows

The workflows section is used to define the workflows of the API. It is a list of objects, each containing a name and a description. We'll dive deeper into workflows in the next major section.

This specific workflow is based on the "Lost Invention Mission".

Steps

The steps section is used to define the steps of a specific workflow. Each step contains a name, a description, and a request object. The request object contains the API call to be made. We'll dive deeper into steps in the next section. This specific workflow is based on the "Lost Invention Mission".

Workflow: Lost Invention

This workflow is based on the "Lost Invention Mission".

Workflow: Lost Invention - Inputs

The inputs section is used to define the inputs of a specific workflow. It is a json schema object describing each input. This specific API requires a token input. We'll pass the token into the Arazzo workflow runner using an input parameter (or environment variable).

Workflow: Lost Invention - Parameters

The parameters section is used to define the parameters of a specific workflow. It is a list of objects, each containing a name, an in property, and a value property. The value in this case uses the prefixes the "Bearer " to the input parameter token and passes it to the API as part of the Authorization header.

Steps

The steps section is used to define the steps of a specific workflow. The stepId is required and used to uniquely identify the step. It's a good practice to give each step a meaningful description.

Operation ID

The operationId is the operation ID of the API call to be made. Arazzo has some flexibility in how it references the operation either by operationId or an operationPath. In this case, we're using the operationId to reference the setAnchor operation in the api-reference API. Note that the operationId is prefixed with the sourceDescription.name (in this case, api-reference) which allows Arazzo to disambiguate between operations with the same ID or path in different APIs.

Outputs

The outputs section is used to define the outputs of a specific step. Output is only defined for passing data to another step. It does not describe the full API response.

In this case, we're using the anchor_id output to pass the ID of the anchor to the next step. The value is $response.body#/id which means that the value is the id field in the response body.

The format of outputs is a map object where each key is the output name and the value follows a convention described in the Arazzo specification as a runtime expression.

expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source / "$inputs." name / "$outputs." name / "$steps." name / "$workflows." name / "$sourceDescriptions." name / "$components." name / "$components.parameters." parameter-name)
parameter-name = name ; Reuses 'name' rule for parameter names
source = ( header-reference / query-reference / path-reference / body-reference )
header-reference = "header." token
query-reference = "query." name
path-reference = "path." name
body-reference = "body" ["#" json-pointer ]
json-pointer    = *( "/" reference-token )
reference-token = *( unescaped / escaped )
unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
  ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
escaped         = "~" ( "0" / "1" )
; representing '~' and '/', respectively
name = *( CHAR )
token = 1*tchar
tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA

Request Body

The requestBody section is used to define the request body of a specific step. You can supply a payload object to pass data to the API. In this case, we're using the requestBody to pass the timeline_id and proposed_changes to the API. You can "hardcode" the values or use the outputs from previous steps.

Using outputs from previous steps

In this exmaple, we're using the output from the setAnchorToCurrentTime step to pass the anchor_id to the returnToPresent step.

Success Criteria

The successCriteria section is used to define the success criteria of a specific step. It is a list of objects, each containing a condition and a context. The condition is a boolean expression that describes the success criteria. The context is the context of the success criteria.