Repository files navigation

The Openlayer Java SDK provides convenient access to the Openlayer REST API from applications written in Java. It includes helper classes with helpful types and documentation for every request and response property.

The Openlayer Java SDK is similar to the Openlayer Kotlin SDK but with minor differences that make it more ergonomic for use in Java, such asOptional instead of nullable values,Stream instead ofSequence, andCompletableFuture instead of suspend functions.

It is generated withStainless.

The REST API documentation can be found onopenlayer.com.

implementation("com.openlayer.api:openlayer-java:0.1.0-alpha.11")

<dependency>    <groupId>com.openlayer.api</groupId>    <artifactId>openlayer-java</artifactId>    <version>0.1.0-alpha.11</version></dependency>

UseOpenlayerOkHttpClient.builder() to configure the client.

Alternately, set the environment withOPENLAYER_API_KEY, and useOpenlayerOkHttpClient.fromEnv() to read from the environment.

importcom.openlayer.api.client.OpenlayerClient;importcom.openlayer.api.client.okhttp.OpenlayerOkHttpClient;OpenlayerClientclient =OpenlayerOkHttpClient.fromEnv();// Note: you can also call fromEnv() from the client builder, for example if you need to set additional propertiesOpenlayerClientclient =OpenlayerOkHttpClient.builder()    .fromEnv()// ... set properties on the builder    .build();

Read the documentation for more configuration options.

To create a new inference pipeline data, first use theInferencePipelineDataStreamParams builder to specify attributes, then pass that to thestream method of thedata service.

importcom.openlayer.api.core.JsonValue;importcom.openlayer.api.models.InferencePipelineDataStreamParams;importcom.openlayer.api.models.InferencePipelineDataStreamResponse;importjava.util.List;InferencePipelineDataStreamParamsparams =InferencePipelineDataStreamParams.builder()    .inferencePipelineId("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")    .config(InferencePipelineDataStreamParams.Config.ofLlmData(InferencePipelineDataStreamParams.Config.LlmData.builder()        .inputVariableNames(List.of("user_query"))        .outputColumnName("output")        .numOfTokenColumnName("tokens")        .costColumnName("cost")        .timestampColumnName("timestamp")        .build()))    .rows(List.of(InferencePipelineDataStreamParams.Row.builder()        .putAdditionalProperty("user_query",JsonValue.from("what is the meaning of life?"))        .putAdditionalProperty("output",JsonValue.from("42"))        .putAdditionalProperty("tokens",JsonValue.from(7))        .putAdditionalProperty("cost",JsonValue.from(0.02))        .putAdditionalProperty("timestamp",JsonValue.from(1610000000))        .build()))    .build();InferencePipelineDataStreamResponseresponse =client.inferencePipelines().data().stream(params);

To make a request to the Openlayer API, you generally build an instance of the appropriateParams class.

InExample: creating a resource above, we used theInferencePipelineDataStreamParams.builder() to pass to thestream method of thedata service.

Sometimes, the API may support other properties that are not yet supported in the Java SDK types. In that case, you can attach them using theputAdditionalProperty method.

importcom.openlayer.api.core.JsonValue;importcom.openlayer.api.models.InferencePipelineDataStreamParams;InferencePipelineDataStreamParamsparams =InferencePipelineDataStreamParams.builder()// ... normal properties    .putAdditionalProperty("secret_param",JsonValue.from("4242"))    .build();

When receiving a response, the Openlayer Java SDK will deserialize it into instances of the typed model classes. In rare cases, the API may return a response property that doesn't match the expected Java type. If you directly access the mistaken property, the SDK will throw an uncheckedOpenlayerInvalidDataException at runtime. If you would prefer to check in advance that that response is completely well-typed, call.validate() on the returned model.

importcom.openlayer.api.models.InferencePipelineDataStreamResponse;InferencePipelineDataStreamResponseresponse =client.inferencePipelines().data().stream().validate();

In rare cases, you may want to access the underlying JSON value for a response property rather than using the typed version provided by this SDK. Each model property has a corresponding JSON version, with an underscore before the method name, which returns aJsonField value.

