Skip to content

Upgrading from 3.X to 4.0

Jump to bottom
Zee edited this page Dec 1, 2017 · 4 revisions

The Nylas Ruby SDK is officially breaking backwards compatibility in order to provide a more modern ruby focused user experience.

This includes:

  • Keyword args over positional args.
  • More YARD documentation!
  • Models and Queries will conform (pretty closely) to ActiveModel and ActiveResource.
  • Separating out the modeling layer from the "just let me retrieve arrays of hashes plz" layer.
  • And probably more.

In doing so, version 4.0 will keep as much backwards compatibility as possible with the 3.X series while marking most of the interfaces that don't support the above goals as deprecated. 5.0 will then remove those deprecated features (likely not until 2019 or 2020)

This means upgrading from 3.X to 4.0 should be relatively painless, while 4.X to 5.0 will require more significant code changes you can make over a longer period of time.

Upgrading from 3.X to 4.0 will require code changes in the following cases:

To Change Your Nylas::API.new Calls

There are two options:

  1. Update your calls to Nylas::API.new to use the new keyword arguments instead of positional arguments
  2. Replace your calls to Nylas::API.new to Nylas::API.deprecated_new.

In the first case, you'll want to map the positional arguments to the following keyword args:

  • First Arg is now app_id
  • Second arg is now app_secret
  • Third arg is now access_token
  • Fourth arg is now api_server
  • Fifth arg is now service_domain

Here's an example of changing from the deprecated new syntax to the modern new syntax with keyword arguments:

# Old
Nylas::API.new("your_app_id", "your_app_secret", 
               "your_users_access_token", 
               "https://your-hosted-nylas.example.com",
               "your-hosted-nylas.example.com')

# New! Modern! Keywords!
Nylas::API.new(app_id: "your_app_id", app_secret: "your_app_secret", 
               access_token: "your_users_access_token", 
               api_server: "https://your-hosted-nylas.example.com", 
               service_domain: "your-hosted-nylas.examples.com")

For those of you who are hesitant to embrace the deliciousness that is Keyword args, we've also provided the ability to replace all your existing calls to new with calls to deprecated_new. Yes, this still requires a change on your part; but it should be much smaller and require a find/replace transformation which is very safe from a risk of transformation perspective, whereas shifting arguments is a slightly higher risk.

Example:

# Old
Nylas::API.new("your_app_id", "your_app_secret", 
               "your_users_access_token", "https://your-hosted-nylas.example.com",
               "your-hosted-nylas.example.com')

# New
Nylas::API.deprecated_new("your_app_id", "your_app_secret", 
                          "your_users_access_token", 
                          "https://your-hosted-nylas.example.com",
                          "your-hosted-nylas.example.com')

But Why?

Keyword arguments make life easier for most programmers because they allow us to use names to reference what we're passing into methods and functions. Ruby introduced them in Ruby 2.0, with full support in 2.1. While they are slightly more verbose, it's strongly preferred that methods which take more than 1 argument to keyword arguments for secondary arguments and/or any optional arguments. See This thoughtbot post on keyword args for more context.

To Keep Using the Streaming API

The Delta Streams API is super useful for a number of our users; however we have chosen to split it into it's own package. See https://github.com/nylas/nylas-ruby/pull/151/ for more details. To continue using the Delta Stream API, change your Gemfile to use nylas-streaming instead of nylas.

But Why?

The Ruby Streaming SDK depended on yajl and em-http-request. Both of these libraries are fabulous, but we prefer to keep a lower upstream dependency graph especially if the dependency isn't being used throughout the rest of the library.

Clone this wiki locally