HTTP 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;
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');
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');
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);
Calling execute() actually causes the HTTP operation to be invoked. Details about the response are then available via methods on the same request object.
This method returns true if the request succeeded, meaning that the connection succeeded and the response contained an HTTP Status Code < 400.
This method returns the HTTP Status code for the request.
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.
This method returns the body of the response as a string.
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;
HTTPS URLs are automatically supported by the HTTP API. If there is a requirement to connect to a service that uses features of HTTP beyond the basics however, it may be necessary to add extra configuration.
If a server is using a self-signed certificate, or a certificate signed by an unknown authority, the certificate can be manually added to the request via the JavaScript API.
Certificates and KeyStores that will be used by the JavaScript API must be placed directly in the following directory:
[smilecdr]/classes/client_certificates
For security reasons, the JavaScript API is not able to access any certificate/keystore files that are not located directly in this directory.
KeyStore files containing trusted certificates can be stored in either PKCS#12 format or in Java KeyStore format.
The following snippet shows the use of a keystore:
var get = Http.get('https://localhost:61500/someUri');
get.getTlsOptions().trustStore('my-keystore.p12');
get.getTlsOptions().trustStorePassword('changeit');
get.execute();
Certificate files can be in PEM or DER format. These formats also commonly use the .cer extension.
The following snippet shows the use of a certificate:
var get = Http.get('https://localhost:61500/someUri');
get.getTlsOptions().trustCertificate('my-certificate.pem');
get.execute();
If a self-signed certificate is used without a Subject Alternative Name (i.e. a domain/host name that the keypair is specifically signed to secure), you may need to disable host name verification. Note that this comes with its own security risks and should be carefully considered. This problem often manifests itself via an error such as the following:
Certificate for <localhost> doesn't match any of the subject
The following snippet shows how to disable host name verification:
var get = Http.get('https://localhost:61500/someUri');
get.getTlsOptions().trustStore('my-keystore.p12');
get.getTlsOptions().trustStorePassword('changeit');
get.getTlsOptions().disableHostVerification();
get.execute();
To enable TLS Mutual Authentication (also called TLS Client Authentication), a KeyStore containing a private key must be suppplied. Like the certificates and keystores mentioned above, this keystore should also be placed directly in the following directory:
[smilecdr]/classes/client_certificates
The following snippet shows a complete example enabling TLS mutual authentication using a truststore containing the server certificate and a keystore containing the client private key:
var get = Http.get('https://localhost:61500/someUri');
get.getTlsOptions().trustStore('my-truststore.p12');
get.getTlsOptions().trustStorePassword('changeit');
get.getTlsOptions().disableHostVerification();
get.getTlsOptions().keyStore('my-keystore.p12');
get.getTlsOptions().keyStorePassword('changeit');
get.getTlsOptions().keyStoreKeyPassword('changeit');
get.execute();
TLS details are logged in the HTTP Troubleshooting Log, so some issues may be diagnosed by enabling this log.