HTTP

Table of contents

The HTTP API allows scripts to send HTTP requests to web services, enabling integration between Memento Database and external systems. All HTTP operations are performed through the Http object, which is accessed via the global http() function.

HTTP requests must be executed asynchronously in the last Phase of an Event

The library must have the “Network” permission enabled

Global functions

http()

Global function that returns an Http object for making HTTP requests.

Returns

A new Http object instance for making HTTP requests

Example 

var httpClient = http();
log("Created new HTTP client");

Http Object

The Http object provides methods for making HTTP requests and managing request headers. It is obtained through the global http() function.

get(url)

Executes an HTTP GET request to the specified URL.

Parameters

Parameter Type Description
url String The complete URL starting with http:// or https://

Returns

Type Description
HttpResult Object containing the response from the HTTP request

Example 

var result = http().get("http://api.fixer.io/latest?base=USD");
log("Response code: " + result.code);
log("Response body: " + result.body);

download(url, headers)

Downloads a file with an HTTP GET request. The response body is streamed directly to a temporary file without converting its bytes to text or loading the entire file into memory.

Parameters

Parameter Type Description
url String The complete URL starting with http:// or https://
headers Object Optional header names and string values for this request. May be omitted or null.

Headers configured with headers(info) on the same Http object are used as defaults. Headers passed to download override those defaults case-insensitively for this request without changing subsequent requests. The timeout configured with timeout(millis) also applies to downloads.

Returns

Type Description
HttpResult Response with code, response headers, and a File object in file. The body property is null.

HTTP error responses, such as 404 or 500, also return their body as a file. Check code before using the downloaded file. An empty response body produces an empty file. Network or file I/O errors throw an error and remove the incomplete download.

In the Android app, each download is stored in its own subdirectory of the application’s temporary storage. Its initial name is download.tmp; the server’s filename and extension are not retained. Use rename(newName) to give it a meaningful filename. Separate downloads can be renamed to the same name because they are in different directories.

Downloaded files are temporary. To keep one as an attachment, pass the File object to Entry.set(name, value), which copies it into the library’s file storage. Calling file.close() does not delete the temporary file.

Downloading requires the “Network” permission. Reading the File object or copying it into a library requires file read permission; renaming it requires file write permission.

Example 

var result = http().download("https://example.com/report.pdf", {
    "Authorization": "Bearer " + token
});
if (result.code >= 200 && result.code < 300) {
    entry().set("Document", result.file.rename("report.pdf"));
} else {
    log("Download failed with HTTP status: " + result.code);
}

post(url, body)

Executes an HTTP POST request to the specified URL with the given body content. PATCH and PUT requests are also supported through patch(…) and put(…) using the same parameter structure.

Parameters

Parameter Type Description
url String The complete URL starting with http:// or https://
body String The content to send in the POST request body

Returns

Type Description
HttpResult Object containing the response from the HTTP request

Example 

var result = http().post("http://httpbin.org/post", "Hello World");
log("POST response code: " + result.code);

del(url)

Executes an HTTP DELETE request to the specified URL.

Parameters

Parameter Type Description
url String The complete URL starting with http:// or https://

Returns

Type Description
HttpResult Object containing the response from the HTTP request

Example 

// Delete a resource on the server
var result = http().del("http://httpbin.org/delete");
log("DELETE response code: " + result.code);

headers(info)

Sets HTTP headers for subsequent requests.

Parameters

Parameter Type Description
info Object Key-value pairs of header names and values

Returns

Type Description
Http The Http object (for method chaining)

Example 

var httpClient = http();
httpClient.headers({"User-Agent": "Memento Script", "Accept": "application/json"});
var result = httpClient.get("http://httpbin.org/get");
log("Request with custom headers completed: " + result.code);

HttpResult Object

The HttpResult object contains the response from an HTTP request.

Properties

Property Type Description
body String or null The response body as text; null for download()
file File or null The downloaded File object for download(); null for other HTTP methods
code Number The HTTP status code of the response (e.g., 200 for success)

header(tag)

Retrieves a specific header from the response.

Parameters

Parameter Type Description
tag String The name of the header to retrieve

Returns

Type Description
String The value of the specified header

Example 

var result = http().get("http://httpbin.org/get");
var etag = result.header("etag");
log("Response ETag: " + etag);

Examples 

// Get current exchange rate from API
var result = http().get("https://data.fixer.io/api/latest?access_key=[API Key]");

// Parse the JSON response
var usdToEur = JSON.parse(result.body)["rates"]["EUR"];
log("Current USD to EUR rate: " + usdToEur);

// Update entry with converted price
var usdPrice = entry().field("PriceUSD");
var eurPrice = usdPrice * usdToEur;
entry().set("PriceEUR", eurPrice);
log("Converted " + usdPrice + " USD to " + eurPrice + " EUR");