Make an HTTP request

4 min read

The HTTP protocol is the cornerstone of all APIs. A REST API call is an HTTP request. You can execute such requests with the HTTP request block. It will provide the response in its output. However, you have to validate the response to effectively use the body. The result of the HTTP request has the property "body" that isn't typed. After validating, this data is typed, and all its properties can be used in the mapping.

The input for HTTP requests has the following properties:

  • method is the HTTP method and defaults to "GET".
  • url is required and needs to have the "http" or "https" protocol.
  • headers may contain an object with HTTP request headers. You can use this to provide authentication, for example. The Content-Type header is automatically set when using body to post JSON or when using form. However, you may still override its value by providing it to headers.
  • body contains the requested body. Objects are automatically posted as JSON. There is no need to set the Content-Type header in this case manually. For posting other types, you set the body to a string and provide the correct Content-Type header.
  • json can be set to an object to post form data. The Content-Type header is automatically set to "application/x-www-form-urlencoded" when providing values to form. This data format is used when posting an HTML form but is also common in APIs. Examples are Google ReCaptcha and Paddle payments API.
  • query is an object with GET parameters. These items will be appended to the URL after the question mark. For example {"page":1} will be added as ?page=1. Note that it is also possible to provide parameters in the URL. Both will be used, so when the URL is http://example.com/?q=test, the requested URL becomes http://example.com/?q=test&page=1.
  • responseFormat is used to define if and how the response body needs to be parsed. Options are "auto", "json", "text", and "binary". This choice is made automatically based on the HTTP response headers when using "auto", which is the default setting. When using "binary", the response comes back as a base64 encoded string.
  • secret provides authorization. Read the section below to learn about its usage.

In many situations, you'll use a JSON response body. However, if the response is {"name":"John"}, for example, you cannot use "name" directly. In the mapping, the body has no type yet. We can solve that by validating the response using a Validate block as seen in the flow below.

Validate after HTTP request in flow

You must provide a schema to validate against. Click on the settings icon on the validate block, and choose "Edit schema". This dialog contains a link "Generate or import". It is often easiest to generate the schema from a JSON example, which is usually given in the API documentation of the target API. Alternatively, you can execute the flow by using the "Test flow" button in the top-right corner and then use the debug button on the block to get the returned JSON.

Secrets

The secrets input provides a convenient way to authenticate the request. Its value refers to a secret defined in the workspace settings. Supported types are password, Basic Auth, HTTP headers, and OAuth2.

When using a password, the following HTTP header is used:

Authorization: Bearer PASSWORD

This form is a common practice for adding authorization tokens. An identical header is used for OAuth2, but with a dynamic token instead of a fixed password.

Only one secret can be used simultaneously due to the nature of the HTTP authorization. Also, you cannot set a custom authorization header via the headers input while also using a secret.