Java project

Terra Java Client Library

Terra provides an API wrapper library for Java to help integrate with your application faster.

Features include:

• Fully asynchronous HTTP request wrapping
• Webhook parsing
• Webhook event dispatching
• User management

View Javadoc

Installation

terra-client is available for download from Maven Central.

Requirements:

• Java 11 or later

Gradle users

Add this dependency to your project's build file:

implementation "co.tryterra:terra-client:<version>"

Maven users

Add this dependency to your project's pom:

<dependency>
    <groupId>co.tryterra</groupId>
    <artifactId>terra-client</artifactId>
    <version>${terra-client.version}</version>
</dependency>

Usage

Setup

In order to interact with the Terra API using this library, you need an instance of TerraClientV2. This is created using TerraClientFactory:

TerraClientV2 client = TerraClientFactory.getClientV2("API KEY", "DEV ID");

In order to parse and handle webhook requests from Terra, you instead need an instance of WebhookHandlerUtility:

WebhookHandlerUtility webhookUtility = new WebhookHandlerUtility("WEBHOOK SECRET");

Authentication & User Management

This library does not provide the facilities for directly authenticating a user - you can currently only interact with users that have been authenticated previously.

Creating a User object

API request methods of your TerraClientV2 instance accept both User and PartialUser objects - this allows you not to make a web request to fetch a full User object if you are certain that a user with the given ID exists.

When any API request is made, a new User object will be returned with the response. (See TerraApiResponse#getUser())

With API request

User user = client.getUser("USER ID");

Without API request

PartialUser user = client.userFromId("USER ID");

Deauthentication

Future<TerraApiResponse<Void>> resp = client.deauthenticateUser(user);
if (resp.get().isSuccessful()) {
  System.out.println("User deauthenticated");
}