Flux REST API
Aside from programmatically managing your Flux services via
FluxMethods
, Martini also allows you to manage your workflows via the
Flux REST API. With this API, you can:
- Execute a Flux service
- Terminate a Flux service
- Send an event to Flux services
- Get all Flux services' contexts
- Get a Flux service's context
- Get a Flux state's context
- Add a tag to a Flux service
- Remove a Flux service's tag
- Get a Flux service's definition
Flux REST API or FluxMethods
?
If you are trying to handle Flux service(s) from another service,
TORO recommends you use FluxMethods
instead.
Headers
By default, the Flux REST API allows access to all Flux services. The request privilege
may be elevated by providing an Authorization
header:
Header Name | Data Type | Description |
---|---|---|
Authorization | string | Bearer <The access token of a Martini user> |
Endpoints
All endpoints of the Flux REST API have paths beginning with /flux-api
. Read on below for more information about the
API's endpoints.
Available as a Postman collection (v2.1)
You can use Postman to try out and call the endpoints of the Flux REST API. Simply download and import this Postman collection.
Execute a Flux service
Method | Path |
---|---|
POST |
/flux-api/{package}/execute |
Request
Path parameters
Parameter name | Data type | Required | Description |
---|---|---|---|
package |
string | true | The name of the Martini package where the Flux is contained. |
Body Parameters
Parameter Name | Data Type | Required | Description |
---|---|---|---|
fluxName |
string | true | The name of the Flux service to be run. If the service is located inside a directory, its name should be prepended by the name of its subdirectories separated by periods. For example, org.your.SendAlerts . |
startState |
string | false | The name of the state where the Flux execution should start. |
input |
object | false | The inputs which will be fed to the target Flux service. |
tags |
string[] | false | The tags to be added to the Flux service during execution. |
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | curl -X POST \ 'http://<host>:<port>/flux-api/examples/execute' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "fluxName": "flux.ProcessData", "input": { "order": { "productId": "productA", "quantity": 2 } }, "tags": [ "invoke" ] }' |
Response
Content Type
application/json
application/xml
Example
1 2 3 4 | { "message" : "Flux flux.ProcessData is now executing", "contextId" : 13 } |
Terminate a Flux service
Method | Path |
---|---|
DELETE |
/flux-api/terminate |
Request
Query Parameters
Parameter Name | Data Type | Required | Description |
---|---|---|---|
contextId |
long | true | The context ID of the to-be-stopped but running Flux service. |
Example
1 2 3 | curl -X DELETE \ 'http://localhost:8080/flux-api/terminate?contextId=32' \ -H 'Accept: application/json' |
Response
Content Type
application/json
application/xml
Example
1 2 3 | { "message" : "Flux terminated" } |
Send an event to Flux services
Method | Path |
---|---|
POST |
/flux-api/event |
Request
Query Parameters
Parameter Name | Data Type | Required | Description |
---|---|---|---|
contextId |
long | false | The context ID of the running Flux service you want to send the event to. Specify this parameter only when a single Flux service will receive the event. |
Body Parameters
Parameter Name | Data Type | Required | Description |
---|---|---|---|
event |
string | true | The name of the event the waiting state should transition to. |
input |
object | false | The inputs to be given to the Flux service(s). |
tags |
string[] | false | The tags to use for determining which Flux Services the external event should be sent to. |
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 | curl -X POST \ http://localhost:8080/flux-api/event \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "event": "done", "input": { "greeting": "hello" }, "tags": [ "users" ] }' |
Response
Parameter Name | Data Type | Description |
---|---|---|
transitions |
object[] | The Flux services which were transitioned by the external event. |
executions |
object[] | The Flux services which were triggered by the external event. |
Content Type
application/json
application/xml
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | { "message": "Event done has been sent", "transitions": [ { "contextId": 201, "state": "state_A" }, { "contextId": 203, "state": "state_B" } ], "executions": [ { "contextId": 205, "state": "state" } ] } |
Get all Flux services' contexts
Method | Path |
---|---|
GET |
/flux-api/contexts |
Request
Query Parameters
Parameter Name | Data Type | Required | Multiple | Description |
---|---|---|---|---|
fluxName |
string | false | false | Specify to fetch only the contexts of Flux services whose names match the value of this parameter. |
tag |
string | false | true | Specify to fetch only the contexts of Flux services whose tags match all the values of this parameter. |
status |
string | false | false | Specify to fetch only the contexts of Flux services whose statuses match the value of this parameter. |
currentState |
string | false | false | Specify to fetch only the contexts of Flux services whose current states match the value of this parameter. |
startState |
string | false | false | Specify to fetch only the contexts of Flux services whose starting states match the value of this parameter. |
limit |
integer | false | false | Limits the number of contexts returned. The default value is 30 . |
page |
integer | false | false | Used with limit to select which page of the response should be returned. Its default value is 0 . |
Example
1 2 3 | curl -X GET \ 'http://localhost:8080/flux-api/contexts?status=WAITING_UNTIL&fluxName=flux.ProcessExternalEvent' \ -H 'Accept: application/json' |
Response
Content Type
application/json
application/xml
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 | [ { "fluxName": "flux.ProcessExternalEvent", "id": 185, "currentState": "Process_Event_State", "startState": "Start_State", "waiting": true, "debugged": true, "nextRun": 1526967557049, "status": "WAITING_UNTIL", "input": { "name": "input", "type": "model", "allowExtraProperties": true, "gloopProperties": [] }, "output": { "name": "output", "type": "model", "allowExtraProperties": true, "gloopProperties": [] }, "tags": [], "stateContexts": [ { "name": "Start_State", "input": { "name": "input", "type": "model", "allowExtraProperties": true, "gloopProperties": [] }, "output": { "name": "output", "type": "model", "allowExtraProperties": true, "gloopProperties": [] }, "transitionContexts": [ {} ] } ], "executionHistory": [ { "fluxName": "flux.ProcessExternalEvent", "stateName": "Start_State", "stateIndex": 0 } ] } ] |
Get a Flux service's context
Method | Path |
---|---|
GET |
/flux-api/context |
Request
Query Parameters
Parameter Name | Data Type | Required | Description |
---|---|---|---|
contextId |
long | true | The context ID of the running Flux service whose context is to be fetched. |
Example
1 2 3 | curl -X GET \ 'http://localhost:8080/flux-api/context?contextId=209' \ -H 'Accept: application/json' |
Response
Content Type
application/json
application/xml
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 | { "fluxName": "flux.ProcessExternalEvent", "id": 209, "currentState": "Process_Event_State", "startState": "Start_State", "waiting": true, "debugged": true, "nextRun": 1526974884257, "status": "WAITING_UNTIL", "input": { "name": "input", "type": "model", "allowExtraProperties": true, "gloopProperties": [] }, "output": { "name": "output", "type": "model", "allowExtraProperties": true, "gloopProperties": [] }, "tags": [], "stateContexts": [ { "name": "Start_State", "input": { "name": "input", "type": "model", "allowExtraProperties": true, "gloopProperties": [] }, "output": { "name": "output", "type": "model", "allowExtraProperties": true, "gloopProperties": [] }, "transitionContexts": [ {} ] } ], "executionHistory": [ { "fluxName": "flux.ProcessExternalEvent", "stateName": "Start_State", "stateIndex": 0 } ] } |
Get a Flux state's context
Method | Path |
---|---|
GET |
/flux-api/context/state |
Request
Query Parameters
Parameter Name | Data Type | Required | Description |
---|---|---|---|
contextId |
long | true | The context ID of the running Flux service that owns the state whose context is to be fetched. |
stateName |
string | true | The name of the state whose context is to be fetched. |
Example
1 2 3 | curl -X GET \ 'http://localhost:8080/flux-api/context/state?contextId=217&stateName=Start_State' \ -H 'Accept: application/json' |
Response
Content Type
application/json
application/xml
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | { "name": "Start_State", "input": { "name": "input", "type": "model", "allowExtraProperties": true, "gloopProperties": [] }, "output": { "name": "output", "type": "model", "allowExtraProperties": true, "gloopProperties": [] }, "transitionContexts": [ {} ] } |
Add a tag to a Flux service
Method | Path |
---|---|
POST |
/flux-api/context/tag |
PUT |
/flux-api/context/tag |
Request
Query Parameters
Parameter Name | Data Type | Required | Multiple | Description |
---|---|---|---|---|
contextId |
long | true | false | The context ID of the running Flux service that will receive the new tag. |
tag |
string | true | true | The tag to add. |
Example
1 2 3 | curl -X POST \ 'http://localhost:8080/flux-api/context/tag?contextId=241&tag=tag1,tag2' \ -H 'Accept: application/json' |
Response
Content Type
application/json
application/xml
Example
1 2 3 | { "message": "Tags [tag1, tag2] successfully added to flux context with id '241'" } |
Remove a Flux service's tag
Method | Path |
---|---|
DELETE |
/flux-api/context/tag |
Request
Query Parameters
Parameter Name | Data Type | Required | Multiple | Description |
---|---|---|---|---|
contextId |
long | true | false | The context ID of the running Flux service whose tag will be removed. |
tag |
string | true | true | The tag to remove. |
Example
1 2 3 | curl -X DELETE \ 'http://localhost:8080/flux-api/context/tag?contextId=257&tag=tag3,tag4' \ -H 'Accept: application/json' |
Response
Content Type
application/json
application/xml
Example
1 2 3 | { "message": "Tags [tag3, tag4] successfully removed from flux context with id '257'" } |
Get a Flux service's definition
Method | Path |
---|---|
GET |
/flux-api/definition |
Request
Query Parameters
The parameter fluxName
and contextId
are mutually exclusive; only one of them is required for the request. If both
are specified, contextId
takes precedence over fluxName
.
Parameter Name | Data Type | Required | Description |
---|---|---|---|
fluxName |
string | false | The name of the Flux service whose definition is to be fetched. If the service is located inside a directory, its name should be prepended by the name of its subdirectories separated by periods. For example, org.your.SendAlerts . |
contextId |
long | false | The context ID of the specific running Flux service whose definition is to be fetched. |
Example
1 2 3 | curl -X GET \ 'http://localhost:8080/flux-api/definition?fluxName=flux.FluxWithTrigger' \ -H 'Accept: application/json' |
Response
Content Type
application/json
application/xml
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | { "comment" : "This Flux service demonstrates how to use triggers. Triggers are events that can start a Flux service, when the Flux engine receives an event it will look for Flux services with matching trigger events and start them.\n\nThis Flux service has two triggers 'trigger1' and 'trigger2'. To send a trigger event, right click the Flux editor and send an event using one of the trigger event. To monitor the execution of the Flux service open a Martini console or the Martini Service Manager view.", "triggers" : [ "trigger2", "trigger1" ], "states" : [ { "name" : "Print_Trigger", "displayName" : "Print Trigger", "x" : 120, "y" : 120, "comment" : "This states logs the event data that triggered this Flux service. The triggering event can be retrieved using the special property '$triggerFluxEvent'.", "action" : { "type": "invokeCode", "className": "io.toro.martini.LoggerMethods", "methodName": "info", "parameters": [ "String" ], "inputs": [ { "type": "set", "expression": "\"This Flux service was started using the trigger \\\"${$triggerFluxEvent}\\\".\"", "evaluate": true, "to": [ "message" ] } ] }, "input" : [ ], "output" : [ ] } ] } |