The HTTP Request Data Operation makes a web request to an external API. It has many uses, including sending and receiving data from external sources.
If there are external integrations set up as described in Querying and Manipulating Data From External Systems, the HTTP Request Data Operation can automatically handle authentication.
Make sure the URL in your requests points at port 80 for HTTP requests and a port 443 for HTTPS requests. Other ports are not supported.
Use Cases
- Connect to any public facing REST or SOAP API
- Remit data to key systems of record
Data Operation Properties
Service
If there are Integrations added to the App, as described in Connecting to External Systems, they will be listed here. If a Service is chosen, the request will automatically authenticate. For instance, if the Resource uses OAuth authentication, the Data Operation will automatically handle requesting a token and setting the Authorization headers.
Method
The HTTP Method that this request will use. The method the HTTP request should use will be specified by the API documentation.
URL
Expects type text.
The URL that this HTTP request will access. This can be any Airscript expression, including simple static Text, a Text Format, or any function that returns a String.
If 'https://' is used, the request will be a SSL connection and if not encrypted, the request will fail. For more information see SSL.
Allow non-compliant HTTP headers
Allow interoperability with non-conformant HTTP implementations by accepting invalid HTTP headers. Using this should be avoided if possible.
Content-Type
Expects type text.
This describes what format the HTTP Body will have. For instance, a POST request to a REST API should use "application/json", and a POST request to a SOAP API should use "application/soap+xml".
Body
Expects type any.
The HTTP Body of the request. This field does not appear if the Method is GET.
Sending Airkit Assets
HTTP Request bodies can be file contents (asset) as well. If you specify an asset URI as the request body, it sends the contents of this asset as the body.
Headers
Expects type text.
HTTP Headers allow the HTTP request to specify additional information about its request. To add an HTTP header, press the + button and specify a Field Name and a Value.
For instance, an HTTP request can specify a Field Name of Accept-Language and a Value of es to ask that the server respond with user-readable text in Spanish if possible.
Query Parameters
Expects type text.
An HTTP request can specify query parameters as another way to send information to the API. The query parameters you can use will be available in the API's documentation.
To add a query parameter, press the + icon and specify a Field Name and a Value. For instance, to specify that only up to 10 events should be returned from a query to the Google Calendar API, the Field Name maxResults should be set to the Value 10.
Query parameters can also be specified in the URL. For instance, using the URL example.com/search?text=blue would be the same as specifying example.com/search with a query parameter whose Field Name is Text and whose Value is
blue. It is usually more convenient to have each parameter listed in the Query Parameters section, but either option will work.
Form Parameters
Expects type text.
If the external API expects to receive data via Form Parameters, the content-type "application/x-www-form-urlencoded" should be used. To add a form parameter, press the + icon and specify a Field Name and a Value.
If a Body is specified, the Form Parameters will be ignored.
Has Paging?
This box should be checked if the API endpoint supports paging. With paging, an API will break up a response into multiple pages if the response is too large.
Response Type
By default, Variable of type Any.
Certification Authority, Client Side Private Key, and Client Side Certificate
These fields are used to set up mutual SSL authentication between Airkit (the client) and an external server. For more on how that is configured, see SSL Auth.
When the Certification Authority, client-side private key, and client-side certificate are hardcoded as part of an HTTP Request Data Operation, they are necessarily stored as plaintext. To store their values in an encrypted database, as is commonly best practice for security purposes, you will need to configure them as a Console-level integration, though it is also possible to pull relevant values from another external system as part of the Data Flow and then use variables to configure the Certification Authority.
Run Results
When an HTTP Request Data Operation is created, 3 Variables are automatically created to capture its output.
These Variables appear in the Inspector on the right, and can be renamed to make them more descriptive of the HTTP request they belong to.
result: The result of the HTTP request, parsed into an Airscript object if possible.
rawResult: The full headers, HTTP response code and raw body of the completed HTTP request. Note that rawResult.body is the same value as the result variable above.
request: The original request. This contains the URL, HTTP Method, and all the other information described above. This Variable will contain all the information necessary to make the same request again.