Interfaces

HTTP endpoints

The main way to communicate with Steep (i.e. to submit workflows, to monitor progress, fetch metadata, etc.) is through its HTTP interface. By default, Steep listens to incoming connections on port 8080.

GET information

Get information about Steep. This includes:

  • Steep’s version number
  • A build ID
  • A SHA of the Git commit for which the build was created
  • A timestamp of the moment when the build was created
Resource URL
/
Parameters
None
Status codes
200The operation was successful
Example request
GET / HTTP/1.1
Example response
HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Length: 130
Content-Type: application/json
 
{
    "version": "6.7.0",
    "build": "2024",
    "commit": "2c83c13ff96d776c298e0c8f69b6f40d7e729ed2",
    "timestamp": 1697633365619
}

GET health

An endpoint that can be used by external applications at regular intervals to monitor Steep’s health, i.e. to check if it works correctly and if the underlying database as well as all remote agents are reachable.

The response is a JSON object, which will always contain the attribute health. This attribute can be either true if Steep works correctly or false if some error has occurred. Apart from that, the response may contain additional information about data stored in the database (such as the number of submissions) as well as information about remote agents. However, these attributes are not defined and may change in future versions.

Resource URL
/health
Parameters
None
Status codes
200The operation was successful
503Service unavailable. Steep may not work as expected.
Example request
GET /health HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 105
content-type: application/json
 
{
    "agents": {
        "count": 4,
        "health": true
    },
    "health": true,
    "services": {
        "count": 14,
        "health": true
    },
    "submissions": {
        "count": 1960,
        "health": true
    },
    "vms": {
        "count": 4173,
        "health": true
    }
}

GET submissions

Get information about all submissions in the database. The response is a JSON array consisting of submission objects without the properties workflow, results, and errorMessage. In order to get the complete details of a submission, use the GET submission by ID endpoint.

The submissions are returned in the order in which they were added to the database with the newest ones at the top.

Resource URL
/workflows
Parameters
size
(optional)		The maximum number of submissions to return. The default value is 10.
offset
(optional)		The offset of the first submission to return. The default value is 0.
status
(optional)		If this parameter is defined, Steep will only return submissions with the given status. Otherwise, it will return all submissions from the database. See the list of submission statuses for valid values.
Response headers
x-page-sizeThe size of the current page (i.e. the maximum number of submission objects returned). See size request parameter.
x-page-offsetThe offset of the first submission returned. See offset request parameter
x-page-totalThe total number of submissions in the database matching the given request parameters.
Status codes
200The operation was successful
400One of the parameters was invalid. See response body for error message.
Example request
GET /workflows HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 662
content-type: application/json
x-page-offset: 0
x-page-size: 10
x-page-total: 2
 
[
  {
    "id": "akpm6yojjigral4cdxgq",
    "startTime": "2020-05-18T08:44:01.045710Z",
    "endTime": "2020-05-18T08:44:21.218425Z",
    "status": "SUCCESS",
    "requiredCapabilities": [],
    "runningProcessChains": 0,
    "pausedProcessChains": 0,
    "cancelledProcessChains": 0,
    "succeededProcessChains": 10,
    "failedProcessChains": 0,
    "totalProcessChains": 10
  },
  {
    "id": "akttc5kv575splk3ameq",
    "startTime": "2020-05-24T17:20:37.343072Z",
    "status": "RUNNING",
    "requiredCapabilities": [],
    "runningProcessChains": 1,
    "pausedProcessChains": 0,
    "cancelledProcessChains": 0,
    "succeededProcessChains": 391,
    "failedProcessChains": 0,
    "totalProcessChains": 1000
  }
]

GET submission by ID

Get details about a single submission from the database.

Resource URL
/workflows/:id
Parameters
idThe ID of the submission to return
Status codes
200The operation was successful
404The submssion was not found
Example request
GET /workflows/akpm6yojjigral4cdxgq HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 348
content-type: application/json
 
{
  "id": "akpm6yojjigral4cdxgq",
  "startTime": "2020-05-18T08:44:01.045710Z",
  "endTime": "2020-05-18T08:44:21.218425Z",
  "status": "SUCCESS",
  "requiredCapabilities": [],
  "runningProcessChains": 0,
  "pausedProcessChains": 0,
  "cancelledProcessChains": 0,
  "succeededProcessChains": 10,
  "failedProcessChains": 0,
  "totalProcessChains": 10,
  "workflow": {
    "api": "4.7.0",
    "vars": [
      …
    ],
    "actions": [
      …
    ]
  }
}

PUT submission

Update a submission. The request body is a JSON object with the submission properties to update. At the moment, only the status and priority properties can be updated.

If the operation was successful, the response body contains the updated submission without the properties workflow, results, and errorMessage.

Notes:

  • You can use this endpoint to cancel the execution of a submission (see example below).
  • If you update a submission’s priority, the priorities of all process chains that belong to this submission and have a status of either REGISTERED, RUNNING, or PAUSED will be updated too. Also, all process chains generated from this submission in the future will receive the updated priority. Finished process chains will not be modified.
Resource URL
/workflows/:id
Parameters
idThe ID of the submission to update
Status codes
200The operation was successful
400The request body was invalid
404The submission was not found
Example request
PUT /workflows/akujvtkv575splk3saqa HTTP/1.1
Content-Length: 28
Content-Type: application/json
 
{
  "status": "CANCELLED"
}
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 195
content-type: application/json
 
{
  "id": "akujvtkv575splk3saqa",
  "startTime": "2020-05-25T19:02:21.610396Z",
  "endTime": "2020-05-25T19:02:33.414032Z",
  "status": "CANCELLED",
  "requiredCapabilities": [],
  "runningProcessChains": 0,
  "pausedProcessChains": 0,
  "cancelledProcessChains": 314,
  "succeededProcessChains": 686,
  "failedProcessChains": 0,
  "totalProcessChains": 1000
}

POST workflow

Create a new submission. The request body contains the workflow to execute.

If the operation was successful, the response body contains submission.

Resource URL
/workflows
Status codes
202The workflow has been accepted (i.e. stored in the database) and is scheduled for execution.
400The posted workflow was invalid. See response body for more information.
Example request
POST /workflows HTTP/1.1
Content-Length: 231
Content-Type: application/json
 
{
  "api": "4.7.0",
  "vars": [{
    "id": "sleep_seconds",
    "value": 3
  }],
  "actions": [{
    "type": "execute",
    "service": "sleep",
    "inputs": [{
      "id": "seconds",
      "var": "sleep_seconds"
    }]
  }]
}
Example response
HTTP/1.1 202 Accepted
content-encoding: gzip
content-length: 374
content-type: application/json
 
{
  "id": "akukkcsv575splk3v2ma",
  "status": "ACCEPTED",
  "workflow": {
    "api": "4.7.0",
    "vars": [{
      "id": "sleep_seconds",
      "value": 3
    }],
    "actions": [{
      "type": "execute",
      "service": "sleep",
      "inputs": [],
      "outputs": [],
      "inputs": [{
        "id": "seconds",
        "var": "sleep_seconds"
      }]
    }]
  }
}

GET process chains

Get information about all process chains in the database. The response is a JSON array consisting of process chain objects without the properties executables, results, totalRuns, runNumber, and autoResumeAfter. In order to get the complete details of a process chain, use the GET process chain by ID endpoint.

The process chains are returned in the order in which they were added to the database with the newest ones at the top.

Some properties such as startTime, status, or endTime depend on a specific process chain run (see the section on process chains for more information about runs). This endpoint always displays the latest run (if available). You can get more information through the endpoints /processchains/:id/runs and /processchains/:id/runs/:runNumber.

