Java

The Java SDK publishes to Maven Central. It targets Java 17, sends requests with java.net.http.HttpClient, and depends on Jackson plus the JSR-305 nullability annotations.

Install

<dependency>
  <groupId>com.your-org</groupId>
  <artifactId>api-client</artifactId>
  <version>1.0.0</version>
</dependency>

Options

Set these for Java in SDK Studio. Each one names its key for octri sdk settings set. Every option, for every language, is in the settings reference.

Client stylechoicedefault: class

class gives callers a client to create. functions gives free functions to import. See client style.

clientStyleByLang.java

Namespacechoicedefault: tags

Groups operations by tags, by URL path, or not at all with none.

namespaceByLang.java

Method namingchoicedefault: short

short drops the group's word from the method name, and full keeps the operation ID. Set for every language at once.

methodNaming

Argument stylechoicedefault: object

object takes one parameters object, and positional takes arguments in order. See argument style.

outputByLang.java.argumentStyle

Doc commentschoicedefault: full

full or minimal.

outputByLang.java.docComments

Usage examplechoicedefault: full

full or concise.

outputByLang.java.usageExample

File headerchoicedefault: include

include or omit. Omitting it needs the Enterprise plan. Set for every language at once.

fileHeader

Package name

Maven coordinates are groupId:artifactId, and the groupId must be a domain you control:

com.acme:api-client

Maven Central verifies the groupId

Central requires proof you own the domain behind the groupId, and releases are signed. That's more setup than npm, and it's worth starting before the day you want to ship.

Central releases are immutable

A published version can never be changed or removed. See Publishing.

What callers write

var config = new SdkConfig.ClientConfig();
config.baseUrl = "https://api.acme.com/v1";
var auth = new SdkConfig.ClientAuthConfig();
auth.bearer = System.getenv("ACME_TOKEN");
config.auth = auth;

var acme = new Acme(config);

// Namespaces are final fields on the client. The callback returns false to stop.
acme.users.listPaginated(
    Users.ListUsersRequest.builder().limit(100L).build(),
    user -> {
        System.out.println(user.id);
        return true;
    });

Request types are nested in their resource class (Users.ListUsersRequest, from acmeapi.methods.Users), and models expose public fields. Errors are unchecked: each common status is a subclass of SdkHttpError (SdkNotFoundError, SdkRateLimitError and so on) carrying statusCode and requestId.

Runtime


Requires	Java 17 or newer
HTTP	`java.net.http.HttpClient`
Timeout	30 seconds per attempt
Retries	Up to 3 attempts, with backoff from 500 ms to 8 seconds
Idempotency keys	`POST` and `PATCH`

Those are the defaults. See every setting and retries and timeouts to change them.

Streaming

For an operation that streams:

try (var events = client.events.stream()) {
    events.forEach(event -> System.out.println(event.id));
}

Returns a Stream<Event>. Close it, as here, so the connection is released. See streaming.

Handling errors

try {
    client.users.get(Users.GetUserRequest.builder().id("usr_1").build());
} catch (SdkNotFoundError error) {
    return null;
} catch (SdkHttpError error) {
    System.err.println(error.statusCode + " " + error.requestId);
    throw error;
}

Each common status has its own subclass of SdkHttpError. error.data holds the decoded model, which you can narrow with instanceof. See what's in the package.

Kotlin

Also Maven Central, with an engine choice.

Publishing

Connect Maven Central and release.