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:
HTTP/1.1 201 Created
Content-Length: 80
Content-Type: application/json;charset=UTF-8
Location: http://localhost:8080/api/execution/511b0441-d6d0-4a8a-8003-22ef52740847
{
"uuid": "511b0441-d6d0-4a8a-8003-22ef52740847",
"uri": "/api/execution/511b0441-d6d0-4a8a-8003-22ef52740847",
"token": "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI1MTFiMDQ0MS1kNmQwLTRhOGEtODAwMy0yMmVmNTI3NDA4NDciLCJzdWIiOiJleGVjdXRvciIsImlhdCI6MTU1NzI0NjE4OSwiZXhwIjoxNTU3Mjc0OTg5fQ.2GVAuboArO8k1G48CY1ojFdypO9zm9u2ZubCE7Qa-Co"
}
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:.
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI1MTFiMDQ0MS1kNmQwLTRhOGEtODAwMy0yMmVmNTI3NDA4NDciLCJzdWIiOiJleGVjdXRvciIsImlhdCI6MTU1NzI0NjE4OSwiZXhwIjoxNTU3Mjc0OTg5fQ.2GVAuboArO8k1G48CY1ojFdypO9zm9u2ZubCE7Qa-Co
{
"uuid": "89828e1e-c834-42a2-86f1-893209f63ab5",
"uri": "/product",
"terminal": false,
"backEnabled": false,
"export": {"product1": "Product1", "product2": "Product2"},
"payload": {"product": "product1"}
)
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:
POST /api/executor/c973a8e7-eb24-4e55-980f-f2ea0fff680e HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI1MTFiMDQ0MS1kNmQwLTRhOGEtODAwMy0yMmVmNTI3NDA4NDciLCJzdWIiOiJleGVjdXRvciIsImlhdCI6MTU1NzI0NjE4OSwiZXhwIjoxNTU3Mjc0OTg5fQ.2GVAuboArO8k1G48CY1ojFdypO9zm9u2ZubCE7Qa-Co
{
"uuid": "3a0d231f-12b8-47b3-a495-b9418db294b3",
"payload": {
"firstname": "Joe",
"lastname": "Bloke",
"id_card": {
"uuid": "a3c6c1ec-ae02-47a6-8cac-8760521f2ed8",
"fileName": "my_cool_id_card_photo.png",
"mimeType": "application/png",
"size": 123123,
"expiredOn": "2020-01-01T12:00:00Z"
}
}
}
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:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI1MTFiMDQ0MS1kNmQwLTRhOGEtODAwMy0yMmVmNTI3NDA4NDciLCJzdWIiOiJleGVjdXRvciIsImlhdCI6MTU1NzI0NjE4OSwiZXhwIjoxNTU3Mjc0OTg5fQ.2GVAuboArO8k1G48CY1ojFdypO9zm9u2ZubCE7Qa-Co
{
"uuid": "89828e1e-c834-42a2-86f1-893209f63ab5",
"uri": "/product",
"terminal": false,
"backEnabled": false,
"export": {"product1": "Product1", "product2": "Product2"}
)
This is an example of a route validation error response:
HTTP/1.1 422 UNPROCESSABLE ENTITY
Content-Type: application/json;charset=UTF-8
{
"errors": [
{
"field": "mobile",
"message": "Required"
}
]
}
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:
POST /api/executor/c973a8e7-eb24-4e55-980f-f2ea0fff680e/back HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI1MTFiMDQ0MS1kNmQwLTRhOGEtODAwMy0yMmVmNTI3NDA4NDciLCJzdWIiOiJleGVjdXRvciIsImlhdCI6MTU1NzI0NjE4OSwiZXhwIjoxNTU3Mjc0OTg5fQ.2GVAuboArO8k1G48CY1ojFdypO9zm9u2ZubCE7Qa-Co
{
"uuid": "3a0d231f-12b8-47b3-a495-b9418db294b3",
"payload": {
"firstname": "Joe"
}
}
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.
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"uuid": "fc05e808-9521-4268-af2d-dcc68a6eb4c9",
"uri": "/basic",
"terminal": false,
"backEnabled": false,
"payload": {
"firstname": "Joe",
"lastname": "Bloke"
}
}
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
POST /api/execution/871fe310-c9c9-4f54-ac2d-80380cb235c0/function/ HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI1MTFiMDQ0MS1kNmQwLTRhOGEtODAwMy0yMmVmNTI3NDA4NDciLCJzdWIiOiJleGVjdXRvciIsImlhdCI6MTU1NzI0NjE4OSwiZXhwIjoxNTU3Mjc0OTg5fQ.2GVAuboArO8k1G48CY1ojFdypO9zm9u2ZubCE7Qa-Co
{
"name": "exchange"
}
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:
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Location: http://localhost:8080//api/execution/871fe310-c9c9-4f54-ac2d-80380cb235c0/function/9899999f-0845-4027-9cfd-09d1f109a420
{
"uuid": "9899999f-0845-4027-9cfd-09d1f109a420",
"uri": "/api/execution/871fe310-c9c9-4f54-ac2d-80380cb235c0/function/9899999f-0845-4027-9cfd-09d1f109a420"
}
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:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI1MTFiMDQ0MS1kNmQwLTRhOGEtODAwMy0yMmVmNTI3NDA4NDciLCJzdWIiOiJleGVjdXRvciIsImlhdCI6MTU1NzI0NjE4OSwiZXhwIjoxNTU3Mjc0OTg5fQ.2GVAuboArO8k1G48CY1ojFdypO9zm9u2ZubCE7Qa-Co
{
"hello": "dummy"
}