HTTP module

The HTTP module is used to make HTTP requests from Flow Connect applications.

Requests and responses

The primary way to make HTTP requests is using the request function.

Signature: (url: text, options: RequestOptions = {}) -> Response

// Get the HTML content from novacura.com as text
return HTTP.request("https://www.novacura.com").asText();

Request options

You customize an HTTP request by passing options in the options parameter of the request function.

method

To specify the HTTP method of an HTTP request, use the method option:

// Make a HEAD request and return the status code
return HTTP.request("https://www.novacura.com", { method: "HEAD" }).statusCode;

The method option accepts the values "GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS" and "HEAD". If the method option is left unspecified, a GET request will be made.

body

For methods which accept a request body (e.g. POST), you specify the request body using the body option. The body option accepts text, binary or MultiPartBody (see below).

// Make a POST request with a text body (serialized JSON)
let response = HTTP.request(
  'https://jsonplaceholder.typicode.com/posts',
  {
    method: 'POST',
    body: JSON.serialize({
      title: 'foo',
      body: 'bar',
      userId: 1,
    }),
    headers: {
       'Content-type': 'application/json; charset=UTF-8',
    },
});

return response.asText();

headers

To add headers to the request, use the headers option. The request headers are specified as a record.

// Make an HTTP request with an Accept header
return HTTP.request(
    "https://jsonplaceholder.typicode.com/todos/1",
    {
        headers: { "Accept" : "application/json" }
    })
    .asText();

continueOnError

By default, the request function raises an error if the status code of the response is not within the success (2XX) range. To change this behavior, you can set the continueOnError option to true.

// Fetch a non-existent URL, yielding a 404 status code
return HTTP.request(
    "https://www.novacura.com/nonexistent",
    {
        continueOnError: true
    })
    .statusCode;

Responses

The request function returns a record of the Response type, containing information about the response from the server. The response record also contains functions for reading the response body.

let response = HTTP.request("https://jsonplaceholder.typicode.com/todos/1");
return response.asText();

statusCode

The statusCode field contains the HTTP status code, as a number, indicating whether the request was successful. Note that if the request is made with continueOnError set to false (or left unspecified) the program will fail on non-success status codes rather than returning a response record.

reasonPhrase

The reasonPhrase field contains a textual description of the status code.

ok

The ok field contains a boolean value indicating whether the response status code indicates success. Note that if the request is made with continueOnError set to false (or left unspecified) the program will fail on non-success status codes rather than returning a response record.

headers

Contains response headers provided by the server. Unlike the request headers, the response headers are formatted as a sequence of key/value pairs where each entry may have more than one value.

// Example: extract a Cookie header from an HTTP response.

let response = HTTP.request("https://www.google.com");
let cookie = null;

do response.close();

// Look for a cookie in the response headers
let header = firstOrNull(response.headers where name = "Set-Cookie")
if header != null:
    cookie = first(header.values);

return cookie;

asText

The response record contains an asText function member which reads the response body as text. It is suitable for text-based formats like JSON, XML or CSV. You can only read the response body once. You cannot defer the reading of the response body to a subsequent step.

asBinary

The asBinary function member reads the response body as binary, suitable for data like images or PDF files.

close

The close function member is used to close the underlying socket connection if you do not intend to read the response body.

Multipart content

In order to create a body containing multi-part content, use the multipart helper function.

Signature: (subtype: text, ...contents: MultipartContent*) -> MultipartBody

return HTTP.request(
    "https://some.api.com/submit",
    {
        method: 'POST',
        body: HTTP.multipart(
            'mixed',
            { contentType: 'text/plain', content: 'Hello, Text!' },
            { contentType: 'application/json', content: '[1, 2]' }
        )
    }
).asText()

Legacy HTTP module functions

getText

Signature: (url: text, headers: { }) -> { statusCode: number, reasonPhrase: text, contents: text }

Makes an HTTP GET request with the specified URL and headers. The returned record contains the response data (if any) as a text value.

getBinary

Signature: (url: text, headers: { }) -> { statusCode: number, reasonPhrase: text, contents: binary }

Makes an HTTP GET request with the specified URL and headers. The returned record contains the response data (if any) as a binary value.

postText

Signature: (url: text, headers: { }, body: text) -> { statusCode: number, reasonPhrase: text, contents: binary }

Makes an HTTP POST request with the specified URL, headers and body. The body is taken in text format, and the returned record contains the response data (if any) as a text value. If no Content-Type header is specified, the Content-Type will be passed as text/plain.

postBinary

Signature:(url: text, headers: { }, body: binary) -> { statusCode: number, reasonPhrase: text, contents: binary }

Makes an HTTP POST request with the specified URL, headers and body. The body is taken in binary format, and the returned record contains the response data (if any) as a binary value. No Content-Type header is added automatically.

patchText

Signature: (url: text, headers: { }, body: text) -> { statusCode: number, reasonPhrase: text, contents: text }

Makes an HTTP PATCH request with the specified URL, headers and body. The body is taken in text format, and the returned record contains the response data (if any) as a text value. If no Content-Type header is specified, the Content-Type will be passed as text/plain.

patchBinary

Signature: (url: text, headers: { }, body: binary) -> { statusCode: number, reasonPhrase: text, contents: binary }

Makes an HTTP PATCH request with the specified URL, headers and body. The body is taken in binary format, and the returned record contains the response data (if any) as a binary value. No Content-Type header is added automatically.

putText

Signature: (url: text, headers: { }, body: text) -> { statusCode: number, reasonPhrase: text, contents: text }

Makes an HTTP PUT request with the specified URL, headers and body. The body is taken in text format, and the returned record contains the response data (if any) as a text value. If no Content-Type header is specified, the Content-Type will be passed as text/plain.

putBinary

Signature: (url: text, headers: { }, body: binary) -> { statusCode: number, reasonPhrase: text, contents: binary }

Makes an HTTP PUT request with the specified URL, headers and body. The body is taken in binary format, and the returned record contains the response data (if any) as a binary value. No Content-Type header is added automatically.

head

Signature: (url: text, headers: { }) -> { statusCode: number, reasonPhrase: text }

Makes an HTTP HEAD request with the specified URL and headers. The returned value has no contents, only status code, reason phrase and response headers.

delete

Signature: (url: text, headers: { }) -> { statusCode: number, reasonPhrase: text }

Makes an HTTP DELETE request with the specified URL and headers. The returned value has no contents, only status code, reason phrase and response headers.