Only show these results:

Migrate the Nylas Java SDK v1 to Kotlin/Java v2 beta

Version 2.0.0 of the Nylas Java SDK is a major release that prepares the SDK for the upcoming launch of the Nylas API v3. The goal of this release was to make the SDK more idiomatic and easier to use. It introduces Kotlin support, and the name has been changed to "Kotlin/Java SDK" to indicate this. The release also includes method and model documentation, so you can easily find the implementation details that you need.

The Nylas API v3 brings a lot of changes. Be sure to familiarize yourself with them before you start upgrading. For more information, see the list of v3 features and changes and the v3 diff list.

⚠️ The Nylas Kotlin/Java SDK v2 is not compatible with Nylas APIs earlier than v3 Beta. If you're still using an earlier version of the API, Nylas recommends that you keep using the Nylas Java SDK v1.x until you can start using the Nylas v3 APIs.

Migrate to Nylas Kotlin/Java SDK v2

📝 Note: The SDK's artifact name has been changed from nylas-java-sdk to nylas, making it consistent with the other Nylas SDK offerings. The name change also reflects that the SDK is no longer Java-only, but now supports Kotlin as well.

To upgrade a v1.x Nylas Java SDK to the Nylas Kotlin/Java SDK v2, change the dependency in your build.gradle file to the following specification.

implementation ('com.nylas.sdk:nylas:2.0.0-beta.1')

Initialize the NylasClient object

After you migrate to the Kotlin/Java SDK v2, you need to set up your environment. To do so, create a new NylasClient object using the builder, as below.

NylasClient nylas = new NylasClient.Builder("API_KEY").build();

⚠️ All previous methods of initializing the NylasClient object have been removed. The Nylas Kotlin/Java SDK now uses builder patterns only to create objects.

You can now use the NylasClient object to make API requests.

Changes to objects in the Kotlin/Java SDK v2

As mentioned above, the Nylas Kotlin/Java SDK now exclusively uses builder patterns to create objects. This makes it easier to create objects with many optional parameters. All models that include optional parameters have a builder class in v2 that you can use to create the object.

In v2, the SDK has different models for creating, updating, and retrieving objects. This better reflects the underlying methods in the Nylas API.

  • "Create" objects are prefixed with Create and have a Request suffix.
  • "Update" objects are prefixed with Update and have a Request suffix.
  • "Retrieve" objects use only the object's name.

Example: Calendar objects

In v1.x of the Nylas Java SDK, only one Calendar object was available. v2 of the Nylas Kotlin/Java SDK splits the Calendar object into three:

  • Calendar: An object for retrieving a Calendar.
  • CreateCalendarRequest: An object for creating a Calendar.
  • UpdateCalendarRequest: An object for updating a Calendar.

The following code snippet demonstrates how to create a new Calendar object.

NylasClient nylas = new NylasClient.Builder("API_KEY").build();

CreateCalendarRequest createCalendarRequest = new CreateCalendarRequest.Builder("My Calendar") // Calendar name is required.
    .description("My calendar description") // Calendar description is optional.
    .location("My calendar location") // Calendar location is optional.
    .timezone("America/New_York") // Calendar timezone is optional.
    .build();

Making requests to the Nylas API

To make requests to the Nylas API, you use the NylasClient object that you initialized during set up.

The Nylas SDK is organized into resources corresponding to each of the Email and Calendar APIs. Each resource includes all of the available methods to make requests to a specific API.

ℹ️ Available v3 APIs: Currently, only the v3 Email and Calendar APIs are available. The Messages, Drafts, Threads, and Contacts APIs are coming soon!

For example, to get a list of Calendars, you can use the calendars().list() method as in the example below.

NylasClient nylas = new NylasClient.Builder("API_KEY").build();
ListResponse<Calendars> calendars = nylas.calendars().list("GRANT_ID");

Changes to requests in the Kotlin/Java SDK v2

You may have noticed some new concepts in the Kotlin/Java SDK when making requests. These are explained in more detail in the following sections.

Resource parameters

In v2 of the Nylas Kotlin/Java SDK, each resource takes different parameters.

All resources take an identifier, which is the ID of the account ("Grant") that you want to make the request for. This is usually the account's Grant ID or email address.

Some resources also take query parameters, which are mainly used to filter data or pass additional information.

Standard response objects