Resource URL
/processchains
Parameters
size
(optional)		The maximum number of process chains to return. The default value is 10.
offset
(optional)		The offset of the first process chain to return. The default value is 0.
submissionId
(optional)		If this parameter is defined, Steep will only return process chains from the submission with the given ID. Otherwise, it will return process chains from all submissions. If there is no submission with the given ID, the result will be an empty array.
status
(optional)		If this parameter is defined, Steep will only return process chains with the given status. Otherwise, it will return all process chains from the database. See the list of process chain statuses for valid values.
Response headers
x-page-sizeThe size of the current page (i.e. the maximum number of process chain objects returned). See size request parameter.
x-page-offsetThe offset of the first process chain returned. See offset request parameter
x-page-totalThe total number of process chains in the database matching the given request parameters.
Status codes
200The operation was successful
400One of the parameters was invalid. See response body for error message.
Example request
GET /processchains HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 262
content-type: application/json
x-page-offset: 0
x-page-size: 10
x-page-total: 7026
 
[
  {
    "id": "akukkcsv575splk3v2na",
    "submissionId": "akukkcsv575splk3v2ma",
    "startTime": "2020-05-25T19:46:02.532829Z",
    "endTime": "2020-05-25T19:46:05.546807Z",
    "status": "SUCCESS",
    "requiredCapabilities": []
  },
  {
    "id": "akujvtkv575splk3tppq",
    "submissionId": "akujvtkv575splk3saqa",
    "status": "CANCELLED",
    "requiredCapabilities": []
  },
  …
]

GET process chain by ID

Get details about a single process chain from the database.

Some properties such as startTime, status, or endTime depend on a specific process chain run (see the section on process chains for more information about runs). This endpoint always displays the latest run (if available). You can get more information through the endpoints /processchains/:id/runs and /processchains/:id/runs/:runNumber.

Resource URL
/processchains/:id
Parameters
idThe ID of the process chain to return
Status codes
200The operation was successful
404The process chain was not found
Example request
GET /processchains/akukkcsv575splk3v2na HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 603
content-type: application/json
 
{
  "id": "akukkcsv575splk3v2na",
  "submissionId": "akukkcsv575splk3v2ma",
  "startTime": "2020-05-25T19:46:02.532829Z",
  "endTime": "2020-05-25T19:46:05.546807Z",
  "status": "SUCCESS",
  "agentId": "bakwqka7gk2vrjnxdo5a",
  "requiredCapabilities": [],
  "results": {},
  "totalRuns": 1,
  "runNumber": 1,
  "executables": [{
    "id": "ayj5kboaxngbglzlxiba",
    "path": "sleep",
    "serviceId": "sleep",
    "runtime": "other",
    "runtimeArgs": [],
    "arguments": [{
      "id": "seconds",
      "type": "input",
      "dataType": "integer",
      "variable": {
        "id": "sleep_seconds",
        "value": "3"
      }
    }]
  }]
}

GET process chain logs

Get contents of the log file of a process chain.

This endpoint will only return something if process chain logging is enabled in the log configuration. Otherwise, the endpoint will always return HTTP status code 404.

Also note that process chain logs are stored on the machine where the Steep agent that has executed the process chain is running. The log files will only be available as long as the machine exists and the agent is still available. If you want to persist log files, define a location on a shared file system in the log configuration.

This endpoint supports HTTP range requests, which allows you to only fetch a portion of a process chain’s log file.

Resource URL
/logs/processchains/:id
Parameters
idThe ID of the process chain whose log file to return
forceDownload
(optional)		true if the Content-Disposition header should be set in the response. This is useful if you link to a log file from a web page and want the browser to download the file instead of displaying its contents. The default value is false.
runNumber
(optional)		Specifies the actual run of the process chain whose log file to return (see the section on process chains for details on runs). If no run number is given, the endpoint will return the log file of the latest run. Note that a process chain that currently has the status PAUSED or REGISTERED, does not have a latest run. In this case, the endpoint will return HTTP status code 404.
Request headers
Range
(optional)		The part of the log file that should be returned (see HTTP Range header)
Response headers
Accept-RangesA marker to advertise support of range requests (see HTTP Accept-Ranges header)
Content-Range
(optional)		Indicates what part of the log file is delivered (see HTTP Content-Range header)
Status codes
200The operation was successful
206Partial content will be delivered in response to a range request
400The given run number is invalid (either not a number or less than 1)
404a) Process chain log file could not be found. Possible reasons: (1) the process chain has not produced any output (yet), (2) the agent that has executed the process chain is not available anymore, (3) process chain logging is disabled in Steep’s configuration, (4) the process chain has the status PAUSED or REGISTERED, (5) the given run number was out of range
416Range not satisfiable
Example request
GET /logs/processchains/akukkcsv575splk3v2na HTTP/1.1
Example response
HTTP/1.1 200 OK
content-type: text/plain
accept-ranges: bytes
content-encoding: gzip
transfer-encoding: chunked
 
