HTTP client library for scripts

HttpClient

The HttpClient is available via the IClientScriptContext. You can get a default-configured (see below) builder for the client by calling getHttpClientBuilder() on the context, e.g. context.getHttpClientBuilder(). After calling the build()-method on the builder the client is ready to use.

Using the client

try (def client = context.getHttpClientBuilder().build()) { 
    def response = client.get("https://my-api-call.example")
    // process response
}

The client offers methods for every HTTP method (e.g. get, post) and allows to provide custom HTTP headers as the last method argument, if necessary. The response has the type HttpResponse and contains the status code, response headers and, if present, the response entity. The response entity (of type HttpEntity) contains the response content as a byte array, the mime type and the charset of the data. HttpEntity is also the required data type used for the request body of post, put and patch requests. Please read the JavaDoc for more details on how to use the client and the data types.

JSON API calls using the HttpClientRestWrapper

As most APIs nowadays are JSON/REST APIs, we provide an easier way to deal with JSON data to avoid parsing the byte arrays manually into custom data types. The HttpClientRestWrapper class can be used to wrap a HttpClient instance and make JSON API calls with it. Under the hood it uses a Jackson ObjectMapper to transform the data from/to JSON. If necessary, a custom ObjectMapper instance can be passed into the constructor, but the default mapper should suffice for most cases.

The following example shows how to make a simple API call.

class WeatherModel { 
    // ...
} 

try (def client = context.getHttpClientBuilder().build()) { 
    HttpClientRestWrapper restClient = new HttpClientRestWrapper(httpClient);
    // GET data
    WeatherModel weatherReport = restClient.get(WEATHER_API_URL, WeatherModel.class);
    // POST data; we pass null as the result type because we are not interested in the response
    WeatherModel desiredWeather = DefaultWeather.SUNNY_DAY;
    restClient.post(WEATHER_API_URL, desiredWeather, null);
}

Error handling

All exceptions in the client are thrown as HttpClientExceptions.

Configuration of the client and its default configuration

The HttpClient can be configured using the builder available from context.getHttpClientBuilder(). The following settings are configurable: userAgent, httpProxyHost, httpProxyPort, httpProxyUsername, httpProxyPassword, timeout, redirectsEnabled. While most of these settings are self-explained, the given userAgent allows to add a context specific part of the user agent, for example a script ID or sophora installation idenfier, but does not allow to change the entire user agent string.

All of these settings can have defaults which will be pre-configured for all scripts obtaining the builder via context.getHttpClientBuilder(). The default configuration settings can be made in the configuration document "Script HttpClient" with the externalId sophora.configuration.scriptsettings. The available keys are already pre-filled with no value. This enables, for instance, configuring a shared HTTP proxy server that all scripts can utilize. The configuration document will be automatically installed during a Sophora Server update to at least version 5.6.1.