API Trigger
An API Trigger is used when you want to start a Process by invoking a specified HTTP Endpoint or in short, expose an OpenAPI Specification interface with Frends. These Triggers are bound to existing OpenAPI Specification operations and are created through the Frends API Management View.
When configuring an API Trigger from the Process Editor, you must select which existing operation is bound to this specific Process.
API Trigger parameters
After selecting the API Operation, Control Panel will provide a set of parameters.
The HTTP method is locked to that provided in the Swagger operation, and can not be changed. Valid values are GET, POST, PUT, DELETE, HEAD, OPTIONS and PATCH.
The URL path is locked to that provided in the Swagger operation, and can not be changed. Path parameters are allowed. If the path parameters are of type integer or boolean, then the path will be restricted to contain only those types. This enables having Endpoints like /api/pet/{id} and /api/pet/getStatus active at the same time with no collision, if the {id} parameter is of type integer. However having /api/pet/{name} and /api/pet/getStatus at the same time would not be possible if the {name} parameter would be of type string.
The Allowed protocols defines whether to accept requests with HTTP, HTTPS or both. If a request is made with a protocol that is not allowed, the reply will be Forbidden (403).
The API Triggers can use four different kinds of Authentication:
None - No authentication at all
Basic - Authenticate with HTTP basic authentication. This authenticates the user either against the Active Directory or the local users. Which one is used depends on the Frends Agent service user. If the Agent uses a local user account, users are authenticated against the local machine users. If the Agent uses an AD user account, users are authenticated against the AD users. The username and password need to be encoded with UTF-8 before being converted to Base64 for the basic authentication header.
Certificate - Use a client certificate to authenticate. This requires that the client certificate is valid for the Frends Agent user on the Agent machine. Also, the issuer for the certificate needs to be found in the agent user's Client Authentication Issuers certificate store.
API Key - Authenticate with an API Key together with Ruleset to determine if the client has access to an URL. For more information, see API Keys.
OAuth2 - Authenticate using OAuth 2.0 bearer tokens from registered OAuth applications to gain access to the API. You need to set an API Access Policy to allow access.
If you are using scopes for controlling access to an API, you need to give the required scopes in the Swagger definition. Please note that if you give many scopes to an API Trigger operation, calls will go through if the OAuth token has any of the scopes given.
We strongly recommend to only use Authentication over HTTPS.
An Allow requests from these origins (CORS) flag is used if there is a need to allow a certain page to trigger a Process, i.e. enable cross-origin resource sharing (CORS). Check the "Allow requests from these origins" checkbox, and define the allowed origins in the textbox. The * character allows calls from all origins. Multiple origins can be provided separated with a colon(,) or semicolon(;)
Note: if the call does not come from the default port, it must be included in the origin. The origin making the call must also support CORS.
Intermediate return
A Process can return a response for the user before the Process is finished. This functionality is enabled by adding an Intermediate return Element to the Process. When this Element is executed the caller will receive a HTTP response from the Process. This can, for example, be used when calling a long-running Process and the caller should be notified that the long-running Task has started.
HTTP Response Formatting
The API Trigger returns the result of the executed Process as a HTTP response. The response varies according to the following conditions. When the Process' result is a string, the string is set as the body of the response. If it was an object, it will be returned either as JSON or XML depending on the request's ACCEPT header or JSON by default. For example ACCEPT: application/xml would produce an XML response, while ACCEPT: application/json would produce a JSON response.
If the result is an object with the properties HttpStatusCode and Content, the result will be mapped to a response accordingly:
HttpStatusCode: Reponse status code (int)
Content: The body of the response (string)
ContentEncoding: The encoding for the body, e.g. utf-8 (string)
ContentType: ContentType header value, e.g. application/xml or application/json (string)
HttpHeaders: Response headers (KeyValuePair[])
HTTP Response
The Process Element's return, Intermediate return and Throw all have the option to generate a pre-defined HTTP response. See HTTP Response results in the Parameter Editor.
Referencing Trigger parameter values
#trigger.data.httpBody
The body of the HTTP request in string format#trigger.data.httpClientIp
IP of the client as a string#trigger.data.httpCookies
Cookies associated with the request as a Dictionary#trigger.data.httpMethod
HTTP method type (e.g. GET, POST..)#trigger.data.httpRequestUri
Request URI (e.g. https://myfrendsagent.example.com:9998/api/MyApi/execute?mode=1).#trigger.data.username
The username associated with the caller. Only set if authentication is used. The following values are passed for the different types out authentications:
Api Key: The name of the API key
Basic authentication: The provided username
Certificate: The certificate's SubjectName.Name field
OAuth2: The value from the name claim#trigger.claimsprincipal(from 5.1.1)
The ClaimsPrincipal initialized from the access token. Only available when using OAuth2. You can access the claims collection with#trigger.claimsprincipal.Claimsor check individual claim existence with#trigger.claimsprincipal.HasClaim("foo"). When using role claims, e.g. from Azure AD, you can check if the token had the role via#trigger.claimsprincipal.IsInRole()#trigger.data.body
Will contain whatever is passed on the request body. If the body contains a JSON object, the properties will be accessible with dot notation. Eg, if the JSON string{ "house": { "windows": 4}}is passed in the body, it would be possible to access the "window" property with#trigger.data.body.house.window#trigger.data.path
Contains path parameters. Automatic casting will be attempted if the parameters have been defined in the swagger spec. Path parameters are mandatory and thus always populated.
If the path /user/{id} has been configured, and the parameter id is of type int, then the reference#trigger.data.path.idcan be used straight away for integer comparisons (for example in a Decision expression#trigger.data.path.id>3would be usable)#trigger.data.query
Contains query parameters. Automatic casting will be attempted if the parameters have been defined in the swagger spec. If the parameter has a default value and the request does not contain the parameter, the default value will be passed to the Process.
Query parameters defined in the swagger spec are always populated in the Trigger, even if no value is provided.#trigger.data.header
Contains header parameters. Automatic casting will be attempted if the parameters have been defined in the swagger spec. If the parameter has a default value and the request does not contain the parameter, the default value will be passed to the Process.
Header parameters defined in the swagger spec are always populated in the Trigger, even if no value is provided.
You can try to access an optional reference from any of the references (e.g.#trigger.data.httpHeader.foo) and if it is found the value will be returned and if not the value will be set to null.
Automatic casting of parameter values by definition
Swagger parameters usually contain a type definition. Parameters of type integer, number or boolean will be cast to their corresponding .NET type (Int, Long, Float, Double or Boolean). For array type parameters, the array will use the separator defined in the swagger parameter and the array content in turn will be cast according to their types. An array parameter with a csv separator and content type integer has the call content "1,2,3,4,5" and will be accessible as an JArray containing integer values.
The next article is Introduction to HTTP Trigger