When a pipeline is configured and published with REST Trigger, a REST endpoint is automatically created. You can visualize this endpoint after the deployment - just click on the pipeline card in the Runtime screen.
With this trigger, you can create APIs that meet the REST standard and quickly define which methods your endpoint will answer to.
Take a look at the configuration parameters of the trigger:
Methods: configures the HTTP verbs to be supported by the endpoint after the deployment. If no value is informed, the default value will be considered: POST, PUT, GET, PATCH, DELETE and OPTIONS.
Maximum Timeout: limit time for the pipeline to process information before returning a response (standard = 30000, limit = 300000). In milliseconds. If the processing takes longer than the parameter determination, the request is ended and returns status-code 500, but with no body.
Maximum Request Size: maximum size of the payload (in MB). The maximum size of the configurable payload is 5MB. If the payload sent by the endpoint consumer goes beyond the limit, a message will be returned informing that the maximum size has been overcome and a status-code 413 with the following message:
{
"message": "Request size limit exceeded"
}
Response Headers: headers to be returned by the endpoint when processing in the pipeline is complete. This parameter cannot be left empty and accepts Double Braces. Special characters should not be used in keys, due to possible failures in proxies and gateways.
Add Cross-Origin Resource Sharing (CORS) - CORS Headers: add the CORS headers to be returned by the endpoint when processing in the pipeline is complete. Cross-Origin Resource Sharing (CORS) is a mechanism that lets you tell the browser which origins are allowed to make requests. This parameter defines CORS specifically for the pipeline and its constraints. To configure globally rather than individually on each pipeline see the CORS Global article.
Important: I used a comma to inform multiple values in a header, but I didn'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.
External API: if the option is enabled, the API is published in an external gateway.
Internal API: if the option is enabled, the API is published in an internal gateway. In this case, the internal API is accessible only through the dedicated VPN or the Pipeline Executor. The pipeline can have both the External API and Internal API options simultaneously enabled.
mTLS enabled API: se a opção estiver ativada, a API é publicada em um gateway dedicado a APIs com mTLS ativo por padrão. Nesse caso, o host de acesso será diferente dos demais. O pipeline pode ter tanto a opção de External API quanto a Internal API habilitadas simultaneamente, mas é recomendado deixá-las inativas. Este parâmetro não suporta API Key e JWT. Para utilizá-lo no seu realm, é necessário fazer uma solicitação via chat e assim enviremos as informações necessárias para instalação deste serviço.
API Key: if the option is enabled, the endpoint can be consumed only if an API key is previously configured in the Platform. There’s a global configuration parameter that obliges all the pipelines to be published only with the API Key option enabled. The only way to disable this parameter is by making a request via chat. It can be disabled in 2 ways: for one pipeline only, and you must send its name, or globally, which will disable the parameter for all the pipelines of your Realm.
Token JWT: if the option is enabled, the endpoint can be consumed only if a JWT token previously generated by another endpoint with this capacity is sent. Read the article about JWT implementation to have more details.
Additional API Routes: if the option is enabled, the trigger allows you to configure new routes. See more about this parameter below.
Routes: displayed only when the Additional API Routes parameter is enabled. Here you can define the endpoint additional routes.
Allow Redelivery Of Messages: if the option is enabled, it allows the message to be resend if the Pipeline Engine fails. Read the article about Pipeline Engine to have more details.
Additional API Routes
As previously explained, this option is to configure new routes in the endpoint.
When a pipeline is deployed, an URL is automatically created. However, you can customize the route according to your convenience. It also includes receiving parameters through the route.
Once the pipelines are deployed, the URLs take on the following structure:
or
{realm}: corresponds to realm
v{n}: versão principal (major) do pipeline
{pipeline-name}: nome dado ao pipeline
Customized static route
Let's assume you created the product-list pipeline. Taking into account the comment above, your URL would look like this:
https://test.godigibee.io/pipeline/realm/v1/product-list
Now, see how to configure a static route for this case.
With these applied configurations and the deployed pipeline, you get a new URL:
https://test.godigibee.io/pipeline/realm/v1/products
Custom route with parameter in the path
Using as example the same pipeline previously configured, see how to configure the route:
With these applied configurations and the deployed pipeline, you get a new URL:
https://test.godigibee.io/pipeline/realm/v1/products/:id
In this case, the endpoint consumer can send a request with the id of a product and return information about it only. Example of URL in the request:
https://test.godigibee.io/pipeline/realm/v1/products/10156
To use this value sent by the route inside the pipeline, go for the Double Braces syntax:
{{ message.queryAndPath.id }}
REST Trigger in Action
See below how the trigger behaves in specific situations and what its respective configuration is.
Query API of information with response in JSON
See how to configure a pipeline with REST Trigger to return information inside the pipeline in JSON format and how the return must be treated specifically for this trigger.
First of all, create a new pipeline and configure the trigger. The configuration can be made in the following way:
With the configurations above, you determine that:
the endpoint works with the verb GET only.
Besides, you determine that the API is external and doesn’t need a token for the communication.
IMPORTANT: this example works for educational matters only. In some cases you can’t let the endpoint open for security reasons.
Now see how to configure a MOCK in the pipeline so it becomes the data provider that the endpoint returns in the end. Place the indicated component, connect it to the trigger and configure it with the following JSON:
{
"data": {
"products": [
{
"name": "Samsung 4k Q60T 55",
"price": 3278.99
},
{
"name": "Samsung galaxy S20 128GB",
"price": 3698.99
}
]
}
}
After doing that, the endpoint will already automatically return the JSON defined above as the endpoint response.
After the deployment, take the generated url and send a GET-type request. The endpoint must return the status-code 200 and the response body must have the same appearance of the JSON we previously defined inside the MOCK component.
Dispatch API of information with response in JSON
See how to configure a pipeline with REST Trigger to return information inside the pipeline in JSON format and how the return must be treated specifically for this trigger.
First of all, create a new pipeline and configure the trigger. The configuration can be made in the following way:
With the configurations above, you determine that:
the endpoint works with the verb POST only.
Besides, you determine that the API is external and doesn’t need a token for the communication.
IMPORTANT: this example works for educational matters only. In some cases you can’t let the endpoint open for security reasons.
Now see how to configure a MOCK in the pipeline so it changes the received data and the endpoint will return in the end. Place the indicated component, connect it to the trigger and configure it with the following JSON:
{
"data": {
"products": [
{
"name": "Samsung 4k Q60T 55",
"price": 3278.99
},
{
"name": "Samsung galaxy S20 128GB",
"price": 3698.99
},
{{ message.body.product }}
]
}
}
With this configuration, a payload with a new product will be received and it will be added to the array. After that, the pipeline will return the array with the new added product to the consumer.
After the deployment, take the generated url and send a POST-type request with the following body:
{
"product": {
"name": "Samsung galaxy note 10 256GB",
"price": 2879.99
}
}
The endpoint must return the status-code 200 and the response body must have the following appearance:
{
"data": {
"products": [
{
"name": "Samsung 4k Q60T 55",
"price": 3278.99
},
{
"name": "Samsung galaxy S20 128GB",
"price": 3698.99
},
{
"name": "Samsung galaxy note 10 256GB",
"price": 2879.99
}
]
}
}
Everytime you make a request to the created endpoint, the structure of the message that the trigger delivers to the pipeline is always the same and follows this pattern:
{
"body": "{}",
"form": {},
"headers": {
"Host": "pipeline-trigger-http:8100",
"Connection": "keep-alive",
"X-Forwarded-For": "***",
"X-Forwarded-Proto": "http",
"X-Forwarded-Host": "***",
"my-custom-header": "a"
},
"queryAndPath": {
"id": "1"
},
"method": "POST",
"contentType": "application/json",
"path": "/pipeline/digibee/v1/trigger-rest/1"
}
body: content to be sent in the request payload to be transformed into 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 are automatically filled according to 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.