2021-03-04 15:34:17 - Hello world!

GET process chain runs

Return an array of all runs of a process chain.

A run is represented by an object containing a subset of the properties of a process chain, namely agentId, startTime, endTime, status, errorMessage, and autoResumeAfter. See the section on process chains for more information about runs and these properties.

Runs are ordered by their run number from 1 to n where n is the total number of runs (see process chain property totalRuns).

Resource URL
/processchains/:id/runs
Parameters
idThe ID of the process chain whose runs should be returned
Status codes
200The operation was successful
404The process chain was not found
Example request
GET /processchains/a6wgb7gwpbzr2p6rdlma/runs HTTP/1.1
Example response
HTTP/1.1 200 OK
vary: origin
content-type: application/json
content-encoding: gzip
content-length: 474
 
[
  {
    "agentId": "bakwqka7gk2vrjnxdo5a",
    "startTime": "2023-01-24T13:26:04.294068Z",
    "endTime": "2023-01-24T13:26:14.724449Z",
    "status": "ERROR",
    "errorMessage": "Failed to run. Exit code: 1",
    "autoResumeAfter": "2023-01-24T13:26:59.724445Z"
  },
  {
    "agentId": "bakwqka7gk2vrjnxdo5a",
    "startTime": "2023-01-24T13:27:16.079864Z",
    "endTime": "2023-01-24T13:27:26.200881Z",
    "status": "ERROR",
    "errorMessage": "Failed to run. Exit code: 1",
    "autoResumeAfter": "2023-01-24T13:28:11.200878Z"
  },
  {
    "agentId": "bakwqvi7gk2vrjnxdo7q",
    "startTime": "2023-01-24T13:28:16.101778Z",
    "endTime": "2023-01-24T13:28:26.280940Z",
    "status": "SUCCESS"
  }
]

GET process chain run by run number

Fetches information about a run of a process chain.

The path parameter runNumber specifies the number of the run to return. Run numbers start at 1 in continuously increasing order. The process chain property totalRuns specifies how many runs the process chain has.

This endpoint renders a view of a process chain for the run with the given runNumber. It renders objects similar to the ones returned by the /processchains/:id endpoint. If runNumber equals totalRuns, both endpoints return the exact same object (because /processchains/:id always renders the latest run).

Resource URL
/processchains/:id/runs/:runNumber
Parameters
idThe ID of the process chain whose runs should be returned
runNumberThe number of the run to render
Status codes
200The operation was successful
400The run number was invalid (i.e. not a number)
404Either the process chain or the run were not found
Example request
GET /processchains/a6wgb7gwpbzr2p6rdlma/runs/1 HTTP/1.1
Example response

See /processchains/:id endpoint.

HEAD process chain logs

This endpoint can be used to check if a process chain log file exists and how large it is. For more information, please refer to the GET process chain logs endpoint.

Resource URL
/logs/processchains/:id
Parameters
idThe ID of the process chain whose log file to check
Response headers
Content-LengthThe total size of the log file
Accept-RangesA marker to advertise support of range requests (see HTTP Accept-Ranges header)
Status codes
200The operation was successful
404Process chain log file could not be found. Possible reasons: (1) the process chain has not produced any output (yet), (2) the agent that has executed the process chain is not available anymore, (3) process chain logging is disabled in Steep’s configuration
Example request
HEAD /logs/processchains/akukkcsv575splk3v2na HTTP/1.1
Example response
HTTP/1.1 200 OK
content-type: text/plain
content-length: 1291
accept-ranges: bytes

