External validators

These validators are external programs taking in a definition and response data as JSON and returning the validation result. They are user created and have no limitations except the in- and output.

Interface definition

Inputs

Validators get the following json object as input in stdin

{
    "response": {
        "statusCode": 200,
        "rawData": {},
        "url": ""
    },
    "endpoint": {
        "version": 1,
        "name": "",
        "baseUrl": "",
        "method": "",
        "payload": {},
        "authorization": "",
        "jwtLogin": {},
        "headers": {},
        "excludedValidators": [],
        "queryParameters": [],
        "format": "",
        "variables": [],
        "testCaseNames": [],
        "okCode": 200,
        "responseSchema": {}

    }
}

The endpoint property contains the definition used in this test case. The validator can assume that the schema matches so the data can be deserialized into a strongly typed type if possible.

Slim validators

If the additional context provided by the endpoint property is not needed the validator can be declared as “slim”.

This leads to the input not containing the endpoint property.

Output

If validation fails the validator should exit with a non-zero exit code and print an optional message to stderr.

If the validator exits with code 0 Apisense assumes the data was valid

Templates

To ease the creation of custom validators there are templates for many languages.

Official templates

The official templates are found in the repositories of the Buonotti GitHub organization. They have the following naming convention

validator-template-<lang>

Where lang is the name of the language the validator is for

Installing templates

Templates are managed with the Apisense CLI.

To update the local index with the templates available in the remote repositories run

apisense templates update

To install an unofficial template you can run the following command

apisense templates add --lang <lang> --url <git_url>

This allows to add a custom Git repository as a source for a validator template for a custom language.

You can also add an unofficial github profile/org to use as repository

apisense templates add-repo --name <name> --url <url>

To create a validator from a template run

apisense templates create --lang <lang> <name>

If you want to upgrade the local templates to the latest commit run

apisense templates upgrade