Http.Request

Http.Request is a value type that encapsulates the data sent during a HTTP request.

Although a request is often just a simple URL, it can also include additional parameters, HTTP headers, and content data to transmit to the remote server.

When interacting with web APIs it is common for all requests made to a server to have mandatory fields or headers, to identify your application or login. To simplify your application, you can preconfigure a Http.Request instance with these parameters and then specialize a a new copy of it for each request. For example:

Object {
    // HttpRequest pre-configured with url, X-API-Key field etc.
    property Http.Request authorizedRequest

    function makeRequest() {
        Http.Request myRequest = authorizedRequest
        myRequest.setParameter("query", "users")
        // ...
        http.get(myRequest)
    }
}

To actually issue a HTTP request, use the Http element.

function Http.Request(Url url) → Http.Request

Creates a Http.Request object for the url.

property Url url

The request URL.

property Bool allowRedirects

When enabled, requests will transparently follow redirects returned by the remote server. Otherwise, the returned Http.Response will contain a 30x status code and you can manually decide whether or not to resubmit the request to the new location.

Any HTTP headers returned by the server - including cookies - from an intermediate request are discarded. If you need these headers, you must handle redirects manually.

Redirects are allowed by default.

function parameter(String name) → String

function setParameter(String name, String value)

Get and set request parameters.

In the case of a GET request, the parameters will be percent-encoded and included as the URL query string. If the request URL contained a query string, the request parameters will replace it.

For a POST request, they will be included as the request body, with a "application/x-www-form-urlencoded" content-type.

property String contentread only

property String contentTyperead only

The content and content-type to be sent with a POST request.

Both properties will return empty strings unless content has been set with the setContent() method.

function setContent(Json json)

function setContent(String type, String content)

Sets custom content for a POST request.

By default, the request parameters are included as the POST content, encoded as "application/x-www-form-urlencoded" data. This matches the behavior of data submitted through a HTML form and is what most web servers expect.

You can explicitly control the raw POST content by providing both the content-type and the content data. This data will be sent as-is to the remote server.

req.setContent("text/plain", "username: bob, password: secret")

When interacting with HTTP APIs that communicate using JSON, you can provide a Json object to be used as the POST content. The JSON object will be stringified into a compact form, and the content type set automatically to "application/json".

var json = { username: "bob", password: "secret" }
req.setContent(json)

In both cases, the custom POST content overrides the request parameters.

function header(String name) → String

function setHeader(String name, String value)

Get and set request HTTP headers. HTTP header names are case-insensitive.

function cookie(String name) → String

function setCookie(String name, String value)

Get and set request cookies.