PUT process chain

Update a process chain. The request body is a JSON object with the process chain properties to update. At the moment, only the status and priority properties can be updated.

If the operation was successful, the response body contains the updated process chain without the properties executables and results.

Notes:

  • You can use this endpoint to cancel the execution of a process chain (see example below).
  • The priority can only be modified if the process chain status is REGISTERED, RUNNING, or PAUSED. Otherwise, the operation will result in HTTP error 422.
Resource URL
/processchains/:id
Parameters
idThe ID of the process chain to update
Status codes
200The operation was successful
400The request body was invalid
404The process chain was not found
422The process chain’s priority could not be modified because the process chain is already finished, i.e. the process chain status is not REGISTERED, RUNNING, or PAUSED
Example request
PUT /processchains/akuxzp4rojbw7mnvovcq HTTP/1.1
Content-Length: 28
Content-Type: application/json
 
{
  "status": "CANCELLED"
}
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 222
content-type: application/json
 
{
  "id": "akuxzp4rojbw7mnvovcq",
  "submissionId": "akuxzp4rojbw7mnvovbq",
  "startTime": "2020-05-26T11:06:24.055225Z",
  "endTime": "2020-05-26T11:06:52.367194Z",
  "status": "CANCELLED",
  "requiredCapabilities": []
}

GET agents

Get information about all agents currently connected to the cluster. In order to get details about a single agent, use the GET agent by ID endpoint.

Resource URL
/agents
Parameters
None
Status codes
200The operation was successful
Example request
GET /agents HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 195
content-type: application/json
 
[
  {
    "id": "akuxryerojbw7mnvovaa",
    "available": false,
    "capabilities": [],
    "startTime": "2020-05-26T10:50:02.001998Z",
    "stateChangedTime": "2020-05-26T11:06:52.367121Z"
  },
  {
    "id": "akvn7r3szw5wiztrnotq",
    "available": true,
    "capabilities": [],
    "startTime": "2020-05-27T12:21:24.548640Z",
    "stateChangedTime": "2020-05-27T12:21:24.548640Z"
  }
]

GET agent by ID

Get details about a single agent.

Resource URL
/agents/:id
Parameters
idThe ID of the agent to return
Status codes
200The operation was successful
404The agent was not found
Example request
GET /processchains/akuxryerojbw7mnvovaa HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 177
content-type: application/json
 
{
  "id": "akuxryerojbw7mnvovaa",
  "available": false,
  "capabilities": [],
  "startTime": "2020-05-26T10:50:02.001998Z",
  "stateChangedTime": "2020-05-26T11:06:52.367121Z"
}

GET VMs

Get information about all VMs in the database. To get details about a single VM, use the GET VM by ID endpoint.

The VMs are returned in the order in which they were added to the database with the newest ones at the top.

Resource URL
/vms
Parameters
size
(optional)		The maximum number of VMs to return. The default value is 10.
offset
(optional)		The offset of the first VM to return. The default value is 0.
status
(optional)		If this parameter is defined, Steep will only return VMs with the given status. Otherwise, it will return all VMs from the database. See the list of VM statuses for valid values.
Response headers
x-page-sizeThe size of the current page (i.e. the maximum number of VM objects returned). See size request parameter.
x-page-offsetThe offset of the first VM returned. See offset request parameter
x-page-totalThe total number of VMs in the database matching the given request parameters.
Status codes
200The operation was successful
400One of the parameters was invalid. See response body for error message.
Example request
GET /vms HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 2402
content-type: application/json
x-page-offset: 0
x-page-size: 10
x-page-total: 614
 
