Pardon Quickstart

Tip

These docs assume a NodeJS installation and basic experience with git, node, and npm, and README.md files.

The quickstart here is intended to quickly showcase Pardon’s features without going into the details of how it works. The other tutorials are intended to explain more.

The example/todo repo contains a sample server and Pardon collection. You can use this to demo some workflows.

Installation and Building

To get started with Pardon, first build the Pardon application.

building pardon

$ git clone https://github.com/adobe/pardon.git
$ cd pardon
$ npm install
$ npm install --prefix=packages/core
$ npm install --prefix=packages/favor
$ npm run package --prefix=packages/favor # this also rebuilds pardon's core

Building on Windows

When building on windows, instead of using --prefix, please cd to the various subdirectories.

powershell or cmd

$ git clone https://github.com/adobe/pardon.git
$ cd pardon
$ npm install
$ cd packages/core
$ npm install
$ cd ../favor
$ npm install
$ npm run package

The Pardon application is built into ./packages/favor/out/... (path depends on your plaform, osx and windows should both work, have not tested any linux flavors yet.)

Optionally, you can link the built application as a command-line tool as well.

optional

$ cd packages/core
$ npm link .
# undo this with npm uninstall -g pardon

Setup the example-todo service

In another folder clone the example/todo branch.

$ git clone  https://github.com/adobe/pardon.git -b example/todo example-todo
$ cd example-todo
$ npm start # runs a local server

This runs a simple in-memory-store “TODO list” application as a local service. This will give the ability to make basic CRUD operations via pardon and view the current list of tasks (in a browser)

The repository contains a simple server:

• package.json support for npm start to run the server
• Directoryserver/

  • mini-server.js minimal server framework
  • index.js basic TODO app frontend/backend logic

… and a Pardon project / collection for interacting with that server:

• package.json includes "pardon": {} configuration
• Directorycollection/todo/

  • service.yaml configuration for our todo environments
  • ping.https ping the service
  • list.https list the todos
  • update.https update a todo entry
  • get.https get a todo entry
  • create.https create a new todo entry
  • delete.https delete a todo entry
  • todo-helper.ts functions for working with the service
  • toggle.mix.https a mixin for making update “toggle”
• pardon.test.ts testcases for this service

After running npm start, please open a browser to http://localhost:3000 to view the TODO list.

Open the example workspace

It’s time to run the pardon application (find it in ./packages/favor/out/...) and set the context to the example-todo directory (setting the context is in the file menu).

If everything went well, you should have

env=local

in the globals, and

GET https://todo.example.com/ping

in the main input. This request should be shown as GET http://localhost:3000/ping and there should be a button to actually make the request.

If the server is running, you can run this and get pong back.

You should also see the list of endpoints, (with ping highlighted because it matches the current request).

• Directorytodo

  • create
  • delete
  • get
  • list
  • ping
  • update

The other endpoint we can run trivially is list, select that and the request editor will change to

GET https://todo.example.com/todos

and when we run this we should get back something like this

200 OK
connection: close
content-length: 65
content-type: application/json
date: --- now ---

[
  {
    "task": "get setup with pardon",
    "completed": false,
    "id": "T1001"
  }
]

From this we see a pre-populated task with pardon has an id of T1001.

To change this, we can use the update endpoint

todo=T1001
completed=true

PUT https://todo.example.com/todos/{{todo}}

alternatively, we can specify this entirely with values given an endpoint and other data.

method=PUT
endpoint=todo/update
todo=T1001
completed=true

Note

for sanity, pardon defaults method to GET if not specified, which is done for various reasons but most importantly it is intended to prevent accidents.

Remember to keep the http://localhost:3000 page open while you run this to see the todo list update from the API calls.

Try again, but with completed=false to mark the todo action as pending again.

todo=T1001
completed=false

PUT https://todo.example.com/todos/{{todo}}

Automation

Manually changing completed every time we want to toggle something is great, but what if we could automatically compute the completed for each request?

For this next experiment, instead of setting the completed value, try do=toggle (use the “samples” directory to even-more-easily configure the request.)

todo=T1001
do=toggle

PUT http://todo.example.com/todos/{{todo}}

this will automatically produce the opposite value of completed each time this request is rendered.

The details are covered in later tutorials, but what we have here is pardon requests making pardon requests… executing the following script:

todo-helper.ts

import { pardon } from "pardon";

type TodoOptions = { origin: string; todo: string; };

export async function getCompleted({ origin, todo }: TodoOptions) {
  const { inbound } = await pardon({
    origin,
    todo,
  })`GET https://todo.example.com/todos/{{todo}}`();

  return inbound.values.completed;
}

The operative files here are the get.https endpoint, where completed is parsed from the response, and toggle.mix.https for how getCompleted is used in a template.

Making successive calls using this configuration can now toggle the todo’s completed value.

You can see in the application via the history, that the call made was dependent on the GET call first. (Pardon tracks which promises are awaited to build this graph!).

Next Steps

Now that we’ve seen the behavior of pardon, we can explore its inner workings, starting with the template/schema engine.

Pardon Templates A quick introduction to Pardon's templates