Based on customer feedback, we have been working on improving our all-category SDKs. We recently released our Advanced Java SDK. It is currently available for anyone to use.
Note that the existing Java SDKs are fully functional and will continue to work.
There are key benefits in using this Advanced SDK. We understand that migrating will take both time and effort, which is why we’ve worked on putting together this helpful migration guide.
We strongly recommend to use the new SDKs. You’ll play an integral role in providing feedback on our SDKs, making them more usable and robust and get a head start on migrating over.
We would love any and all feedback by reaching out to your engagement manager or [email protected]. All your feedback will be promptly addressed.
Migration Guide
This guide is for Merge customers using the gen-0 and gen-1 Java SDKs:
Generation | SDK Name | Github | Package Name |
0 | HRIS Java |
| |
0 | ATS Java |
| |
1 | Kotlin multi-category |
|
We recommend all customers move to the Advanced SDK:
package manager:
# maven
<dependency>
<groupId>dev.merge.api</groupId>
<artifactId>merge-java-client</artifactId>
<version>0.0.1</version>
<type>module</type>
</dependency>
# gradle implementation("dev.merge.api:merge-java-client:0.0.1")
This SDK has the following advantages:
Feature | Description |
Better base client | The earlier kotlin multicategory SDK relied on ktor-client as a base http client which is harder to work in Java than okhttp, so we have moved back to okhttp for this generation of SDK. |
Safer threading semantics | Due to the aforementioned ktor base library decision, threading and callback events were harder to work with and had memory leak issues that are no longer present with the new SDK. |
Flexible JSON inputs | The earlier SDKs had a tough time with customizability, but the new SDKs allow for more flexible inputs to highly-dynamic endpoints such as our CREATE and PASSTHROUGH endpoints. |
More builder pattern usage | The builder pattern will result in cleaner code as customers construct request parameters. |
Tests | This SDK ships with a much more comprehensive set of unit tests compared with the prior SDK. |
This SDK has all Merge categories, which makes it easy for Merge customers to find all endpoint methods in one package. The earlier single-category SDKs as well as the multi-category SDK all have the same style of method call, so let’s consider what it looks like to move from an existing employees list call to the new SDK.
Earlier SDK Code
AccountsApi accountsApi = new AccountsApi();
accountsApi.setApiKey("your API key");
accountsApi.setAccountToken("YOUR_X_ACCOUNT_TOKEN");
CompletableFuture<MergePaginatedResponse<Account>> accountingAccountsPromise = accountsApi.accountsListAsync(
new AccountsApi.AccountsListRequest()
);
MergePaginatedResponse<Account> accountingAccountsResponse = accountingAccountsPromise.get();
Advanced SDK Equivalent
MergeApiClient mergeClient = MergeApiClient.builder()
.accountToken("ACCOUNT_TOKEN")
.apiKey("API_KEY")
.build();
CandidatesListRequest request = CandidatesListRequest.builder()
.createdAfter(OffsetDateTime.parse("2007-12-03T10:15:30+01:00"))
.build();
PaginatedCandidateList list = mergeClient.ats().candidates().list(request);
if (list.getResults().isPresent()) {
List<Candidate> resultList = (List<Candidate>) list.getResults().get();
for(Candidate candidate : resultList) {
assertThat(candidate.getId().isPresent());
}
}
int iterations = 0;
while (list.getNext().isPresent() && iterations < 10) {
CandidatesListRequest iterParams = CandidatesListRequest.builder().cursor(list.getNext().get()).build();
list = mergeClient.ats().candidates().list(iterParams);
if (list.getResults().isPresent()) {
List<Candidate> resultList = (List<Candidate>) list.getResults().get();
for(Candidate candidate : resultList) {
assertThat(candidate.getId().isPresent());
}
}
iterations += 1;
}
Here are some key advantages from the new client class:
Increased use of
Optionalwrappers to help prevent null pointer exceptions.Ability to override
account_tokenin the SDK call to allow for dynamic reference to multiple linked accounts in the same organization.