Skip to content
↑↓ move↵ openesc close

Reference

The bundled examples

The Pokédex and PayPal payments examples in detail, what each workflow shows and what you need to run them.

5 min read

Luvin ships with two examples so you can try everything without your own API. The Pokédex runs against a public API and needs nothing. PayPal payments shows authorization, reusable pieces and webhooks, and runs in simulation or against the PayPal sandbox. Both are real collections: you can change them and run them again.

  1. On the welcome screen, click Try the Pokédex or Try PayPal payments. See the examples lists both.
  2. Luvin opens the example as a collection of a workspace called Examples, saved inside Luvin, with its documentation in the panel on the right.

The Pokédex opens in Real API mode. PayPal opens in Simulation, because it has no credentials yet. The guided tour walks through both.

The Pokédex uses the PokéAPI, a public read-only API. It needs no credentials and allows calls from the browser, so it runs for real from the first minute. The contract pokeapi.openapi.yaml is a trimmed PokéAPI with six operations. The environment is local, with the server of the contract.

Workflow What it demonstrates
Pokemon card Four steps chained by their outputs, JSONPath criteria and an end action on 404.
Type explorer Three steps: a type, its first Pokémon and its species. The input lists the values it accepts.
Battle matchup A workflow that depends on another one (dependsOn).
Register sighting A real HTTP call mixed with AsyncAPI send and receive steps.

It gets a Pokémon, then its species, what its type is weak to and what its ability does. Each step reads what the previous one returned.

- stepId: getPokemon
operationId: $sourceDescriptions.pokeapi.getPokemon
parameters:
- name: idOrName
in: path
value: $inputs.pokemon
successCriteria:
- condition: $statusCode == 200
- context: $response.body
condition: $.abilities[?(@.is_hidden == false)]
type: jsonpath
onFailure:
- name: pokemonNotFound
type: end
criteria:
- condition: $statusCode == 404
outputs:
id: $response.body#/id
mainType: $response.body#/types/0/type/name

The second successCriteria uses JSONPath to check that the Pokémon has a visible ability. If the Pokémon does not exist, onFailure ends the workflow cleanly. The next step takes $steps.getPokemon.outputs.mainType as its path parameter.

The input type only accepts the names of the Pokémon types:

inputs:
type: object
required: [type]
properties:
type:
type: string
enum: [normal, fire, water, grass, electric]
example: fire

(The file lists all eighteen types.) The first step reads the type, and the next two use the first Pokémon it returns.

It does not declare an input. It depends on Type explorer, which runs first, and uses its outputs:

- workflowId: battleMatchup
dependsOn: [typeExplorer]
steps:
- stepId: getRivalType
operationId: $sourceDescriptions.pokeapi.getType
parameters:
- name: idOrName
in: path
value: $workflows.typeExplorer.outputs.strongAgainst

It mixes one real call with two events, simulated from pokedex-events.asyncapi.yaml. The events are fictional and never leave your computer. The step that waits uses a correlationId and a timeout in milliseconds:

- stepId: awaitConfirmation
channelPath: '{$sourceDescriptions.pokedexEvents.url}#/channels/sightingConfirmed'
action: receive
correlationId: $inputs.correlationId
timeout: 5000
  1. Open Pokemon card and press Run.
  2. In Inputs, change pokemon to charizard, 150 or mewtwo.
  3. In Cases, run the generated cases: happy path, missing or invalid inputs and one case per action, such as “the Pokémon does not exist”.
  4. In Design, drag another operation from the contract to the canvas. The YAML writes itself.

The PokéAPI asks for fair use: do not run the cases in a loop.

This example uses a trimmed PayPal Orders API v2 for the sandbox (api-m.sandbox.paypal.com), its webhooks as AsyncAPI, and OAuth 2.0 per API. The sandbox moves no real money.

Workflow What it demonstrates
Create order Reusable parameters (PayPal-Request-Id and Prefer) and reusable failure actions for 400 and 401.
Capture order Checks the order is APPROVED, captures the payment and waits for the PAYMENT.CAPTURE.COMPLETED webhook.
Order receipt dependsOn: [createOrder], using the order id that Create order returned.

The file declares parameters and actions once, in components, and the steps point to them:

components:
parameters:
requestId:
name: PayPal-Request-Id
in: header
value: '{{$randomUUID}}'
failureActions:
notApproved:
name: notApproved
type: end
criteria:
- condition: $statusCode == 422
parameters:
- reference: $components.parameters.requestId
onFailure:
- reference: $components.failureActions.invalidRequest

If the buyer did not approve the order, PayPal answers 422 and Capture order ends there, through the notApproved action.

The last step waits for the event that PayPal sends when the capture is complete:

- stepId: awaitCaptureEvent
channelPath: '{$sourceDescriptions.paypalEvents.url}#/channels/captureCompleted'
action: receive
correlationId: $inputs.orderId
timeout: 5000

Webhooks are always simulated. Luvin does not receive PayPal events.

- workflowId: orderReceipt
dependsOn: [createOrder]
steps:
- stepId: receipt
operationId: $sourceDescriptions.paypal.showOrderDetails
parameters:
- name: id
in: path
value: $workflows.createOrder.outputs.orderId

PayPal wants an OAuth 2.0 token on every call. It is not inside the Arazzo: it is set per API in the Authorization tab of the workflows and saved in flow-auth.yaml:

apis:
paypal:
type: oauth2
grantType: client_credentials
accessTokenUrl: https://api-m.sandbox.paypal.com/v1/oauth2/token
clientId: '{{clientId}}'
clientSecret: '{{clientSecret}}'

Luvin requests the token, refreshes it and sends it with every request. See Authorization of a workflow and OAuth 2.0.

Simulation Sandbox (Real API)
Credentials None. A Client ID and a Secret of a sandbox app.
What answers The examples of the contract, webhook included. The PayPal sandbox. The webhook stays simulated.
Use it for Seeing the three workflows work. Checking real answers.

In simulation, the rejection cases and your own data cases are not run. See Simulation.

To run against the sandbox:

  1. Go to developer.paypal.com/dashboard, Apps & Credentials, Sandbox tab, and create an app. It is free.
  2. In Luvin, open the Environment selector of the run bar and choose Configure environment….
  3. In the Sandbox environment, paste the Client ID as the variable clientId and the Secret as the secret clientSecret. The secret stays encrypted on your computer.
  4. Switch to Real API and run Create order. The order is CREATED.
  5. To capture it, open the approveUrl from the result with a sandbox buyer account (Testing Tools, Sandbox Accounts) and approve the payment.
  6. Run Capture order, with that orderId in Inputs.