On this page:

20.7HTTP API

 

The Http object allows scripts to call external HTTP services and process the results. The basic flow for invoking an HTTP request is to create the request, then to execute the request, and then to process the results.

A basic example is shown below:

var get = Http.get('https://example.com/somepath');
get.addRequestHeader('Authorization', 'Basic YWRtaW46cGFzc3dvcmQ=');
get.execute();
if (!get.isSuccess()) {
   throw get.getFailureMessage();
}
var responseJson = get.parseResponseAsJson();
var username = responseJson.username;
var password = responseJson.password;

20.7.1Request Creation Methods

 

Methods: get(string), post(string), put(string), head(string), delete(string)

The HTTP verb methods may be used to create an HTTP request for a given URL.

var get = Http.get('https://example.com/somepath');
var post = Http.post('https://example.com/somepath');
var put = Http.put('https://example.com/somepath');
var head = Http.head('https://example.com/somepath');
var delete = Http.delete('https://example.com/somepath');

Methods: setContentType(string), setContentString(string)

The HTTP post and put verbs typically have a Content-Type header and a request body. The simplest way to provide a request body is to simply set a Content-Type via the setContentType(string) method, and a request body via the setContentString(string) method.

var post = Http.post('https://example.com/somepath');
post.setContentType('text/plain');
post.setContentString('this is the body');

Method: setContentJson(object)

The setContentJson method takes a JavaScript Object as input, and creates a request body using the resulting serialized JSON. The request content type is also automatically set to application/json.

var post = Http.post('https://example.com/somepath');

// Create a JSON object
var json = new Object();
json.username = 'someuser';
json.scopes = new Array();
json.scopes[0] = 'foo';
json.scopes[1] = 'bar';

// Use the JSON as the request body
post.setContentJson(json);

20.7.2Request Execution Methods

 

Method: execute()

Calling execute() actually causes the HTTP operation to be invoked. Details about the response are then available via methods on the same request object.

20.7.3Response Processing Methods

 

Method: isSuccess()

This method returns true if the request succeeded, meaning that the connection succeeded and the response contained an HTTP Status Code < 400.

Method: getStatusCode()

This method returns the HTTP Status code for the request.

Method: getFailureMessage()

If the request was not successful (as determined by the response to isSuccess(), this method will return a string indicating the reason for the failure.

Method: getResponseString()

This method returns the body of the response as a string.

Method: parseResponseAsJson()

This method returns the body of the response, parsed as a JSON object.

// Parse the response as JSON
var responseJson = get.parseResponseAsJson();

// Log the JSON for troubleshooting
Log.info(JSON.stringify(responseJson));

// Extract values from the JSON
var cats = responseJson.cats;
var docs = responseJson.dogs;