Introduction to Pardon

Focused interaction

Pardon works differently that most HTTP frameworks. With other frameworks, first the user selects a request or template to build a request. Pardon inverts this by selecting a compatible template from the request.

This design focuses the user on the interesting parts of the requests, and the templates can supply all the nitty-gritty (Content-Type, Authorization, except).

Pardon also can reconfigure requests for different environments. For instance, Pardon can understand a request to https://service.example.com is production, and https://service-stage.example.com is stage, and can switch between them. Collection can specify the nominal https://example.com (for legibility), but can be used in any environment.

Focus on HTTP APIs

Requests are written in a format based on HTTP, so they are easier to understand and maintain in any editor (or source-control) than a json-schema or other proprietary format.

Both requests and request templates share the same HTTP language.

Demo time

Let’s explore a more concrete example. Consider an example.com/ping API that

also has a stage environnment, stage.example.com,
requires an explicit Accept header,
and needs an environment-specific apikey.

This ping.https endpoint template describes that call.

config:
  origin:
    env:
      prod: https://example.com
      stage: https://stage.example.com
>>>
GET https://example.com/ping
Accept: text/plain
api-key: {{ apikey = (env === "prod" ? "system" : "staging") }}

This is a configuration section and then an http request template (after the >>>), the template is interpretted by parsing it and then merging it into the following structure:

{
  "method": "GET",
  "origin": "https://example.com",
  "pathname": "/ping",
  "headers": [
    ["accept", "text/plain"],
    ["api-key", "{{ apikey = ... }}"]
  ]
}

{
  method: "{{method}}",
  origin: "{{origin}}",
  pathname: "{{pathname}}",
  searchParams: ...,
  headers: ...,
  body: ...
}

Where the template strings "{{method}}"and "{{origin}}" merge with the values "GET" and "https://example.com", which has the effect of assigning these values to method and origin.

The config map in the configuration section teaches Pardon about the env=stage and env=prod environments, associating the two values of {{origin}} to those environments, and vice-versa. Literal configured values can be overridden or changed in some cases.

Using this template, the input request can be as simple as “https://example.com/ping” or “https://stage.example.com”. When pardon finds only one template compatible with such a request, it will use it to fill in all the other details.

For example the pardon command line utility can, (using only this template), generate (or make) the full requests directly.

Pardon can execute a simple request, like curl, but using templates reduces the noise.

% pardon https://example.com/ping
pong # from prod

Pinging stage is just as easy.

% pardon https://stage.example.com/ping
pong # from stage

pardon can emit the http request (without making the call), just add --http:

% pardon https://stage.example.com/ping --http
GET https://stage.example.com/ping
accept: text/plain
api-key: staging

By adding env=stage we can rewrite the request to use stage!

Here we see the output of pardon’s “--curl” output.

% pardon https://example.com/ping env=stage --curl
curl "https://stage.example.com/ping" \
  --header "accept: text/plain" \
  --header "api-key: staging"

Let’s explore this further, in a playground environment:

Exercises

change the request to the stage server

Change the host here, watch how pardon updates the request. (keep an eye on the api-key header)

https://stage.example.com/ping

add a query to the input request

Pardon integrates additional query parameters to be included with requests, without any changes to the template.

https://example.com/ping?hello=world

add a header to the input request

Pardon also integrates additional headers to be included in requests, without any changes to the templates.

https://example.com/ping?hello=world
User-Agent: pardon

override the request with configuration

Any KV (key-value) data can go above the HTTP request to configure it.

env=stage
https://example.com/ping

Notice how this changes the request.

Loading Pardon Playground...

Next Steps

To get some hands-on experience running pardon now, please try the following quickstart.

Pardon Quickstart Get running with a TODO app.

To learn more of the fundamentals of Pardon’s request matching and rendering system, please explore the template guide.

Pardon Templates A quick introduction to Pardon's templates