Hub Backend REST API

The Hub Backend provides a REST API for Hub Clients and Backoffice.

Hub Client API

The Hub Client API is used by Hub Clients to start, resume, and get the current state of a workflow execution.

Route resource

Route resource represents a route that will be rendered by a Hub client. It contains these fields:

• uuid - Identifies a route for the purpose of resuming a workflow execution.
• uri - Identifies a route for a hub-client. Used for client-side routing and rendering a corresponding route view.
• terminal - Marks a route as terminal. Set to true if the corresponding execution terminated.
• backEnabled - determines if it's possible to go back to a previous route
• export - Arbitrary data that is passed within a route. Useful for setting up a route view, such as a list of products.
• payload - A payload from a previous route, which may be used to pre-fill the current route view.

Security

The execution API endpoints are secured using JWT tokens. A token is generated when a workflow execution starts. This token is then used for accessing the corresponding workflow execution, identified by uuid.

The token expiration is set to 8 hours and can be modified using the jwt.expiration property.

When using the execution API endpoints, the token must be sent in the Authorization header.

Authorization: Bearer {token}

Start new execution

POST /api/executor/{name}

Creates and starts a new executor for a workflow, which is specified by a name. Optionally, omit the name if the Hub instance has only one workflow.

Optionally, the body can contain a JSON payload that can be then accessed in a workflow script using it.

Response

• Success response: 201 Created - The executor uri as a Location header, the body contains executor UUID, and the uri contains a JWT token for accessing the executor.
• Error response: 404 Not Found - A workflow with a name was not found, or there is no default workflow.

Example:

Query the current route

GET /api/execution/{uuid}

Query the current route using an executor with uuid. Since it must wait until the current route is ready, the response may take a few moments.

Response

• Success response: 200 OK - a success response with Route resource as a body
• Error response: 404 Not Found - an executor with uuid not found
• Error response: 400 Bad Request - invalid executor uuid or execution error
• Error response: 401 Unauthorized - invalid access token
• Error response: 500 Internal Server Error - execution error

Example:.

Submit data and resume execution

POST /api/execution/{uuid}

Submit data gathered at the current route and resume a workflow execution using an executor with uuid.

Request

Parameters:

• uuid - The route uuid to resume, such as the previous route uuid.
• payload - A JSON payload with user entered data and file descriptors for uploaded files.

Example:

Response

• Success response: 200 OK - The execution has resumed, the body contains the next route as Route resource.
• Alternate success response: 202 Accepted - The execution has resumed.
• Error response: 422 Unprocessable Entity - A route validation failed, and the body contains a list of validation errors.
• Error response: 400 Bad Request - Invalid executor uuid or execution error.
• Error response: 401 Unauthorized - Invalid access token.
• Error response: 404 Not Found - An executor with uuid not found.
• Error response: 500 Internal Server Error - Execution error.

Example response:

This is an example of a route validation error response:

Reverse execution to the previous route

POST /api/execution/{uuid}/back

Execution move back to the previous route which has an executor with the uuid.

Parameters:

• uuid: The uuid of the previous route.
• payload: A JSON payload that contains the user-specified data and also the file descriptors for uploaded files.

Request

Form of the request:

Response

• Success response: 200 OK - The body contains the previous route as the Route resource, including the payload from the previous route.
• Error response: 404 Not Found - An executor with the specifiec uuid was not found.
• Error response: 400 Bad Request - Invalid executor uuid or execution error.
• Error response: 401 Unauthorized - Invalid access token.
• Error response: 500 Internal Server Error - Execution error.

Execute function

POST /api/execution/{uuid}/function

Creates and starts a new executor for a function specified by a name with payload as input data.

Parameters:

• name - function registered with a specified name
• payload - input data as JSON payload

Request

Response

• Success response: 201 Created - Contains an executor uri as a Location header, the body contains executor UUID, and a uri with a JWT token for accessing the executor.
• Error response: 404 Not Found - A function with a name was not found.
• Error response: 422 Unprocessable Entity - Validation of the input data failed, and the body contains a list of validation errors.

Example response:

Query function result

GET /api/execution/{uuid}/function/{functionUUID}

Query the result of executed function with functionUUID within execution with uuid. Since it responds when the result is ready, it may take a few moments.

Response

• Success response: 200 OK - The function result is in the JSON body.
• Error response: 404 Not Found - An executor with uuid not found.
• Error response: 400 Bad Request - Invalid executor uuid or execution error.
• Error response: 401 Unauthorized - invalid access token

Form of the response: