HTTP Request Data Operation HTTP Request Data Operation

HTTP Request Data Operation

Elliot Fiske Elliot Fiske

Overview

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.

http-request.gif

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

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.

Content-Type

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".

Some requests don't have an HTTP body. For those requests, the content-type doesn't matter.

Body

The HTTP Body of the request. This field does not appear if the Method is GET.

Headers

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

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 button 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.

Note: 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

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 + button and specify a Field Name and a Value.

Note: 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. For a full explanation of Has Paging and the related parameters, read Using an API With Paging.

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.

Further Reading

For a deeper understanding of subjects like HTTP Methods, Form Parameters, and Headers, the Mozilla website has the most up-to-date documentation and information. Interested readers can start with Sending and Retrieving Form Data, which talks about several of the concepts mentioned above.

The result of the HTTP request is often parsed using The Transform Data Operation.