The example below shows the development team creation using the REST API component with our own REST API service.
Numbers show: (1) The URL and method of the REST API resource, (2) the HTTP call headers, (3) configuration options (4) follow redirect mode, (5) delay, (6) call count and (7) request timeout.
1. HTTP methods and URL
GET
, PUT
, POST
, DELETE
and PATCH
.2. Request Headers and Body
3. Configuration options
Don`t throw Error on Failed Calls
- if enabled return error, error code and stacktrace in message body otherwise throw error in flow.Split Result if it is an Array
- if enabled and response is array, creates message for each item of array. Otherwise create one message with response array.Retry on failure
- enabling rebound feature for following HTTP status codes:
Do not verify SSL certificate (unsafe)
- disable verifying the server certificate - unsafe.4. Follow redirect mode
- If you want to disable Follow Redirect functionality, you can use option Follow redirect mode
.By default Follow redirect mode
option has value Follow redirects
.
5. Delay
- If you want to slow down requests to your API, you can set delay value (in seconds) and the component will delay calling the next request after the previous request.
Time for the delay is calculated as Delay
/ Call Count
and shouldn’t be more than 1140 seconds (19 minutes due to platform limitation).
The Call Count
value by default is 1. If you want to use another value, please set the Call Count
field.
Notice: See Known Limitations about
Delay
value.
6. Call Count
- the field should be used only in pair with Delay
, default to 1.
7. Request timeout
- Timeout period in milliseconds (1-1140000) while component is waiting for server response. This can also be configured with REQUEST_TIMEOUT environment variable if configuration field is not provided. Defaults to 100000 (100 sec).
Notice: Specified for component REQUEST_TIMEOUT environment variable would be overwritten by specified value of Request timeout, default value would be also overwritten.
To use the REST API component with any restricted access API, you need provide the authorization information.
Example above shows how to add the username/password to access the API during the integration flow design.
You can add the authorization methods during the integration flow design or by going to the left side-bar, choosing Credentials > REST API V2
and adding there.
Example above shows how to add new credential to access the API from Credentials page.
REST API component supports 4 authorisation types:
No Auth
- use this method to work with any open REST APIBasic Auth
- use it to provide login credentials like username/passwordAPI Key Auth
- use it to provide API Key
to access the resourceOAuth2
- use it to provide Oauth2
credentials to access the resource. Currently it is implemented Authorization code
OAuth2 flow.To create OAuth2
credential you have to choose Auth-client or create the new one. It must contains Name
, Client ID
, Client Secret
, Authorization Endpoint
and Token Endpoint
. For more information please check the documentation of the API you want to connect to.
Example above shows how to add new Auth-client to access the API.
Here you can see how to select an existing client
:
Please note that the result of creating a credential is an HTTP header automatically placed for you. You can also specify the authorisation in the headers section directly.
NAME | DESCRIPTION | DEFAULT | OPTIONAL |
---|---|---|---|
REQUEST_TIMEOUT | HTTP authorization request timeout in milliseconds. | 10000 | true |
REQUEST_RETRY_DELAY | Delay between authorization retry attempts in milliseconds | 5000 | true |
REQUEST_MAX_RETRY | Number of HTTP authorization request retry attempts. | 3 | true |
In a REST API component the trigger and action perform the same function - HTTP request witch will send a GET
/POST
/PUT
/PATCH
/DELETE
requests and parse the response back to the flow.
The messages produced by the REST API component will have the following properties:
headers
: Object containing the HTTP response headersstatusCode
: HTTP Status Code of the Response. Number between 100
and 599
statusMessage
: Human readable equivalent to the response codebody
: The contents of the HTTP response body:
json
, then the result will be parsed into the corresponding objectxml
, then the result will be converted into the JSON equivalent of the represented XML using the same rules as aboveimage
, msword
, msexcel
, pdf
, csv
, octet-stream
or binary
the request body contents will be stored as an attachment and there will be no body
property in the outgoing messagebody
property in the outbound message.For more details you can see the usage example.
If the HTTP method is any other but GET
, you will see a Body tab appear next to the Header tab. The Body tab enables
configuration options such as the content type drop-down menu and the body input field.
Here is the list of all supported content types:
multipart/form-data
application/x-www-form-urlencoded
text/plain
application/json
application/xml
text/xml
text/html
The body input field changes according to the chosen content type.
Notes:
- Response body will be stored in
msg.body
- Request body that causes empty response body will return
{}
Here is how to send a JSON data in the body. Change the content type to
application/json
and the body input part would change accordingly to accept
JSON object. Please note that this field supports JSONata expressions.
Example shows the JSON in the body where the name
parameter value gets mapped using the value of project_name
from the previous step of integration.
To send an XML
data, set the content type to application/xml
or text/xml
and place the XML
in the body input field between double-quotes like:
"
<note>
<to>" & fname & "</to>
<from>Jani</from>
<heading>Reminder</heading>
<body>Don't forget me this weekend!</body>
</note>
"
Use a JSONata expression to include and map any values coming from the previous steps. It will replace the variable with a real value in the final mapping. Note that the rest of XML
gets passed as a string
.
To send a form data, two content types are available:
application/x-www-form-urlencoded
- used to submit simple values to a formmultipart/form-data
- used to submit (non-alphanumeric) data or file attachment in payloadIn both cases the payload gets transmitted in the message body.
In case of application/x-www-form-urlencoded
content type, add the necessary parameters by giving the name and the values like:
Please note: the parameter value fields support JSONata expressions.*
This HTTP request would submit key1=value1&key2=value2
in the message body.
In case of multipart/form-data
content type, add the parameters similarly.
The transmitted HTTP request body would be:
--__X_BOUNDARY__
Content-Disposition: form-data; name="part1"
Please note that this fields supports [JSONata](http://jsonata.org) expressions.
--__X_BOUNDARY__
Content-Disposition: form-data; name="part2"
<p>Some more text</p>
--__X_BOUNDARY__--
Notice how different parts get separated by the boundary. This form is capable of supporting attachments as well.
This component will try to parse XML content types in the HTTP Response assuming the Content-Type
header has a
MIME Content Type with xml
in it (e.g. application/xml
).
In this case response body will be parsed to JSON using xml2js
node library and following settings:
{
trim: false,
normalize: false,
explicitArray: false,
normalizeTags: false,
attrkey: '_attr',
tagNameProcessors: [
(name) => name.replace(':', '-')
]
}
for more information please see the Documenattion of XML2JS library
You can get HTTP response header only if Don`t throw Error on Failed Calls
option is checked.
In this case output structure of component will be:
{
headers:<HTTP headers>,
body:<HTTP response body>,
statusCode:<HTTP response status code>
statusMessage:<HTTP response status message>
}
Use this section to add the request headers.
Each header has a name and a value. Header name should be colon-separated
name-value pairs in clear-text string
format. The header value can use
JSONata expressions.
Please note: HTTP Response headers will not be stored, the components stores body and attachment only.
Sometimes it’s required to read and set cookies. To read cookies you should have gain access to the Set-Cookie
headers of the HTTP Response,
in this case you should check the Don`t throw Error on Failed Calls
option. Please note that HTTP Response may have multiple
Set-Cookie
headers therefore you should expect to find an array of values in the HTTP Response
To set Cookies you could simply use the HTTP header on your Response called Cookie
to a cookie value to a
list of name-value pairs in the form of
With the REST API component, you can send binary data as attachment. You just need to choose
multipart/form-data
Content type and attachments from the input message will be
included to the request payload automatically.
REST API component automatically load binary data to attachments with next content types in response headers:
image/*
text/csv
application/msword
application/msexcgel
application/pdf
application/octet-stream
application/x-binary
application/binary
application/macbinary
Rest API component uses exception handling logic below:
1. The component can parse any of json and xml content types. They are:
Please note: if content type is not indicated in response header, component will try to parse response as json. If it gets parse exception, it returns response as is.
2. Attachments limitations:
Maximal possible size for an attachment is 10 MB.
Attachments mechanism does not work with Local Agent Installation
3. OAuth2 authentication strategy limitation: Access Token Response should always contain refresh_token
property (optional in OAuth2 standard). Reason behind it - platform shoud be able to refresh access token after it’s expiration. Possible solution - use access_type:offline
in additional parameter which is supported by many OAuth2 providers.
4. We suggest not to set Delay value more than time period between two executions of the flow. Please keep in mind that delay can influence the time of next execution. For example, the flow has type Ordinary
and scheduled for execution for every 60 sec, but the delay is set to 120 sec, so the next execution will be started only after 120 sec, instead of 60 seconds.
Get your free 14-day elastic.io trial account to use this component.