HTTP

mash.http · Network

Limited on SaaS

• On an appliance an administrator can allow hosts the network guard blocks (MASH_NETWORK_WHITELIST). SaaS has no such override.

mash.http makes web requests: fetch data from another system, post an order to it, call an API. Each call returns a response you can read the status, body and JSON from.

How it works

One call per verb. get, post, put, patch, delete, head and options each take a URL and a dictionary of options. getJson is a shortcut for a GET that asks for JSON and gives you the decoded data straight away, not a response.

A failed status is an error by default. A 404 or 500 raises an error and the script carries on to its next line, unless an error block catches it. Set http_errors: false to get the response back instead and decide for yourself. A 429 (too many requests) is retried up to three times, honouring the service’s Retry-After.

Only a short list of options is allowed. bearer, headers, query, json, body, form_params, multipart, auth, timeout, connect_timeout, read_timeout, http_errors, allow_redirects, decode_content, version and verify. Anything else, such as proxy, sink or cert, is refused with a “Security Block” error.

Internal addresses are blocked. A request to a private or reserved address (your own network, localhost, a cloud metadata address) is refused unless an administrator has allowed it. The check is made again on every redirect.

client makes a reusable client. mash.http.client({base_uri: "https://api.example.com", bearer: "..."}) returns a client with those options built in, which you call with relative paths. It also takes retry (0 to turn retries off, or {count: 5, status: [429, 503]}) and cookies.

Common tasks

Fetch and read JSON:

set response to mash.http.get("https://api.example.com/orders/1182", {bearer: "my-token", timeout: 30})
set order to response.json
printline "Order {{order['ref']}} is {{order['status']}}"

Send JSON, and survive a failure:

set response to mash.http.post("https://api.example.com/orders", {
    bearer: "my-token",
    json: {ref: "SO-20417", lines: [{sku: "A", qty: 2}]}
})
error
    printline "Couldn't send the order: {{mash.error.message}}"
    return
end
printline "Sent: {{response.status}}"

Look at the status yourself:

set response to mash.http.get("https://api.example.com/orders/1182", {http_errors: false})
if response.status is 404
    printline "No such order"
elseif response.status is more than or equal to 400
    printline "The service said {{response.status}}"
else
    printline response.body
end

Use one client for several calls:

set api to mash.http.client({base_uri: "https://api.example.com", bearer: "my-token", timeout: 20})
set a to api.get("orders/1")
set b to api.get("orders/2")

Watch out for

• Keep tokens out of the script text. Put them in the script’s config (see Reacting to events) and read them with mash.config.get.
• response.json is null when the body isn’t JSON. It doesn’t raise an error. Check it before you use it.
• Set a timeout. A slow service otherwise holds the script for as long as the platform allows.
• getJson gives data, not a response. There’s no status to check, and a failed status raises an error.
• Calls can repeat. If a script is run twice, a post runs twice. Make the other end ignore a repeat, or record that the script has already sent it.

See also

Talking to the outside world in the tutorial, mash.json, and the response type.

Library for making HTTP requests and processing responses

Methods

client

http.client(options?: array) → Client

Create a new HTTP client with custom options.

delete

http.delete(url: string, options?: array = []) → Response

Send a DELETE request.

get

http.get(url: string, options?: array = []) → Response

Send a GET request.

getJson

http.getJson(url: string, options?: array = []) → dictionary

Send a GET request and decode the JSON response. Returns the decoded JSON (a dictionary or a list), not a Response.

head

http.head(url: string, options?: array = []) → Response

Send a HEAD request.

options

http.options(url: string, options?: array = []) → Response

Send an OPTIONS request.

patch

http.patch(url: string, options?: array = []) → Response

Send a PATCH request.

post

http.post(url: string, options?: array = []) → Response

Send a POST request.

put

http.put(url: string, options?: array = []) → Response

Send a PUT request.