Every public flow in a project has the option to become an endpoint for the API.
To expose a flow, you need to set the property Publish as endpoint for API.
There are a few options in the configuration that need some explanation.
Endpoint
REST/HTTP method
This defines the type the method is going to get. By default this is automatic. This means that the method will always be GET, except if the flow contains a parameter of type entity. That means that the parameters is expected as body, so a POST is needed to retrieve a body.
The other available methods are
•GET
•POST
•PUT
•PATCH
•DELETE
•HEAD
•OPTIONS
•TRACE
Custom path
By default the path to call this method is defined by the module, flow class and name of the flow.
So in this example
The path to call 'Hello world' would be: "ServerURL/demo/simple/helloworld".
When using the custom path, the name is replaced. So if we would take the example again, and set the custom path to 'directpath', our URL to call would look like: "ServerURL/demo/simple/directpath".
To make multiple paths available for the same flow, use a semi colon in the custom path field between the paths.
(Header) Flow
The flow option can be set to a flow that provides header values for the response.
This flow must be a static flow with the result set to list of HttpHeaderValue. (Can be found in Core.Activities.DataSource)
The header value must contain a 'key' and 'value' string.
Example flow
Authorization
On the autorization tab, you can define what roles have access to this flow.
The other option is to set the flow as Anonymously accessible, in this case, no login is needed to call the flow.
More information about logging in and roles can be found at Configure security
Parameters and return value
The structure of a flow changes the way the endpoint works. while parameters are usefull for retrieving data, the result can be set to text or an entity to send data to the caller.
Parameters
Ordinal types of pramaters can be used, this changes the url into 'Module/Flowclass/Flowname/paramater1/parameter2'
take these paramters as example for the hello world flow mentioned above:
Calling "ServerURL/demo/simple/helloworld/world/hello" would fill the 'WorldString' and 'HelloString' parameters with 'hello' and 'world' depending on the order of the parameters.
Entities can also be used as parameters, these will not be included in the url, but in the body.
Create a JSON of the entity and provide it as a string in the body, and use a parameter for the entities.
When providing multiple entities, use a list.
Example, when using event as a parameter:
provide this json in the body:
{
"EventID": 1,
"EventDate": "11-11-2024",
....
}
The HttpRequest entity can also be used as a special parameter, this will be used next to the existing parameters and provide information about the request.
it contains information like the caller host or content type, and has associations to:
- Header values
- Query values
- Form values
The full structure of this entitiy can be found in the plugin datasource Core.Activities.Datasource.
Return value
The return value can be a string or an entity, the string will be returned as raw string, and the entity as a JSON.
Keep in mind that associations are parsed with the entitiy, so if 'event' has an association to 'location', the return value on the request can look something like this:
{
"EventID": 1,
"EventDate": "11-11-2024",
"Location"": {
"LocationID": 2,
"LocationName": "The office",
...
}
....
}
