Unirest for Java

Unirest-Java is a fluent HTTP client library designed for simplicity and ease of use. It supports modern HTTP protocols and provides extensive capabilities for both request building and response handling.

Key Features:

• Protocols: HTTP 1 and HTTP 2, and WebSockets.
• Data Formats: JSON Patch (RFC-6902) support and default object mappers for Jackson and GSON.
• Request Building:
  • Path parameters and query parameter building.
  • Header manipulation, including full cookie support.
  • Multipart requests.
  • Automatic conversion of POJOs into string or binary bodies.
  • Global request interceptors.
• Response Handling:
  • Global response interceptors.
  • Automatic conversion of response bodies into POJOs.
  • Built-in error handling.
• Testing: Includes a mocking library for testing HTTP interactions.

While Unirest maintains a primary single instance, you can manage multiple isolated configurations or use instances for testing purposes instead of the static context.

    // Access the same instance used by the static Unirest class
    UnirestInstance unirest = Unirest.primaryInstance();
    unirest.config().connectTimeout(5000);
    String result = unirest.get("http://foo").asString().getBody();

    // Create a completely new, isolated instance
    UnirestInstance unirest = Unirest.spawnInstance();

To use Jackson as the JSON parser for Unirest, add the unirest-objectmapper-jackson dependency to your Maven pom.xml file.

<dependency>
    <groupId>com.konghq</groupId>
    <artifactId>unirest-objectmapper-jackson</artifactId>
    <version>3.0.01</version>
</dependency>

Unirest 3.0 replaced the org.json dependency with a clean-room implementation of the org.json interface using Google Gson as the engine. This was done to avoid licensing issues associated with org.json.

Key Differences:

• Namespace: The new namespace is kong.unirest.core.json.
• Supported Classes: JSONArray, JSONObject, and JSONPointer honor most public interfaces and behaviors of the original org.json.
• Limitations: Utility classes like XML-to-JSON or CSV-to-JSON are not implemented. Custom indenting via .toString(int spaces) always uses 2 spaces.

Validate that expected requests were actually made using the following methods:

• mock.verifyAll(): Validates that every registered expectation was called at least once.
• expectation.verify(): Validates that a specific expectation was called.
• expectation.verify(Times times): Validates a specific expectation was called a specific number of times (e.g., Times.never()).

    @Test
    void verifyMultiple(){
        MockClient mock = MockClient.register();
    
        var zombo =    mock.expect(HttpMethod.POST, "http://zombo.com").thenReturn();
        var homestar = mock.expect(HttpMethod.DELETE, "http://homestarrunner.com").thenReturn();
    
        Unirest.post("http://zombo.com").asString().getBody();
    
        zombo.verify();
        homestar.verify(Times.never());
    }

To avoid affecting the global static state, use Unirest.spawnInstance() to create a new UnirestInstance. Register the mock specifically for that instance using MockClient.register(unirest). This is useful for isolated testing.

    @Test
    void mockInstant(){
        UnirestInstance unirest = Unirest.spawnInstance();
        MockClient mock = MockClient.register(unirest);
        
        mock.expect(HttpMethod.GET, "http://zombo.com")
                        .thenReturn("You can do anything!");
        
        assertEquals(
            "You can do anything!", 
            unirest.get("http://zombo.com").asString().getBody()
        );
    }

Methods like asString() and asJson() load the entire response into memory, which can cause issues with large payloads. To handle large responses efficiently, you can process the content stream directly using asObject with a custom mapper or use thenConsumeAsync to process the response asynchronously.

// Process large response via stream to avoid memory issues
Map r = Unirest.get(MockServer.GET)
               .queryString("firstname", "Gary")
               .asObject(i -> new Gson().fromJson(i.getContentReader(), HashMap.class))
               .getBody();

// Or use an async consumer
Unirest.get(MockServer.GET)
       .thenConsumeAsync(r -> {
           // Handle response (e.g., write stream to disk)
       });

In Unirest 4, all configuration is centralized through the Unirest.config() method. Configuration should ideally be performed once during application startup. Once Unirest has been activated, options involved in client creation cannot be changed without an explicit shutdown or reset.

    Unirest.config()
            .connectTimeout(1000)
            .proxy("proxy.example.com", 8080)
            .setDefaultHeader("Accept", "application/json")
            .followRedirects(false)
            .enableCookieManagement(false)
            .interceptor(new MyCustomInterceptor());

You can enable Unirest's simple in-memory response caching mechanism by calling Unirest.config().cacheResponses(true). Once enabled, subsequent requests to the same URL will return the cached response instead of making a new network call.

Unirest.config().cacheResponses(true);

// The first response will be cached, and the second will be retrieved from cache
Unirest.get("https://somwhere").asString();
Unirest.get("https://somwhere").asString();