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"
}