Skip to content

REST API Guide

Introduction

The pSeven REST API is a protocol to run existing pSeven workflows. It supports workflow run parameters, data exchange between the REST client and the workflow at run-time, and file download.

User authorization is required to use the API. Authorization grants you a token, which must be added to the Authorization header in every API request (see Authorization).

Since many REST clients can work with the same workflow, they have read- only access to workflows. REST clients cannot change workflow parameters or contents. To run a workflow, you need to deploy a run document first. This document is an instance of the workflow with specific inputs (parameter values) and results. Run documents are isolated from each other, so after deploying a new run you can:

  • Change run parameters (see Run Setup).
  • Control execution (see Run Commands).
  • Exchange messages with blocks at run-time (see Messaging)
  • Get run results (see Run Results).
  • Get files from the run directory (see File Download).

The sections below guide you through a typical run deployment and execution scenario, providing API usage examples for the command-line. These examples require cURL and jq. Note also that the trailing slash / is required in endpoint URLs, as shown in the example requests.

Authorization

To get an authorization token, send a POST request to /pseven/.rest/v1/auth/login/ with username and password as parameters.

Example:

# Authorization.
$ curl \
    --request POST \
    https://pseven.online/pseven/.rest/v1/auth/login/ \
    -H "Content-Type: application/json" \
    --data '{"username": "user@work.org", "password": "pswd"}' \
    | jq .

Output:

{
    "token": "7a592349be99d8affc6739c1ff8fec98030ff14f"
}

Add the received token to subsequent requests. For example, to get a list of user's workflows:

# List workflows.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    https://pseven.online/pseven/.rest/v1/workflows/ \
    | jq .

Run Setup

To set up a run, you will need to identify the workflow you are going to execute, deploy a new run for this workflow, and (optionally) set run parameters.

Workflow Information

To get a list of workflows, send a GET request to /pseven/.rest/v1/workflows/. The response will list all user's workflows with their names and GUIDs.

Example:

# List workflows
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    https://pseven.online/pseven/.rest/v1/workflows/ \
    | jq .

Output:

[
    {
        "id": "130d943e-100e-46e0-b5da-490ac005b70e",
        "name": "MyTestWorkflow",
        "path": "/pSeven/var/storage/home/1/MyTestWorkflow.p7wf",
        "url": "https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/"
    }
    {
        "id": "a5017c37-2a76-421a-8ba4-1f91788f1b60",
        "name": "AnotherTestWorkflow",
        "path": "/pSeven/var/storage/home/1/AnotherTestWorkflow.p7wf",
        "url": "https://pseven.online/pseven/.rest/v1/workflows/a5017c37-2a76-421a-8ba4-1f91788f1b60/"
    }
]

You can get more detailed information for a specific workflow by sending a GET request to /pseven/.rest/v1/workflows/<workflow ID>. A response to this request contains, in particular, a list of all runs for the workflow under <workflow ID>. Another way to get a list of runs is to send a GET request to /pseven/.rest/v1/workflows/<workflow ID>/runs/.

Example:

# Get workflow details and show its runs only.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/ \
    | jq .runs

# List workflow runs.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/ \
    | jq .

Output:

[
    {
        "name": "MyTestWorkflow (#00000001)",
        "path": "/pSeven/var/storage/home/1/MyTestWorkflow.p7wf/@Runs/#00000001.p7run",
        "id": "719572a9-568d-4ef0-a207-6b73ac536524",
        "url": "https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/719572a9-568d-4ef0-a207-6b73ac536524/",
        "state": "FINISHED",
        "workflow": "/pSeven/var/storage/home/1/MyTestWorkflow.p7wf",
        "workflow_url": "https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/"
    },
    {
        "name": "MyTestWorkflow (#00000002)",
        "path": "/pSeven/var/storage/home/1/MyTestWorkflow.p7wf/@Runs/#00000002.p7run",
        "id": "9ce34c08-8ded-42a1-8e1a-f16353060340",
        "url": "https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/9ce34c08-8ded-42a1-8e1a-f16353060340/",
        "state": "CONFIGURATION",
        "workflow": "/pSeven/var/storage/home/1/MyTestWorkflow.p7wf",
        "workflow_url": "https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/"
    }
]

The second run in the example above is in CONFIGURATION state, which means it is already deployed and waiting for launch. This is the only state which allows changing run parameters and starting the run.

Run Deployment

To deploy a new run, send a POST request to /pseven/.rest/v1/workflows/<workflow ID>/runs/. The request body may specify the following parameters:

  • path - optional path to the run directory.
  • name - optional custom run directory name.

If you specify both name and path, then path is treated as the path to the parent directory of the run directory - so the run directory named name is found inside the directory located by path.

The response to this request will contain the run ID and a few other details. Run state will be QUEUED_TO_INITIALIZE, which means it has just entered the deployment queue and is not ready for configuring yet.

Example:

# Deploy a new run.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    --request POST \
    https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/ \
    -H "Content-Type: application/json" \
    --data '{"path": "run_path", "name": "run_name"}' | jq .

Output:

{
    "name": "MyTestWorkflow (#00000003)",
    "path": "/pSeven/var/storage/home/1/MyTestWorkflow.p7wf/@Runs/#00000003.p7run",
    "id": "ea51478a-f1c9-4fce-a879-d1bdd63faadc",
    "url": "https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/ea51478a-f1c9-4fce-a879-d1bdd63faadc/",
    "state": "QUEUED_TO_INITIALIZE",
    "workflow": "/pSeven/var/storage/home/1/MyTestWorkflow.p7wf",
    "workflow_url": "https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/"
}

Before changing run parameters, get run details by sending a GET request to /pseven/.rest/v1/workflows/<workflow ID>/runs/<run ID>/. Verify that run state is CONFIGURATION; otherwise your run setup requests will be rejected.

Example:

# Check run state.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/ea51478a-f1c9-4fce-a879-d1bdd63faadc/ \
    | jq .state

Output:

"CONFIGURATION"

Run Parameters

Change parameters by sending a PATCH request to /pseven/.rest/v1/workflows/<workflow ID>/runs/<run ID>/. The request body should contain run details with new parameter values. The response will contain updated run details.

Parameters are an array in run details (.parameters). Parameter name (.parameters[<index>].name) is a "path" to this parameter in the workflow: for example, 🏠/someInput is mapped to a workflow input, while 🏠/MyBlock/blockInput is a parameter mapped to the blockInput port of the block named MyBlock. Parameter value is found in .parameters[<index>].value.value.

Example:

# Check name and value for each parameter.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/ea51478a-f1c9-4fce-a879-d1bdd63faadc/ \
    | jq "[.parameters[] | {name: .name, value: .value.value}]"

Output:

[
    {
        "name": "🏠/MyFirstParameter",
        "value": "some_value"
    },
    {
        "name": "🏠/SomeBlock/MySecondParameter",
        "value": 42
    }
]

Example:

# Get run details and save them to a file.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/ea51478a-f1c9-4fce-a879-d1bdd63faadc/ \
    --output run_details.json

# (Change parameter values in run_details.json, save changes).

# Send changes and check new parameter values to verify that it worked.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    -H "Content-Type: application/json" \
    --request PATCH \
    https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/ea51478a-f1c9-4fce-a879-d1bdd63faadc/ \
    --data "@run_details.json" \
    | jq "[.parameters[] | {name: .name, value: .value.value}]"

Output:

[
    {
        "name": "🏠/MyFirstParameter",
        "value": "some_value_changed"
    },
    {
        "name": "🏠/SomeBlock/MySecondParameter",
        "value": 43
    }
]

Run Commands

There are 2 endpoints that provide the run start and stop commands.

A POST request to /workflows/<workflow ID>/runs/<run ID>/run/ starts the run. Run state must be CONFIGURATION. Upon receiving this request, run state immediately changes to QUEUED_TO_RUN, which means it is placed in the run queue but is not started yet.

Example:

# Check run state.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/ea51478a-f1c9-4fce-a879-d1bdd63faadc/ \
    | jq .state

# Start the run.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    --request POST \
    https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/ea51478a-f1c9-4fce-a879-d1bdd63faadc/run/ \
    | jq .

Output:

{
    "status": 200,
    "message": "Accepted"
}

When the run starts, its state changes to RUNNING. In this state you can exchange data with blocks in the workflow (see further). When the run completes, its state changes to FINISHED on success, or FAILED on error.

If you need to force stop a run before it finishes, send a POST request to /workflows/<workflow ID>/runs/<run ID>/interrupt/. Run state must be RUNNING, and when the run stops, it changes to INTERRUPTED.

Example:

# Stop a run.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    --request POST \
    https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/ea51478a-f1c9-4fce-a879-d1bdd63faadc/interrupt/ \
    | jq .

Output:

{
    "status": 200,
    "message": "Accepted"
}

Messaging

While a run is in progress, blocks can exchange messages with the REST client using one or more communication channels. A channel works as a pair of message queues:

  • Channel's platform-to-client queue holds messages sent to this channel by blocks that use it. The client can dequeue messages from here to read them.
  • Channel's client-to-platform queue holds messages sent to this channel by the client. Any block can dequeue and read these messages.

Channels are created on the fly when you specify a channel name in an API call. Named channels are optional: for simple tasks, you can omit the channel name parameter to use the default unnamed channel.

Block

In a Python script block, import the api module, then use api.message_push() and api.message_pop().

api.message_push(message, channel=None)

Send a message from the block.

  • Arguments:
    • message (string) - message
    • channel (string) - name of the channel to use
  • Returns: None

Pushes a message to the platform-to-client queue. Channel name is optional, uses the default channel if none specified.

api.message_pop(channel=None, timeout=0)

Receive a message on the block.

  • Arguments:
    • channel (string) - name of the channel to read from
    • timeout (int) - reception timeout in seconds, 0 for none
  • Returns: message (string)
  • Raises:
    • TimeoutError if timeout exceeded

Pops a message from the client-to-platform queue. Channel name is optional: if not specified, reads the default channel.

Note this is a blocking method: the block's script will wait for a return value. By default there is no timeout, so the block waits for a new message indefinitely. Usually this behavior is unwanted - for example, if the client gets disconnected, the client-to-platform queue remains empty, so the block will never finish. However if you set a timeout, this method waits the specified number of seconds at most and raises TimeoutError when the timeout is exceeded. This exception stops the workflow unless you handle it in your way.

Client

Clients use run's message_push/ and message_pop/ endpoints. Both of them accept POST requests with optional channel specification.

To send a message from the client, do a POST request to /pseven/.rest/v1/workflows/<workflow ID>/runs/<run ID>/message_push/. This request pushes a message to the client-to-platform queue. Request body should be a JSON in the following format: {"message": <string>, "channel": <string>}. The "channel" key is optional - if you omit it, the message is sent to the default channel.

Possible responses to the message push (send) request are:

  • Message accepted: 202 Accepted with an empty body.
  • Error: error status code with a body containing error details (see Error Handling).

To get a message on the client, send a POST request to /pseven/.rest/v1/workflows/<workflow ID>/runs/<run ID>/message_pop/. This request pops a message from the platform-to-client queue. The request body may be a JSON specifying which channel to read: {"channel": <string>}. If the body is empty, a message is read from the default channel.

Possible responses to the message pop (receive) request are:

  • Got a message: 200 OK with a body in the {"message": <string>} format.
  • No messages in queue: 204 No Content with an empty body.
  • Error: error status code with a body containing error details (see Error Handling).

Run Results

A workflow author may select certain ports in the workflow as "result ports". Values from these ports are available through the REST API after the workflow finishes. The result ports can be inputs and outputs as well - there is no requirement that results must be output ports. The author may also choose to save workflow results to a file - see File Download for more details.

Run results are available when run state is FINISHED.

Example:

# Check run state.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/ea51478a-f1c9-4fce-a879-d1bdd63faadc/ \
    | jq .state

Output:

"FINISHED"

Once the run reaches FINISHED state, request run details again. They now contain results data in the .results array, which previously was empty. The .results array structure is similar to the .parameters array.

Example:

# Get run details and view values of results.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/ea51478a-f1c9-4fce-a879-d1bdd63faadc/ \
    | jq "[.results[] | {name: .name, value: .value.value}]"

Output:

[
    {
        "name": "🏠/MyResult",
        "value": 99
    },
    {
        "name": "🏠/MyAdditionalResult",
        "value": "no_comments"
    },
    {
        "name": "🏠/MyFirstParameter",
        "value": "some_value_changed"
    },
    {
        "name": "🏠/SomeBlock/MySecondParameter",
        "value": 43
    }
]

Note that a port can be both a parameter and a result port, so for some workflows you may find the input values of parameters in the .results array too. These values are logged from ports in run-time, after the run has started. You can use them for some sanity tests - for example, to check that the run really accepted the parameter values you had set, you can have your REST client save the parameter values it sends, and compare these saved values with parameter values found in results.

File Download

You can download a file located somewhere inside the run directory (specified on start, see Run Deployment) by sending a GET request to /workflows/<id>/runs/<id>/download/ with the file path as the file query parameter. The path is relative to the run directory.

Example:

# Get a file from the run directory root.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    https://pseven.online/pseven/.rest/v1/workflows/130d943e-100e-46e0-b5da-490ac005b70e/runs/ea51478a-f1c9-4fce-a879-d1bdd63faadc/download/?file=results.json \
    --output results.json

Error Handling

The pSeven REST API uses standard HTTP status codes to indicate success or failure of an API call. Successful requests always return 200 OK. Any other status means an error; in this case, the response body contains error details.

Example:

# Unauthorized request.
$ curl \
    -i https://pseven.online/pseven/.rest/v1/workflows/ \
    -w "\n"

Output:

HTTP/1.1 403 Forbidden

{"detail":"Authentication credentials were not provided."}

Example:

# Attempt to get details of a workflow which does not exist.
$ curl \
    -H "Authorization: Token 7a592349be99d8affc6739c1ff8fec98030ff14f" \
    -i https://pseven.online/pseven/.rest/v1/workflows/00000000-0000-0000-0000-000000000000/ \
    -w "\n"

Output:

HTTP/1.1 404 Not Found

{"detail":"Not found."}