Skip to content

REST API

Jump to bottom
Mark Feit edited this page Mar 16, 2018 · 8 revisions

NOTE: This page is in the larval stage.

General Information

Endpoints

The endpoints described below are relative to https://<hostname>/pscheduler. It is possible (but not common) to run pScheduler on alternate ports; see Alternate Server Ports for more information.

Common Parameters

All endpoints understand the following parameters as part of the query string:

api - An integer indicating which version of the API is being used, defaulting to 1 if not provided. The API will, to the extent possible, emulate the behavior of older versions where applicable.

pretty - If present, JSON output will be pretty printed for better readability by humans.

I/O Format

Unless otherwise noted, all URLs produce JSON as output. URLs which take PUT or POST take valid JSON as input.

The remainder of this document breaks up the various endpoints by function.

Administrative

/ - Root (Since API 1)

GET

Retrieves a standard message as a string.

GET /pscheduler/ HTTP/1.1

"This is the pScheduler API server on somehost."

/api - Application Programming Interface Version (Since API 1)

GET

Retrieves the higest API version supported by the version of pScheduler on the server as a number.

GET /pscheduler/api HTTP/1.1

2

/clock - System Clock (Since API 1)

GET

Returns information about the state of the system's clock as an object containing the following pairs:

  • time - A string containing the current time as an ISO 8601 timestamp
  • synchronized- A boolean indicating whether or not the clock is synchronized to an external reference.
  • source - A string describing the source of the synchronization. The sole value for this is currently ntp. Not present if synchronized is false.
  • reference - A free-form string describing the external reference. Not present if synchronized is false.
  • offset - A number indicating the number of seconds by which the system believes the time deviates from the source.
GET /pscheduler/clock HTTP/1.1

{
    "offset": 1.9788742065429688e-05,
    "reference": "secondary reference (3) from 107.170.0.6",
    "source": "ntp",
    "synchronized": true,
    "time": "2017-08-04T14:16:13.744876-04:00"
}

/hostname - Server Host Name (Since API 1)

GET

Retrieves the name of the host as the server knows it and returns it as a string.

GET /pscheduler/hostname HTTP/1.1

"pscheduler6.example.org"

/mtu-safe - Check if the MTU to another host is safe (Since API 4)

GET

Determines whether the MTU along the path named by the argument dest is considered safe for use. An unsafe path is one where the MTU falls below the one being used by the server. The determination of the path MTU is made using tracepath(8).

GET /pscheduler/mtu?dest=ps2.example.org HTTP/1.1

{
    "safe": true",
    "message": "1500+"
}

/schedule-horizon - Schedule Horizon (Since API 1)

GET

Retrieves the amount of time in advance that this server is willing to schedule task runs. Returns a string containing an ISO 8601 duration.

GET /pscheduler/schedule-horizon HTTP/1.1

"P1D"

Tests

/tests - Tests Installed (Since API 1)

GET

Returns an array of strings, each containing the URL of a test plugin installed on the system.

GET /tests HTTP/1.1

[
    "https://pscheduler6.example.org/pscheduler/tests/clock",
    "https://pscheduler6.example.org/pscheduler/tests/dns",
    ...
    "https://pscheduler6.example.org/pscheduler/tests/throughput",
    "https://pscheduler6.example.org/pscheduler/tests/trace"
]

If the expanded parameter, is present, each item in the array will be an object containing a fully-expanded description of the test (see /tests/<name>, below).

/tests/<name> - Individual Test (Since API 1)

GET

Retrieves a full description of the test named <name>.

GET /tests/rtt HTTP/1.1

{
    "description": "Measure the round trip time between hosts",
    "href": "https://pscheduler6.example.org/pscheduler/tests/rtt",
    "maintainer": {
        "email": "[email protected]",
        "href": "http://www.perfsonar.net",
        "name": "perfSONAR Development Team"
    },
    "name": "rtt",
    "scheduling-class": "background",
    "schema": 1,
    "version": "1.0"
}

