HTTP Trigger
Discover more about the HTTP Trigger and how to use it on the Digibee Integration Platform.
When a pipeline is configured and published with HTTP Trigger, an HTTP endpoint is automatically created. You can visualize this endpoint after the implantation - all you have to do is click on the pipeline card in the Run screen.
With this trigger, you have the flexibility to define different content types not only for the request, but also for the endpoint response.
Parameters
Take a look at the configuration parameters of the trigger. Parameters supported by Double Braces expressions are marked with (DB).
There is a global configuration parameter that obliges all the pipelines to be published with at least the API Key or Basic Auth options enabled.
Parameters additional information
Add Cross-Origin Resource Sharing (CORS) - CORS Headers (DB)
(DB)Cross-Origin Resource Sharing (CORS) is a mechanism that lets you tell the browser which origins are allowed to make requests. To configure globally rather than individually on each pipeline see the CORS HTTP header policy.
We use a comma to enter multiple values in a header, but we don't add a space before or after the comma. Special characters should not be used in keys, due to possible failures in proxies and gateways.
Maximum Request Size
If the payload sent by the endpoint consumer overcomes the limit, a message will be returned informing that the maximum size has been overcome and a status-code 413 with the following message:
mTLS enabled API
This parameter does not support API Key, JWT, or Basic Auth. To use it in your realm, it is necessary to make a request via chat and we will send you the necessary information to install this service.
Additional API Routes
As previously explained, this option is for the configurations of new endpoint routes.
When deploying a pipeline, a URL is automatically created. However, you can customize the route according to your convenience. It also includes the parameters received through the route.
After the pipelines are deployed, the URLs will get the following structure:
TEST:
or PROD:
{realm}: corresponds to realm.
v{n}: pipeline's major version.
{pipeline-name}: name given to the pipeline.
Custom static route
Let’s say you’ve created the product-list pipeline. Considering the comment above, your URL would look like this:
Now, see how to configure a static route for this case.
With the configurations applied and the pipeline deployed, you will get a new URL:
Custom route with parameter in the route
Using the same example of the previously configured pipeline, see how to custom the route:
With the configurations applied and the pipeline deployed, you will get a new URL:
In this case, the endpoint consumer can send a request containing the id of a product and return information only about it. Example of the request URL:
To use this value sent by the route inside the pipeline, go for the Double Braces syntax:
Remove Digibee Prefix from Route
As previously explained, this option is recommended for removing the default Digibee route prefix from pipeline route.
Let’s say you’ve created a pipeline and set the trigger as follows:
With the configurations applied and the pipeline deployed, you will get a new URL:
When removing the default prefix and setting the pipeline route through the Additional API Routes parameter, be careful not to set an existing pipeline route used by other pipelines. In case you have more than one pipeline major version, it’s also important to keep in mind that the pipeline route versioning must be done by the user due the absence of a versioning path parameter. For example: /pipeline/realm/v1/.
Rate Limit
When creating APIs, we usually want to limit the number of API requests users can make in a given time interval.
This action can be performed by activating the Rate Limit option and applying the following settings:
If the API has additional paths, the limit is shared among all paths. To apply the rate limit settings, the API must be configured with an API key or Basic Auth so that the Aggregate by parameter can be used by groups of credentials if the Consumer option is selected, or by an individual credential if the Credential (API Key, Basic Auth) option is selected.
If multiple interval parameters are configured with repeating values, only one of these values is considered. It’s also necessary that a value greater than zero be informed for the Limit parameter.
If the rate limiting options aren't set correctly, they'll be ignored and a warning log will be issued. You can view this log on the Pipeline Logs page.
HTTP Trigger in action
See below how the trigger behaves in a determined situation and what its respective configuration is.
Information query API with XML response
Check how to configure a pipeline with HTTP Trigger to return information from inside the pipeline in XML format and how the response must be handled specifically for this trigger.
First of all, create a new pipeline and configure the trigger. The configuration can be made as follows:
With the configurations above, you set that:
the endpoint works with the verb GET only;
the request accepts content-type related to the XML only;
the response returns content-type related to the XML only.
Besides, you determine that the API is external and doesn’t need a token for the communication.
This example work for educational matters only. In some cases, you can’t leave the endpoint open for security reasons.
Now observe how to configure a MOCK in the pipeline so it becomes the data provider the endpoint returns in the end. Add the indicated component, connect it to the trigger and configure it with the following JSON:
The next step is to add a component that transforms the previously created JSON into a XML pattern. For that, use JSON To XML Transformer, add it to the canvas and connect it to the JSON Generator that was previously added. Keep the following configuration:
After that, the last step is to set and determine how the response of this information will be made to the consumer. Add a MOCK again, given that its function will be to set the response only. Connect it to the JSON To XML Transformer output.
To configure this MOCK, use the following JSON:
code: HTTP Status Code to be returned by the endpoint after a request is finished
body: response message body (Double Braces are being used to repass the information converted in the previous step). This item must necessarily be a string. If the data you want to send is a JSON, use the TOSTRING function.
Content-type: content type of the response body. All the types are supported, but must be declared in the Response Content Types field.
When done with all these configurations, you should have a pipeline that looks like the image below:
After the deployment, get the generated url and send a GET-type request. The endpoint must return the status-code 200, as previously shown, and the response body should look like this:
Whenever you want to make a request to the created endpoint, the structure of the message the trigger delivers to the pipeline is always the same and follows this pattern:
body: content to be sent in the request payload to be transformed into a string in this field.
form: if the form-data is used in the request, the sent data is delivered in this field.
headers: the headers sent in the request are delivered in this field, but some of them are automatically filled with the tool used to make the request.
queryAndPath: the query and path parameters provided in the URL are delivered in this field.
method: HTTP method used in the request to be delivered in this field.
contentType: when informed in the request, the Content-type value is repassed to the pipeline inside this field.
path: the path used in the URL in the request is repassed to this field.
Last updated
