Simple Java API Wrapper

You are currently on the Simple Java API Wrapper documentation page.

About

Simple Java API Wrapper is a lightweight no dependency Java 11+ framework for wrapping APIs into developer-friendly maintainable classes.

Technically, it has a dependency, because there is implemented class GsonApiResponse that will use GSON to deserialize API's JSON responses, however, you may not use this abstract class.

Skip to the installation...

Installation

Quick example

Here's an example worth of thousand words.

1. We have a class named SomeApi that contains methods for requesting the wrapped API

2. In the class SomeApi we have a method named #fetchSomething() that will request the endpoint /v1/users/:userId

3. The API's response will be deserialized using GSON (GsonApiResponse)

Wrapper class

SomeApi.java

public class SomeApi implements WrappedApi {
    
    @Override
    public String getDefaultUrl() {
        return "https://example.com"
    }
    
    public ApiRequest<SomeApiResponse> fetchSomething(String userId) {
        JsonObject requestBody = new JsonObject();
        requestBody.addProperty("someValue", 1337);
        
        return ApiRequest.builder(this, HttpBinResponse.class)
                         .withEndpoint("/v1/users/{userId}")
                         .withRequestMethod(RequestMethod.POST)
                         .withPathParameters(PathParameter.of("userId", userId))
                         .withRequestQueries(RequestQuery.of("some_query", "some_query_value"))
                         .withRequestHeaders(RequestHeader.of("SomeHeader", "SomeHeaderValue"),
                                             RequestHeader.ofContentType("application/json")
                         )
                         .withBodyPublisher(HttpRequest.BodyPublishers.ofString(jsonObject.toString()))
                         .withBodyHandler(HttpResponse.BodyHandlers.ofString())
                         .build();
    }
}

API Response class

SomeApiResponse.java

public class SomeApiResponse extends GsonApiResponse<SomeApi> {
    
    public String username;
    public String email;
}

Usage

Somewhere in your code...

public void doSomeWork() {
    // Prepare the wrapped API
    SomeApi someApi = new SomeApi();
    
    // Sync request
    SomeApiResponse someApiResponse = someApi.fetchSomething("123").send();
    System.out.println("Username: " + someApiResponse.username);
    
    // Async request
    someApi.fetchSomething("456")
           .sendAsync() // Returns CompletableFuture<SomeApiResponse>
           .whenCompletedAsync((response, throwable) -> {
               if (throwable != null) {
                   // Handle
                   return;
               }
               System.out.println("Username: " + someApiResponse.username);
           });
}

Installation

Maven

<dependency>
    <groupId>dev.mayuna</groupId>
    <artifactId>simple-java-api-wrapper</artifactId>
    <version>VERSION</version>
</dependency>

Gradle

repositories {
    mavenCentral()
}

dependencies {
    // Change 'implementation' to 'compile' in old Gradle versions
    implementation 'dev.mayuna:simple-java-api-wrapper:VERSION'
}

Latest version

You can find the latest version on the Maven Central Repository.

Eager to learn more?

pageWrappedApi interface