Version:
Only show these results:

Upgrade v5 Nylas Ruby SDK to v6

Version 6.0.0 of the Nylas Ruby SDK is a major release that makes the SDK compatible with Nylas v3. The goal of this release was to make the SDK more intuitive and easier to use. It includes method and usage documentation, so you can easily find the implementation details that you need.

Nylas 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 v6.x Nylas Ruby SDK is only compatible with v3.x Nylas APIs. If you're still using an earlier version of Nylas, you should keep using the v5.x Ruby SDK until you can upgrade to Nylas v3.

Changes to v6 Ruby SDK

The new v6 Ruby SDK is a major release and brings a lot of changes. The following sections describe the updates.

Changes to authentication in v6 Ruby SDK

The authentication methods available in the v6 Ruby SDK reflect those available in the new v3 Nylas APIs. Nylas recommends you use OAuth and an API key to authenticate your end users, but you should make sure you understand the options before you migrate.

While you can only create and manage your Nylas application's connectors (previously called "integrations") from the v3 Dashboard, you can manage almost everything else directly from the v6 Ruby SDK. This includes grants, authentication callback URIs ("redirect URIs"), and OAuth tokens, and authenticating your end users.

The v6 Ruby SDK offers two main methods for authenticating end 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. The response also includes information about the grant that was created.

💡 You don't need to use a grant ID to make a request. Instead, you can use the email address associated with a grant as the identifier. If you prefer to use the grant ID, you can extract it from the CodeExchangeResponse and use it in your future requests.

The following examples show how to authenticate an end user in the v6 Ruby SDK, and in the v5 SDK for reference.

require 'nylas'

nylas = Nylas::API.new(
    api_key: "<NYLAS_API_KEY>",
)

# Build the URL for authentication.
auth_url = nylas.auth.url_for_oauth2(
    client_id: "<NYLAS_CLIENT_ID>",
    redirect_uri: "<CALLBACK_URI>",
    login_hint: "anna@example.com"
)

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

# Exchange the code for an access token.
code_exchange_response = nylas.auth.exchange_code_for_token({
  redirect_uri: "<CALLBACK_URI>",
  client_id: "<NYLAS_CLIENT_ID>",
  client_secret: "<NYLAS_CLIENT_SECRET>",
  code: "<AUTH_EXCHANGE_CODE>"
})

# Use either the email address that was authenticated or the Grant ID from the response as the identifier.
response_with_email = nylas.calendars.list(
    identifier: "anna@example.com"
)

response_with_grant = nylas.calendars.list(
    identifier: code_exchange_response.grant_id
)   
require 'nylas'

# Credentials of user
nylas = Nylas::API.new(
    app_id: "<NYLAS_CLIENT_ID>",
    app_secret: "<NYLAS_CLIENT_SECRET>",
    access_token: "<NYLAS_ACCESS_TOKEN>"
)

# Credentials to be granted
api = Nylas::API.new(
    app_id: "<NYLAS_CLIENT_ID>",
    app_secret: "<NYLAS_CLIENT_SECRET>"
)

# The URL for authentication
url = api.authentication_url(
    redirect_uri: "<CALLBACK_URI>", 
    scopes: ["<SCOPES>"], 
    response_type: "code", 
    login_hint: "anna@example.com", 
    state: "mycustomstate"
)

redirect to(url)

# Write logic to handle URL call
...

# Exchange the code for an access token.
account = api.exchange_code_for_token("<AUTH_EXCHANGE_CODE>", return_full_response: true)

# Use either the email address that was authenticated or the Grant ID from the response as the identifier.
events_with_email = nylas.events.where(calendar_id: "<EMAIL_CALENDAR_ID>")
events_with_grant = account.events.where(calendar_id: "<GRANT_CALENDAR_ID>")

Changes to requests in v6 Ruby SDK

You might notice some new concepts in the v6 Ruby SDK when you make requests:

These are explained in more detail in the following sections.

Resource parameters

In the v6 Nylas Ruby 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 v3 Nylas APIs include standard JSON response objects for all requests, except those made to OAuth endpoints. The v6 Nylas Ruby SDK parses the JSON response and returns a hash that contains the data from the API, and a string representing the original request ID. You can use this string for debugging and troubleshooting, as necessary.

List request responses include the same data, but the response hash contains an array of data that was returned from the Nylas API. If there are multiple pages of data, the response hash also contains a next_cursor key that includes a token representing the next page of data. You can extract this token and use it as a query parameter in a request to retrieve the next page of data.

🚀 Pagination features are coming to the Nylas Ruby SDK soon!

Standard error objects

The v3 Nylas APIs include standard error objects for all requests. The v6 Ruby SDK includes two superclass error classes:

  • 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 Ruby 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.

The code samples below show how to create an event and handle the errors that might occur in the v6 Ruby SDK, and in the v5 SDK for reference.

require 'nylas'

nylas = Nylas::API.new(
    api_key: "<NYLAS_API_KEY>",
)

begin
  # Build the Create Event request.
  create_event_request = nylas.events.create(
      identifier: "<NYLAS_GRANT_ID>",
      query_params: {
        calendar_id: "<CALENDAR_ID>",
      },
      request_body: {
        when: {
          start_time: 1686765600,
          end_time: 1686769200,
        },
        title: "My Event",                    # Optional
        description: "My event description",  # Optional
        location: "My event location",        # Optional
      }
  )
rescue Nylas::NylasApiError => e
  # Handle the error.
  puts e.message
  puts e.request_id
  puts e.status_code
rescue Nylas::NylasSdkTimeoutError => e
  # Handle the error.
  puts e.message
  puts e.url
end   
require 'nylas'

nylas = Nylas::API.new(
    app_id: "<NYLAS_CLIENT_ID>",
    app_secret: "<NYLAS_CLIENT_SECRET>",
    access_token: "<NYLAS_ACCESS_TOKEN>"
)

begin
  event = nylas.events.create(title: "My Event",
      description: "My event description",
      location: "My location"
      when: { 
        start_time: "1686765600", 
        end_time:  "1686769200"
      },
      calendar_id: "<CALENDAR_ID>")
rescue Exception => e
  puts "An error ocurred: #{e}"
end

Upgrade to v6 Ruby SDK

📝 The minimum Ruby version is now the lowest-supported long-term stable release (LTS): v3.0.

To upgrade the v5.x Ruby SDK to v6, download and install the new gem.

gem install nylas

Initialize a Nylas instance

After you upgrade to v6 of the SDK, you need to set up your environment. To do so, initialize a Nylas instance using the constructor. The examples below show the command you use with the v6 Ruby SDK, and with the v5 SDK for reference.

require 'nylas'

nylas = Nylas::API.new(
    api_key: "<NYLAS_API_KEY>",
)   
require 'nylas'

nylas = Nylas::API.new(
    app_id: "<NYLAS_CLIENT_ID>",
    app_secret: "<NYLAS_CLIENT_SECRET>",
    access_token: "<NYLAS_ACCESS_TOKEN>"
)

You can now use the Nylas instance to make API requests.

Make requests to the Nylas APIs

To make requests to the Nylas APIs, use the Nylas instance that you initialized during setup.

The v6 Ruby SDK is organized into resources corresponding to each of the Nylas APIs. Each resource includes all of the available methods to make requests to a specific API. For example, to get a list of events, you can use the events.list method.

The code samples below show how to list events using the v6 Ruby SDK, and using the v5 SDK for reference.

require 'nylas'

nylas = Nylas::API.new(
    api_key: "<NYLAS_API_KEY>",
)

events, _request_ids = nylas.events.list(identifier: "<NYLAS_GRANT_ID>")   
require 'nylas'

nylas = Nylas::API.new(
    app_id: "<NYLAS_CLIENT_ID>",
    app_secret: "<NYLAS_CLIENT_SECRET>",
    access_token: "<NYLAS_ACCESS_TOKEN>"
)

events = nylas.events.where(calendar_id: "<CALENDAR_ID>")

What's next?