The Nylas API v3 includes standard response objects for all requests, except those made to OAuth endpoints. Generally, you'll encounter two types of response objects:

  • Response: Used for requests that return a single object, such as retrieving a single Calendar. This returns a parameterized object of the type that you requested, and a string representing the request ID.
  • ListResponse: Used for requests that return a list of objects, such as retrieving a list of Calendars. This returns a list of parameterized objects of the type that you requested, a string representing the request ID, and a string representing the next page's token.

Standard error objects

Like the response objects, the Nylas API v3 includes standard error objects for all requests. The Nylas Kotlin/Java SDK includes two superclass error classes in v2:

  • AbstractNylasApiError: Used for errors returned by the API.
  • AbstractNylasSdkError: Used for errors returned by the SDK.

The AbstractNylasApiError class includes two subclasses:

  • NylasOAuthError: Used for API errors that are returned from OAuth endpoints.
  • NylasApiError: Used for all other Nylas API errors.

The Kotlin/Java SDK extracts error details from the request response and stores them in an error object, along with the associated request ID and HTTP status code.

Currently, the AbstractNylasSdkError class has only one subclass: the NylasSdkTimeoutError, which is thrown when a request times out.

Example: Error handling

The following example demonstrates how to make a request to create a new Event and handle any errors that may occur.

NylasClient nylas = new NylasClient.Builder("API_KEY").build();

// Build the create Event request.
CreateEventRequest createEventRequest = new CreateEventRequest.Builder(
    new CreateEventRequest.When
        .Timespan
        .Builder(1686765600, 1686769200)
        .build()
    ) // A "When" type is required.
    .title("My Event") // Title is optional.
    .description("My event description") // Description is optional.
    .location("My event location") // Location is optional.
    .build();

// Build the query parameters. They're required for Event creation.
CreateEventQueryParams createEventQueryParams = new CreateEventQueryParams.Builder(calendarId).build();

try {
    // Make the request.
    Response<Event> createdEventResponse = nylas.events().create(
        "GRANT_ID",
        createEventRequest,
        createEventQueryParams
    );
} catch (NylasApiError e) {
    // Handle error.
}

Authentication changes in the Kotlin/Java SDK v2

The authentication methods available in the Nylas Kotlin/Java SDK v2 reflect those available in the new Nylas API v3. Nylas recommends you use OAuth and an API key, but you should make sure you understand the options before migrating.

While you can only create and manage your application's connectors (previously called "integrations") in the v3 Dashboard, you can manage almost everything else directly from the Kotlin/Java SDK. This includes managing Grants, auth callback URIs ("redirect URIs"), and OAuth tokens, and authenticating your users.

The Nylas Kotlin/Java SDK v2 offers two main methods for authenticating users to your Nylas application:

  • Auth#urlForOAuth2: Returns the redirect URL for authentication with Nylas' OAuth 2.0 implementation.
  • Auth#exchangeCodeForToken: Exchanges an authorization code that Nylas returned from an authentication redirect for an access token from the OAuth provider.

You do not need to use a grant_id to make a request. Instead, you can use a Grant's associated email address as the identifier for the account. If you prefer to use the grant_id, you can extract it from the CodeExchangeResponse object and use it.

Example: Authenticate a user

The following example demonstrates how to authenticate a user into a Nylas application.

NylasClient nylas = new NylasClient.Builder("API_KEY").build();

String clientId = "NYLAS_CLIENT_ID";
String clientSecret = "NYLAS_CLIENT_SECRET";
String clientUri = "https://redirect-uri.com/path";

// Build the URL for authentication.
String authURL = nylasClient.auth().urlForOAuth2(
    new UrlForAuthenticationConfig.Builder(clientId, clientUri)
      .loginHint("[email protected]")
      .build());

// Write code here to redirect the user to the URL and parse the code.
    ...

// Exchange the code for an access token.
CodeExchangeRequest codeExchangeRequest = new CodeExchangeRequest.Builder(
    clientUri,
    "CODE",
    clientId,
    clientSecret
).build();

CodeExchangeResponse codeExchangeResponse = nylasClient.auth().exchangeCodeForToken(codeExchangeRequest);

// Use either the email address that was authenticated or the Grant ID from the response as the identifier.

// Using the email address.
ListResponse<Calendars> calendars = nylas.calendars().list("[email protected]");

// Using the Grant ID.
ListResponse<Calendars> calendars = nylas.calendars().list(codeExchangeResponse.getGrantId());

What's next?