[
  {
    "id": "akvn5rmvrozqzj5k3n7a",
    "externalId": "cc6bb115-5852-4646-87c0-d61a9e275722",
    "ipAddress": "10.90.5.10",
    "creationTime": "2020-05-27T12:17:01.861596Z",
    "agentJoinTime": "2020-05-27T12:18:27.957192Z",
    "status": "LEFT",
    "setup": {
      "id": "default",
      "flavor": "7d217779-4d7b-4689-8a40-c12a377b946d",
      "imageName": "Ubuntu 18.04",
      "availabilityZone": "nova",
      "blockDeviceSizeGb": 50,
      "minVMs": 0,
      "maxVMs": 4,
      "provisioningScripts": [
        "conf/setups/default/01_docker.sh",
        "conf/setups/default/02_steep.sh"
      ],
      "providedCapabilities": ["docker"]
    }
  },
  {
    "id": "akvnmkuvrozqzj5k3mza",
    "externalId": "f9ecfb9c-d0a1-45c9-87fc-3595bebc85c6",
    "ipAddress": "10.90.5.24",
    "creationTime": "2020-05-27T11:40:19.142991Z",
    "agentJoinTime": "2020-05-27T11:41:42.349354Z",
    "destructionTime": "2020-05-27T11:50:58.961455Z",
    "status": "DESTROYED",
    "reason": "Agent has left the cluster",
    "setup": {
      "id": "default",
      "flavor": "7d217779-4d7b-4689-8a40-c12a377b946d",
      "imageName": "Ubuntu 18.04",
      "availabilityZone": "nova",
      "blockDeviceSizeGb": 50,
      "minVMs": 0,
      "maxVMs": 4,
      "provisioningScripts": [
        "conf/setups/default/01_docker.sh",
        "conf/setups/default/02_steep.sh"
      ],
      "providedCapabilities": ["docker"]
    }
  },
  …
]

GET VM by ID

Get details about a single VM from the database.

Resource URL
/vms/:id
Parameters
idThe ID of the VM to return
Status codes
200The operation was successful
404The VM was not found
Example request
GET /vms/akvn5rmvrozqzj5k3n7a HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 617
content-type: application/json
 
{
  "id": "akvn5rmvrozqzj5k3n7a",
  "externalId": "cc6bb115-5852-4646-87c0-d61a9e275722",
  "ipAddress": "10.90.5.10",
  "creationTime": "2020-05-27T12:17:01.861596Z",
  "agentJoinTime": "2020-05-27T12:18:27.957192Z",
  "status": "LEFT",
  "setup": {
    "id": "default",
    "flavor": "7d217779-4d7b-4689-8a40-c12a377b946d",
    "imageName": "Ubuntu 18.04",
    "availabilityZone": "nova",
    "blockDeviceSizeGb": 50,
    "minVMs": 0,
    "maxVMs": 4,
    "provisioningScripts": [
      "conf/setups/default/01_docker.sh",
      "conf/setups/default/02_steep.sh"
    ],
    "providedCapabilities": ["docker"]
  }
}

GET plugins

Get information about all configured plugins. To get information about a single plugin, use the GET plugin by name endpoint.

Resource URL
/plugins
Parameters
None
Status codes
200The operation was successful
Example request
GET /plugins HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 159
content-type: application/json
 
[
    {
        "type": "outputAdapter",
        "name": "fileOrEmptyList",
        "version": "1.0.0",
        "scriptFile": "conf/plugins/fileOrEmptyList.kt",
        "supportedDataType": "fileOrEmptyList"
    }
]

GET plugin by name

Get information about a single plugin.

Resource URL
/services/:name
Parameters
nameThe name of the plugin to return
Status codes
200The operation was successful
404The plugin was not found
Example request
GET /plugins/fileOrEmptyList HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 136
content-type: application/json
 
{
    "type": "outputAdapter",
    "name": "fileOrEmptyList",
    "version": "1.0.0",
    "scriptFile": "conf/plugins/fileOrEmptyList.kt",
    "supportedDataType": "fileOrEmptyList"
}

GET services

Get information about all configured service metadata. To get metadata of a single service, use the GET service by ID endpoint.

Resource URL
/services
Parameters
None
Status codes
200The operation was successful
Example request
GET /services HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 2167
content-type: application/json
 
