Reference
The bundled examples
The Pokédex and PayPal payments examples in detail, what each workflow shows and what you need to run them.
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.
Open an example
Section titled “Open an example”- On the welcome screen, click Try the Pokédex or Try PayPal payments. See the examples lists both.
- 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.
Pokédex
Section titled “Pokédex”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. |
Pokemon card
Section titled “Pokemon card”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/nameThe 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.
Type explorer
Section titled “Type explorer”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.
Battle matchup
Section titled “Battle matchup”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.strongAgainstRegister sighting
Section titled “Register sighting”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: 5000Things to try
Section titled “Things to try”- Open Pokemon card and press Run.
- In Inputs, change
pokemontocharizard,150ormewtwo. - 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”.
- 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.
PayPal payments
Section titled “PayPal payments”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. |
Reusable pieces
Section titled “Reusable pieces”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 == 422parameters: - reference: $components.parameters.requestIdonFailure: - reference: $components.failureActions.invalidRequestIf the buyer did not approve the order, PayPal answers 422 and Capture order ends there, through the notApproved action.
Capture order and the webhook
Section titled “Capture order and the webhook”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: 5000Webhooks are always simulated. Luvin does not receive PayPal events.
Order receipt
Section titled “Order receipt”- workflowId: orderReceipt dependsOn: [createOrder] steps: - stepId: receipt operationId: $sourceDescriptions.paypal.showOrderDetails parameters: - name: id in: path value: $workflows.createOrder.outputs.orderIdAuthorization
Section titled “Authorization”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 or sandbox
Section titled “Simulation or sandbox”| 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:
- Go to developer.paypal.com/dashboard, Apps & Credentials, Sandbox tab, and create an app. It is free.
- In Luvin, open the Environment selector of the run bar and choose Configure environment….
- In the Sandbox environment, paste the Client ID as the variable
clientIdand the Secret as the secretclientSecret. The secret stays encrypted on your computer. - Switch to Real API and run Create order. The order is
CREATED. - To capture it, open the
approveUrlfrom the result with a sandbox buyer account (Testing Tools, Sandbox Accounts) and approve the payment. - Run Capture order, with that
orderIdin Inputs.