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: