OpenRoam SDK for Java

Official client for the OpenRoam Partner API: eSIMs, airtime, utility payments, gift cards, hotels and flights. Java 11+.

Install

<dependency>
  <groupId>com.openroam</groupId>
  <artifactId>openroam-sdk</artifactId>
  <version>0.1.0-rc.6</version>
</dependency>

This is a release candidate: install it by its exact version, as above; a plain install does not pick it up. Before 1.0 the API can change between minor versions; every change is listed in the changelog.

Quick start

import com.openroam.sdk.EsimsSearchQuery;
import com.openroam.sdk.OpenRoam;
import com.openroam.sdk.model.*;

OpenRoam openroam = new OpenRoam(System.getenv("OPENROAM_API_KEY")); // or new OpenRoam() with OPENROAM_API_KEY set

EsimSearchResult found = openroam.esims().search(new EsimsSearchQuery().countryCode("JP"));
EsimOrderRequest body = new EsimOrderRequest().currency("USD").addItemsItem(new EsimOrderRequestItem().publicId(offerId).quantity(1));
EsimQuote quote = openroam.esims().quote(body);
EsimOrder order = openroam.esims().order(body);

openroam.esims().getUsage(iccid);
openroam.hotels().search(new HotelSearchRequest() /* ... */);

Every product is a resource of the client: esims(), airtime(), utilities(), giftCards(), hotels(), flights(), plus orders(), orderItems(), wallets(), currencies(), countries() and mobileNetworks(). Buying always reads search, quote, order; get fetches one thing you own, list... returns many, everything else starts with a verb. A path id is the first argument, a body is passed as it is (the model class, for example EsimOrderRequest). Query parameters are one object named after the method, for example EsimsSearchQuery for esims().search(...): its setters chain, a parameter you do not set is not sent, and its constructor takes the required ones (new AirtimeLookupNumberQuery(phoneNumber)). A method whose query parameters are all optional can also be called without them.

Options when you need them:

OpenRoam openroam = OpenRoam.builder()
    .apiKey("key")
    .environment(OpenRoam.Environment.SANDBOX) // default PRODUCTION
    .maxRetries(3)                             // default 0: no retries
    // .baseUrl("https://...") to point anywhere else, for example a development host
    // .httpClientBuilder(HttpClient.newBuilder().proxy(...)) for a proxy or a connect timeout
    .build();

A client is thread-safe: create one and share it.

Orders are safe to repeat

An idempotency key means: if the same request arrives twice, OpenRoam makes one order, not two. order() creates a key for you on every call, and the retries of that call reuse it. To stay safe even if your own program crashes and asks again, pass a UUID generated once and persisted for that purchase, for example your order id if it is a UUID:

openroam.esims().order(body, new RequestOptions().idempotencyKey(myOrderId));

Errors

A failed call throws an OpenRoamException (unchecked) with the error body of the API: getStatus(), getCode() (branch on this), getErrorName(), getMessage(), getRequestId() (keep it for support) and getDetails(). When no answer arrived (network error, timeout), getStatus() is null and getCause() has the original error. An interrupted call keeps the thread's interrupt flag set.

import com.openroam.sdk.OpenRoamException;

try {
    openroam.esims().order(body);
} catch (OpenRoamException e) {
    if (e.getCode() != null && e.getCode() == 11002) { /* the price rose above your maxPrice */ }
    else throw e;
}

A 202 answer with code 12002 (IDEMPOTENCY_KEY_IN_PROGRESS) is an error too: the order is still being accepted. Repeat the same call with the same key and body, or turn on retries, which do that for you.

Lists and pages

Pagination depends on the method. esims().search(...) accepts page and limit and returns getItems() and getPagination(), while orders().list(...) returns getOrders() and getPagination(). esims().listCatalog(...) accepts cursor and limit and returns getItems() and getNextCursor(); pass getNextCursor() as cursor to fetch the next page. Some lists, such as esims().listCompatibleDevices(), return an unpaged list.

Webhooks

import com.openroam.sdk.Webhooks;

Webhooks.verify(secret, timestampHeader, eventIdHeader, signatureHeader, rawBodyBytes);
// throws Webhooks.SignatureException when invalid or older than 5 minutes

Retries

Retries are off by default. Set maxRetries to retry network errors, 429, 502/503/504 and "still running" (12002) safely: a POST is sent again only with its Idempotency-Key, the same key and the same body, and order() always has one. A 500 and other 4xx answers are never repeated.

OpenRoam openroam = OpenRoam.builder().apiKey(apiKey).maxRetries(3).build();

The full behaviour: Retries and idempotency. OpenRoamRetry, RetryOptions and OpenRoamRetry.newIdempotencyKey() are also public if you build your own requests.

Good to know

The client is generated from the OpenRoam Partner API description, so it always matches the API; webhooks, retries and the errors are hand-written. MIT licensed.