[
  {
    "id": "cp",
    "name": "cp",
    "description": "Copies files",
    "path": "cp",
    "runtime": "other",
    "parameters": [{
      "id": "no_overwrite",
      "name": "No overwrite",
      "description": "Do not overwrite existing file",
      "type": "input",
      "cardinality": "1..1",
      "dataType": "boolean",
      "default": false,
      "label": "-n"
    }, {
      "id": "input_file",
      "name": "Input file name",
      "description": "Input file name",
      "type": "input",
      "cardinality": "1..1",
      "dataType": "file"
    }, {
      "id": "output_file",
      "name": "Output file name",
      "description": "Output file name",
      "type": "output",
      "cardinality": "1..1",
      "dataType": "file"
    }],
    "runtimeArgs": [],
    "requiredCapabilities": []
  }, {
    "id": "sleep",
    "name": "sleep",
    "description": "sleeps for the given amount of seconds",
    "path": "sleep",
    "runtime": "other",
    "parameters": [{
      "id": "seconds",
      "name": "seconds to sleep",
      "description": "The number of seconds to sleep",
      "type": "input",
      "cardinality": "1..1",
      "dataType": "integer"
    }],
    "runtimeArgs": [],
    "requiredCapabilities": []
  },
  …
]

GET service by ID

Get configured metadata of a single service.

Resource URL
/services/:id
Parameters
idThe ID of the service to return
Status codes
200The operation was successful
404The service metadata was not found
Example request
GET /services/sleep HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 401
content-type: application/json
 
{
  "id": "sleep",
  "name": "sleep",
  "description": "sleeps for the given amount of seconds",
  "path": "sleep",
  "runtime": "other",
  "parameters": [{
    "id": "seconds",
    "name": "seconds to sleep",
    "description": "The number of seconds to sleep",
    "type": "input",
    "cardinality": "1..1",
    "dataType": "integer"
  }],
  "runtimeArgs": [],
  "requiredCapabilities": []
}

GET setups

Get information about all configured setups. To get a single setup, use the GET setup by ID endpoint.

Resource URL
/setups
Parameters
None
Status codes
200The operation was successful
404Setups are unavailable because cloud configuration is disabled
Example request
GET /setups HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 3526
content-type: application/json
 
[
  {
    "id": "default",
    "flavor": "7d217779-4d7b-4689-8a40-c12a377b946d",
    "imageName": "Ubuntu 18.04",
    "availabilityZone": "nova",
    "blockDeviceSizeGb": 50,
    "minVMs": 0,
    "maxVMs": 4,
    "provisioningScripts": [
      "conf/setups/default/01_docker.sh",
      "conf/setups/default/02_steep.sh"
    ],
    "providedCapabilities": ["docker"],
    "additionalVolumes": [{
      "sizeGb": 50,
      "type": "SSD"
    }]
  },
  …
]

GET setup by ID

Get information about a single setup.

Resource URL
/setups/:id
Parameters
idThe ID of the setup to return
Status codes
200The operation was successful
404The setup cannot be found or setups are unavailable because cloud configuration is disabled
Example request
GET /setups/default HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 407
content-type: application/json
 
{
  "id": "default",
  "flavor": "7d217779-4d7b-4689-8a40-c12a377b946d",
  "imageName": "Ubuntu 18.04",
  "availabilityZone": "nova",
  "blockDeviceSizeGb": 50,
  "minVMs": 0,
  "maxVMs": 4,
  "provisioningScripts": [
    "conf/setups/default/01_docker.sh",
    "conf/setups/default/02_steep.sh"
  ],
  "providedCapabilities": ["docker"],
  "additionalVolumes": [{
    "sizeGb": 50,
    "type": "SSD"
  }]
}

Perform a full-text search in Steep’s database to find submissions and process chains.

The response is a JSON object with the attributes counts and results:

  • counts is an object containing the total number of matches in the database for each possible object type (workflow and processChain) as well as a total sum (total). The numbers may either be exact or estimated depending on the count parameter given in the request. The object might also be left off if count equals none.
  • results is a list of search result objects sorted by relevance.
