Rester

Rester is a command line tool to test HTTP APIs. It processes declaratively written request descriptions as a test script, executing and validating the requests as specified.

For instance, a description like the following:

# basic.yml
requests:
  basic:
    url: https://httpbin.org/anything
    validation:
      status: 200

is processed as follows:

Rester currently supports:

• Request methods: GET, POST, PUT, DELETE
• Variable substitution
• Post data with respective encoding
  • JSON
  • query parameters
  • forms
  • multipart
• Sending headers
• Using response values as substitution variables
• Batch file processing
• Uploading and downloading of files
• Delay between requests

See Upcoming Features for a list of what is planned for future releases.

Example request sequence

An example is worth a thousand words - this is how you can use rester to instrument API calls:

# github.yml
variables:
  BASE_URL: https://api.github.com/repos/finestructure/Rester
requests:
  releases:
    url: ${BASE_URL}/releases
    validation:
      status: 200
      json:
        # validate the first id in the list (latest release)
        # this also captures it as a variable
        0:
          id: .regex(\d+)
    log:
      # log the id to the console
      - json[0].id
  latest_release:
    # use the release id to request release details
    url: ${BASE_URL}/releases/${releases[0].id}
    validation:
      status: 200
    log:
      # log the latest release tag to the console
      - json.tag_name

Result:

More examples

The examples directory demonstrates further uses of rester. You can also find the output these examples generate in the test snapshot directory.

A few noteworthy examples for common tasks are

• github.yml: Use the Github API to fetch and print the latest release version of rester. Demonstrates the use of response variables and how to index into response arrays and objects as well as how to log responses.
• multipart.yml: Performs a multipart upload of an image.

Running rester

The easiest way to run rester is via docker:

docker run --rm -t -v $PWD:/host -w /host finestructure/rester examples/github.yml

It's probably easiest to define an alias:

alias rester="docker run --rm -t -v $PWD:/host -w /host finestructure/rester"
rester examples/basic.yml

A word regarding the docker parameters:

• --rm cleans up the container after running
• -t attaches a tty (this helps with flushing and unicode representation)
• -v $PWD:/host maps your current directory onto /host inside the container
• -w /host sets that /host directory as the working directory inside the container. This way you can simply reference files relative to your working directory and they will be found at the same path inside the container.

Note that if you want to test APIs that are running on localhost, you will also want to add

• --network host

to your docker run command. This lets the container run on the host network and allows it to see the host as localhost.

Installing rester

rester requires Swift 5. You can build and install it from source via the Swift Package Manager:

git clone https://github.com/finestructure/rester
cd rester
swift build -c release

On macOS, the easiest way to install and update rester is probably Mint:

brew install mint
mint install finestructure/rester