/tests/<name>/spec - Test Specification (Since API 1)

GET

Convert an array of command-line arguments supplied in the args parameter into an object suitable for use as a test specification for test <name>.

GET /tests/rtt/spec?args=%5B%22--dest%22%2C%20%22www.example.com%22%5D HTTP/1.1

{
    "dest": "www.example.com",
    "schema": 1
}

/tests/<name>/spec-is-valid - Validate a Test Specification (Since API 2)

GET

Determines the validity of a test specification for test <name> supplied in the spec parameter.

GET /tests/rtt/spec/is-valid?spec=%7B%20%22dest%22%3A%20%22www.example.com%22%20%7D HTTP/1.1

{
    "valid": true
}

If the specification is not valid, an error containing an error message will be provided.

cpr '/tests/rtt/spec/is-valid?spec=%7B%20%22bad%22%3A%20%22www.example.com%22%20%7D'
{
    "error": "Additional properties are not allowed (u'bad' was unexpected)",
    "valid": false
}

/tests/<name>/tools - Find Tools for a Test (Since API 1)

GET

Retrieve an array of URLs of installed tool plugins capable of running test <name> based on the specification in the spec parameter.

GET /tests/trace/tools?spec=%7B%20%22dest%22%3A%20%22www.example.com%22%20%7D HTTP/1.1

[
    "https://localhost/pscheduler/tools/tracepath",
    "https://localhost/pscheduler/tools/traceroute",
    "https://localhost/pscheduler/tools/paris-traceroute"
]

If the expanded parameter is supplied, the array will contain objects with a full description of each tool:

GET /tests/trace/tools?spec=%7B%20%22dest%22%3A%20%22www.example.com%22%20%7D&expanded HTTP/1.1

[
    ...
    {
        "description": "Map the route between hosts with traceroute",
        "href": "https://localhost/pscheduler/tools/traceroute",
        "maintainer": {
            "email": "[email protected]",
            "href": "http://www.perfsonar.net",
            "name": "perfSONAR Development Team"
        },
        "name": "traceroute",
        "preference": 0,
        "schema": 1,
        "tests": [
            "trace"
        ],
        "version": "1.0"
    },
    ...
]

/tests/<name>/participants - Determine Test Participants (Since API 1)

GET

Retrieves a list of the hosts that would participate in the test specified by the spec parameter. If the first entry is null, the local host is implied and null-reason will provide a string explaining why.

GET /tests/throughput/participants?spec=%7B%20%22dest%22%3A%20%22ps.example.edu%22%20%7D

{
    "participants": [ null, "ps.example.edu" ],
    "null-reason": "No source specified"
}

Tools

@application.route("/tools", methods=['GET'])
@application.route("/tools/<name>", methods=['GET'])

Archivers

@application.route("/archivers", methods=['GET'])
@application.route("/archivers/<name>", methods=['GET'])
@application.route("/archivers/<name>/data-is-valid", methods=['GET']) -- API 2

Contexts

NOTE: This describes an upcoming feature.*

@application.route("/contexts", methods=['GET']) -- API 3
@application.route("/contexts/<name>", methods=['GET']) -- API 3
@application.route("/contexts/<name>/data-is-valid", methods=['GET']) -- API 3

Tasks

@application.route("/tasks", methods=['GET', 'POST'])
   ^^ NOTE:  Fields involving HREFs cannot be searched using the `json` argument.
@application.route("/tasks/<uuid>", methods=['GET', 'POST', 'DELETE'])
@application.route("/tasks/<uuid>/cli", methods=['GET'])
@application.route("/tasks/<task>/runtimes", methods=['GET']) -- After API 4, can ask by priority.

Runs

@application.route("/tasks/<task>/runs", methods=['GET', 'POST'])
@application.route("/tasks/<task>/runs/<run>", methods=['GET', 'PUT', 'DELETE'])
@application.route("/tasks/<task>/runs/<run>/result", methods=['GET'])
Clone this wiki locally