SaaSquatch Java SDK

SaaSquatch SDK for Java

Adding SaaSquatch Java SDK to your project

SaaSquatch Java SDK is hosted on JitPack.

Add JitPack repository:

Maven

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

Gradle

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

Add the dependency:

Maven

<dependency>
  <groupId>com.github.saasquatch</groupId>
  <artifactId>saasquatch-java-sdk</artifactId>
  <version>0.2.0</version>
</dependency>

Gradle

dependencies {
    implementation 'com.github.saasquatch:saasquatch-java-sdk:0.2.0'
}

For more information and other built tools, please refer to the JitPack page.

This library aims to abstract away the I/O layer and Reactive Streams implementations to be implementation agnostic. As of right now, this library depends on RxJava 3, Gson, and Apache HttpClient 5, but never exposes library-specific interfaces other than Reactive Streams interfaces. It is recommended that you explicitly import the transitive dependencies if you intend to use them directly, since we may upgrade or switch to other I/O or Reactive Streams libraries in the future.

Android

SaaSquatch Java SDK works on Java 8+ and Android API level 21+. To use this library on Android, you'll need to configure your project to use Java 8 by adding the following to build.gradle (see Android official docs for more information).

Squatch Android is an Android wrapper of this library with Android specific features.

Using the SDK

The entry point of the SDK is SaaSquatchClient. To create a SaaSquatchClient for your tenant with default options, use:

SaaSquatchClient.createForTenant("yourTenantAlias");

If you are in a multi-tenant environment, you can create a tenant-agnostic SaaSquatchClient like this:

SaaSquatchClient.create(ClientOptions.newBuilder().build());

The code above will create a SaaSquatchClient without a default tenantAlias, in which case you'll need to pass in a tenantAlias via RequestOptions for every request you make.

You can also use more advanced options like this:

SaaSquatchClient.create(ClientOptions.newBuilder()
    .setTenantAlias("yourTenantAlias")
    /*
     * This sets the default tenant API key. Note that this option makes more sense
     * if you are using this SDK on the server side. Use this with caution if you are
     * building an Android app.
     */
    .setAuthMethod(AuthMethod.ofTenantApiKey("yourApiKey"))
    .setRequestTimeout(5, TimeUnit.SECONDS)
    // etc.
    .build());

It is recommended that you keep a singleton SaaSquatchClient for all your requests instead of creating a new SaaSquatchClient for every request. SaaSquatchClient implements Closeable, and it's a good idea to call close() to release resources when you are done with it.

Every API method in SaaSquatchClient takes a RequestOptions, where you can specify your tenantAlias override, authentication method override, etc. The per-method RequestOptions always takes precedence over the client-level ClientOptions.

SaaSquatchClient returns Reactive Streams interfaces. Assuming you are using RxJava, then a typical API call made with this SDK would look something like this:

final Publisher<JsonObjectApiResponse> responsePublisher = saasquatchClient
    .userUpsert(userInput,
        RequestOptions.newBuilder().setAuthMethod(AuthMethods.ofJwt(jwt)).build());
Flowable.fromPublisher(responsePublisher)
    .doOnNext(response -> {
      System.out.printf("Status[%d] received\n", response.getHttpResponse().getStatusCode());
      // Getting the raw JSON data as a Map and do whatever you want with it
      final Map<String, Object> data = response.getData();
      // Or unmarshal the JSON result to one of the provided model classes
      final User user = response.toModel(User.class);
      System.out.printf("User with accountId[%s] and id[%s] created\n",
          user.getAccountId(), user.getId());
    })
    .onErrorResumeNext(ex -> {
      if (ex instanceof SaaSquatchApiException) {
        // Non 2XX received, in which case we should typically get a standard api error
        final ApiError apiError = ((SaaSquatchApiException) ex).getApiError();
        System.out.println(apiError.getMessage());
        return Flowable.empty();
      }
      // Catastrophic failure!!!
      ex.printStackTrace();
      return Flowable.error(ex);
    })
    .subscribe();

Unstable APIs

Anything marked with the @Beta or @Internal annotations, as well as anything under the package com.saasquatch.sdk.internal, are either experimental or considered private API, and can be modified in breaking ways or removed without warning.

Development

This project uses a simple Maven build. Compile with mvn compile and run tests with mvn test.

Since Android still doesn't fully support Java 8 🤦, Java 8 specific classes like CompletableFuture, java.util.Optional, and java.time.Instant should be avoided. Java 8 language features like lambda expressions, however, can be used. This restriction does not apply to the test suite.

To run integration tests, you'll need a SaaSquatch account, and run:

mvn test -D"com.saasquatch.sdk.test.appDomain"="REPLACEME" -D"com.saasquatch.sdk.test.tenantAlias"="REPLACEME" -D"com.saasquatch.sdk.test.tenantApiKey"="REPLACEME"

License

Unless explicitly stated otherwise all files in this repository are licensed under the Apache License 2.0.

License boilerplate:

Copyright 2023 ReferralSaaSquatch.com, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.