Resource URL
/search
Parameters
qThe search query
size
(optional)		The maximum number of search results to return. The default value is 10.
offset
(optional)		The offset of the first search result to return. The default value is 0.
count
(optional)		Specifies how Steep should count the total number of search results and if they should be included in the response. Possible values are: exact to include an exact count in the response (may take a long time depending on how many objects match), estimate to include a rough estimate (very fast but might be incorrect), and none if the total number of results should not be counted at all. The default value is estimate.
timeZone
(optional)		An ID of the time zone in which dates and times in the query are specified (typically the time zone of the client or web browser). Valid values are taken from the IANA Time Zone database (e.g. Europe/Berlin). Defaults to the server’s time zone.
Status codes
200The operation was successful
400One of the parameters was invalid. See response body for error message.
Example request
GET /search?q=docker HTTP/1.1
Example response
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 886
content-type: application/json
x-page-offset: 0
x-page-size: 10
x-page-total: 10
 
{
  "counts": {
    "workflow": 6,
    "processChain": 4,
    "total": 10
  },
  "results": [{
    "id": "az2ne7scskxqqzduorzq",
    "type": "workflow",
    "requiredCapabilities": [
      "sleep",
      "docker"
    ],
    "status": "SUCCESS",
    "name": "Docker Sleep",
    "startTime": "2022-06-02T05:43:10.397144Z",
    "endTime": "2022-06-02T05:43:42.534494Z",
    "matches": [{
      "locator": "name",
      "fragment": "Docker Sleep",
      "termMatches": [{
        "term": "docker",
        "indices": [0]
      }]
    }, {
      "locator": "requiredCapabilities",
      "fragment": "docker",
      "termMatches": [{
        "term": "docker",
        "indices": [0]
      }]
    }]
  },
  ...
  ]
}

GET Prometheus metrics

Steep can provide metrics to Prometheus. Besides statistics about the Java Virtual Machine that Steep is running in, the following metrics are included:

MetricDescription
steep_remote_agentsThe number of registered remote agents
steep_controller_process_chainsThe number of generated process chains the controller is currently waiting for grouped by submissionId
steep_scheduler_process_chainsThe number of process chains with a given status (indicated by the label status)
steep_local_agent_retriesThe total number of times an executable with a given service ID (indicated by the label serviceId) had to be retried
steep_eventbus_compressedjson_messagesTotal number of compressed JSON messages sent/received over the event bus (label operation is either sent or recv)
steep_eventbus_compressedjson_bytesTotal number of compressed JSON bytes. Label operation is either sent or recv, and label stage is either compressed or uncompressed. Uncompressed bytes will be compressed before they are sent over the event bus, and received compressed bytes will be uncompressed.
steep_eventbus_compressedjson_timeTotal number of milliseconds spent compressing or decompressing JSON (label operation is either sent or recv and specifies if sent bytes have been compressed or received bytes have been uncompressed)
Resource URL
/metrics
Parameters
None
Status codes
200The operation was successful
Example request
GET /metrics HTTP/1.1
Example response
HTTP/1.1 200 OK
content-type: text/plain
content-encoding: gzip
content-length: 1674
 
# HELP jvm_memory_bytes_used Used bytes of a given JVM memory area.
# TYPE jvm_memory_bytes_used gauge
jvm_memory_bytes_used{area="heap",} 2.1695392E8
jvm_memory_bytes_used{area="nonheap",} 1.46509968E8
…
# HELP steep_remote_agents Number of registered remote agents
# TYPE steep_remote_agents gauge
steep_remote_agents 1.0
…
# HELP steep_scheduler_process_chains Number of process chains with a given status
# TYPE steep_scheduler_process_chains gauge
steep_scheduler_process_chains{status="SUCCESS",} 2.0
steep_scheduler_process_chains{status="RUNNING",} 0.0
steep_scheduler_process_chains{status="ERROR",} 1.0
…
Full-text search
Web-based user interface