APId is a framework that lets you write declarative, end-to-end collections of requests and make sure your API behaves the way you expect.

APId comes in both binary packages and docker image. You can find the docker image here, while the binaries can be found here

Here's how to install the latest binary on UNIX based systems:

# make sure to substitute the URL with the correct platform for you
curl -L https://github.com/getapid/apid/releases/latest/download/apid-darwin-arm64 -o /tmp/apid
chmod +x /tmp/apid
sudo mv /tmp/apid /usr/local/bin/apid

# test if the installation was successful 
apid version

APId tests, or specs, are written in jsonnet. There are a number of built-in useful functions to make it easier to make and validate requests to your API.

// contents of `example.jsonnet`

{
  simple_spec: spec([
    {
      name: "google homepage",
      request: {
        method: "GET",
        url: "https://www.google.com/"
      },
      expect: {
        code: 200
      }
    }
  ])
}

And to run the test

> apid check -s "example.jsonnet"

example::simple_spec
    google homepage
        + status code is 200

specs passed: 1
specs failed: 0

Success! You've just written your first APId test! If you change the expect.code from 200 to lets say 500 the test will fail and this will be the output:

> apid check -s "example.jsonnet"

example::simple_spec
    google homepage
        o status code: wanted 500, got 200  

specs passed: 0
specs failed: 1

For more examples please check the examples folder in this repository.

You can find the most up to date documentation here

Jsonnet is a very powerful language which can be utilised to make your life easier.

For example you can extract any variables in a separate file

// vars.libsonnet
{
  url: 'http://localhost:8080',
}

// test.jsonnet
{
    name: 'request',
    request: {
        url: vars.url,
    },
    expect: {
        code: 200,
    },
},

You can extract your matchers in a local variable to make the test easier to read

// test.jsonnet
local key_matcher = key(
    or([
        regex("\\w+"),
        regex("\\d+"),
    ])
);

{
    body: {
        [key_matcher]: "the value of that key" // note the [] around the key, ref: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#computed_property_names
    }
}

If you have any questions or ideas please feel free to head over to the discussion tab in this repository and ask away!

1. Head to the latest release and select the binary for your operating system.
2. Once downloaded open the archive and place the executable in a directory on your $PATH.

To contribute to APId, please see CONTRIBUTING.