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

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

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

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

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

[
    {
        "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

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

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

{
  "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" : [ ]
  } ]
}