importcom.openlayer.api.core.JsonField;importjava.util.Optional;JsonFieldfield =responseObj._field();if (field.isMissing()) {// Value was not specified in the JSON response}elseif (field.isNull()) {// Value was provided as a literal null}else {// See if value was provided as a stringOptional<String>jsonString =field.asString();// If the value given by the API did not match the shape that the SDK expects// you can deserialise into a custom typeMyClassmyObj =responseObj._field().asUnknown().orElseThrow().convert(MyClass.class);}

Sometimes, the server response may include additional properties that are not yet available in this library's types. You can access them using the model's_additionalProperties method:

importcom.openlayer.api.core.JsonValue;JsonValuesecret =projectCreateResponse._additionalProperties().get("secret_field");

This library throws exceptions in a single hierarchy for easy handling:

• OpenlayerException - Base exception for all exceptions

• OpenlayerServiceException - HTTP errors with a well-formed response body we were able to parse. The exception message and the.debuggingRequestId() will be set by the server.

  400	BadRequestException
  401	AuthenticationException
  403	PermissionDeniedException
  404	NotFoundException
  422	UnprocessableEntityException
  429	RateLimitException
  5xx	InternalServerException
  others	UnexpectedStatusCodeException

• OpenlayerIoException - I/O networking errors

• OpenlayerInvalidDataException - any other exceptions on the client side, e.g.:

  • We failed to serialize the request body
  • We failed to parse the response body (has access to response code and body)

Requests that experience certain errors are automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried by default. You can provide amaxRetries on the client builder to configure this:

importcom.openlayer.api.client.OpenlayerClient;importcom.openlayer.api.client.okhttp.OpenlayerOkHttpClient;OpenlayerClientclient =OpenlayerOkHttpClient.builder()    .fromEnv()    .maxRetries(4)    .build();

Requests time out after 1 minute by default. You can configure this on the client builder:

importcom.openlayer.api.client.OpenlayerClient;importcom.openlayer.api.client.okhttp.OpenlayerOkHttpClient;importjava.time.Duration;OpenlayerClientclient =OpenlayerOkHttpClient.builder()    .fromEnv()    .timeout(Duration.ofSeconds(30))    .build();

Requests can be routed through a proxy. You can configure this on the client builder:

importcom.openlayer.api.client.OpenlayerClient;importcom.openlayer.api.client.okhttp.OpenlayerOkHttpClient;importjava.net.InetSocketAddress;importjava.net.Proxy;OpenlayerClientclient =OpenlayerOkHttpClient.builder()    .fromEnv()    .proxy(newProxy(Proxy.Type.HTTP,newInetSocketAddress("example.com",8080)))    .build();

This library is typed for convenient access to the documented API. If you need to access undocumented params or response properties, the library can still be used.

To make requests using undocumented parameters, you can provide or override parameters on the params object while building it.

FooCreateParams address=FooCreateParams.builder()    .id("my_id")    .putAdditionalProperty("secret_prop",JsonValue.from("hello"))    .build();

To access undocumented response properties, you can useres._additionalProperties() on a response object to get a map of untyped fields of typeMap<String, JsonValue>. You can then access fields like._additionalProperties().get("secret_prop").asString() or use other helpers defined on theJsonValue class to extract it to a desired type.

We use the standardOkHttp logging interceptor.

You can enable logging by setting the environment variableOPENLAYER_LOG toinfo.

$export OPENLAYER_LOG=info

Or todebug for more verbose logging.

$export OPENLAYER_LOG=debug

This package generally followsSemVer conventions, though certain backwards-incompatible changes may be released as minor versions:

1. Changes to library internals which are technically public but not intended or documented for external use.(Please open a GitHub issue to let us know if you are relying on such internals).
2. Changes that we do not expect to impact the vast majority of users in practice.

We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.

We are keen for your feedback; please open anissue with questions, bugs, or suggestions.

This library requires Java 8 or later.