Endpoints for interacting with the Xpress Executor component, scheduling executions, querying status & results.
GET /runtime/status
Summarize the repository status
Response codes indicate the following:
- 200 OK: The repository status is returned
- 500 Internal Server Error: Unexpected failure within component
Response Body
| media type |
data type |
description |
| application/json |
RepositoryStatus (JSON) |
A JSON document describing the status of the component |
GET /runtime/execution
List all of the executions currently in the repository.
Response codes indicate the following:
- 200 OK: The executions list is returned (may be empty)
- 500 Internal Server Error: Unexpected failure within component
Response Body
| media type |
data type |
description |
| application/json |
array of ModelExecution (JSON) |
A JSON array of structures describing the current status of the executions, in order of creation. |
DELETE /runtime/execution
Delete all of the executions currently in the repository.
Response codes indicate the following:
- 200 OK: The executions list is returned (will contain only executions that could not be deleted, or were scheduled during deletion)
- 500 Internal Server Error: Unexpected failure within component
Response Body
| media type |
data type |
description |
| application/json |
array of ModelExecution (JSON) |
A JSON array of structures describing the current status of the surviving executions, in order of creation. |
POST /runtime/execution
Schedule a new execution of the model, with the input data & parameters as specified.
Response codes indicate the following:
- 200 OK: The execution has been scheduled
- 400 Bad Request: The execution request is in some way invalid
- 507 Insufficient Storage: The execution could not be scheduled because there isn't enough quota to store the input data; the client should either delete some existing executions or resubmit with a smaller amount of input data.
- 500 Internal Server Error: Unexpected failure within component
Request Body
| media type |
data type |
description |
| application/json |
ExecutionRequestData (JSON) |
A JSON structure describing the input data & parameters for the execution |
Response Body
| media type |
data type |
description |
| application/json |
ModelExecution (JSON) |
A JSON structure describing the current status of the execution. The new execution can be referenced using the unique "execution ID" you obtain from the 'id' field of this. |
POST /runtime/execution
Schedule a new execution of the model, with the input data & parameters as specified by the given form POST. This is usually used for submitting an iframe AJAX request using a form, passing a file from the local file system as input.
Request Body
| media type |
data type |
description |
| multipart/form-data |
(custom) |
A form posting from which the field "input" will be used as the model inputs, and fields with names starting "param-" will be used to set parameters, e.g. in HTML, a field to set the MAX_NUM_EMPLOYEES parameters would be: <input type="text" name="param-MAX_NUM_EMPLOYEES" /> |
Response Body
| media type |
data type |
description |
| text/html |
(custom) |
An object representing the request response. On success, the returned status code is 200 and the entity is a string containing a JSON ModelExecution structure. On error, the returned status code is something other than 200 and the entity is a string describing the error. |
GET /runtime/ping
Reads the current server time in milliseconds, useful for checking the component is alive.
Response Body
| media type |
data type |
description |
| application/json |
string (JSON) |
the current server time in milliseconds |
GET /runtime/execution/{id}
Return the status of the specified execution.
Response codes indicate the following:
- 200 OK: Operation successful
- 404 Not Found: When the execution does not exist in the component
- 500 Internal Server Error: General failure upon trying to access execution status
Request Parameters
| name |
type |
description |
| id |
path |
The execution ID. |
Response Body
| media type |
data type |
description |
| application/json |
ModelExecution (JSON) |
A JSON structure describing the current status of the execution. |
DELETE /runtime/execution/{id}
Delete an execution. If the execution is not executing, it will be removed from the database and all endpoints associated with the execution ID will subsequently return "404 Not Found". If the execution is currently in progress, it will be flagged as "cancelled" to ensure it is interrupted at the next opportunity, and will be deleted as soon as it either interrupts or completes.
Response codes indicate the following:
- 200 OK: Operation successful
- 404 Not Found: When the execution does not exist in the component
- 500 Internal Server Error: General failure upon trying to delete execution
Request Parameters
| name |
type |
description |
| id |
path |
The execution ID. |
Response Body
| media type |
data type |
description |
| application/json |
object (JSON) |
An OK response if the execution was deleted or flagged for later deletion. |
| application/xml |
anyType (XML) |
GET /runtime/execution/{id}/runlog
Return the run log of the specified execution. The run log is the output of the model, including anything the model itself writes to its log, any error messages, and possibly solver diagnostics.
Calling this endpoint before the execution has completed will return the run log output by the model to-date.
Response codes indicate the following:
- 200 OK: Operation successful
- 404 Not Found: When the execution does not exist or the run log can not be found
- 500 Internal Server Error: General failure upon trying to access execution run log
Request Parameters
| name |
type |
description |
| id |
path |
the execution ID |
Response Body
| media type |
data type |
description |
| text/plain |
(custom) |
The execution run log |
GET /runtime/execution/{id}/runlog
Return part of run log of the specified execution. The run log is the output of the model, including anything the model itself writes to its log, any error messages, and possibly solver diagnostics. The run log fragment will be returned as an array of lines within a JSON structure. The lines do not include trailing newline characters.
The "version" field of the returned structure will only be changed in the case of an execution being restarted. When retrieving something other than the start of the run log, you should always check that this value has not changed since your last call to this endpoint; if it has changed, this means the execution has been restarted and you should retrieve the run log again, starting from line 1.
Response codes indicate the following:
- 200 OK: Operation successful
- 404 Not Found: When the execution does not exist or the run log can not be found
- 500 Internal Server Error: General failure upon trying to access execution run log
Request Parameters
| name |
type |
description |
default |
constraints |
| id |
path |
the execution ID |
|
|
| firstLine |
query |
retrieve a fragment of the run log starting from this line. The run log lines are numbered starting from 1. If unspecified, returns run log starting from line 1. |
1 |
int |
| maxLines |
query |
maximum number of lines to return. If unspecified, will return as many lines as are currently available in the repository. |
2147483647 |
int |
Response Body
| media type |
data type |
description |
| application/json |
RunLogFragment (JSON) |
The execution run log |
GET /runtime/execution/{id}/result
Return the result of the executing model, as output by the model itself in a file called 'result'. This is only available after the model execution has completed.
Response codes indicate the following:
- 200 OK: Operation successful
- 404 Not Found: When the execution does not exist, has not completed or the model did not output a result file./li>
- 500 Internal Server Error: General failure upon trying to access the result of the execution
Request Parameters
| name |
type |
description |
| id |
path |
The execution ID. |
Response Body
| media type |
data type |
description |
| application/octet-stream |
(custom) |
The result of the execution |