HTTP module

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

Requests and responses

Request headers

All the functions in the HTTP module provide the option to specify request headers. The request headers are specified as records. If you do not want to specify any request headers, you can use an empty record {}.

// Example 1: Make an HTTP request with no headers
return HTTP.getText("https://www.novacura.com", { });

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

Response status code

The responses from the functions in the HTTP module contain an HTTP status code indicating whether the request was successful. Generally, status codes between 200 and 299 are considered successful. It is the responsibility of the Flow developer to check the status code of each response from the HTTP module.

The reasonPhrase member of the responses contain a textual description of the status code.

// Example: check whether an HTTP response indicates success.
// In this example, we request a page which does not exist.

let response = HTTP.getText("https://www.novacura.com/does_not_exist.html", { });
if response.statusCode >= 200 and response.statusCode <= 299:
    return "OK";
else:
    error "The request failed with status code "
          & response.statusCode
          & " "
          & response.reasonPhrase;

// Example: create a utility function "ensureSuccess" which raises
// an error if a response is unsuccessful and returns the contents otherwise.

function isSuccess(response: { statusCode: number }) =>
    response.statusCode >= 200 and response.statusCode <= 299;

function ensureSuccess<T>(self response: { statusCode: number, reasonPhrase: text, contents: T }) : T {
    return case when isSuccess(response)
                then response.contents
                else error "The request failed with status code " & response.statusCode & " " & response.reasonPhrase
                end;
}

// Make a request for a nonexistent page.
return HTTP.getText("https://www.novacura.com/does_not_exist.html", { })
           .ensureSuccess();

Response headers

The responses from the functions in the HTTP module also contain response headers. 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.getText("https://www.google.com", {});
let cookie = null;

// 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;

HTTP module functions

getText

Signature: (url: text, headers: { }) -> HTTPResponse<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: { }) -> HTTPResponse<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) -> HTTPResponse<text>

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) -> HTTPResponse<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) -> HTTPResponse<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) -> HTTPResponse<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) -> HTTPResponse<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) -> HTTPResponse<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: { }) -> HTTPResponseNoBody

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: { }) -> HTTPResponseNoBody

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.