Migrating from Namespaces

We’ve put this guide together to help you transition from using deprecated Namespace endpoints in the Nylas API.

Why make this change?

We previously used namespaces as a reference to linked email accounts. In addition to having access to the /n endpoint to get a list of linked accounts, you were requiried to include the namespace id associated with an account in the URI. To simplify the API, we are removing this requirement and associating the linked email account with the credentials you are using.

What’s new?

Endpoint URIs

When accessing resources, you no longer include the namespace id that is associated with the linked account in the URL:

:::xml
GET https://api.nylas.com/n/<namespace_id>/threads

becomes

:::xml
GET https://api.nylas.com/threads

Account objects

The Account has been created to contain attributes previously accessible via namespaces.

:::xml
GET https://api.nylas.com/account

It includes the all the same attributes, except for the namespace_id attribute. The account_id is now the primary identifier that corresponds to the resource. As described in the section below, the new account_id corresponds to the old namespace_id attribute as we are no longer exposing the old namespace account_id attribute.

See the Account object documentation for more details.

What about my existing namespace id’s?

The value of the namespace_id attribute on the old namespace object associated with the email account is now the value of the account_id attribute on the new account object.

Old namespace object:

:::json
[
    {
        "id": "awa6ltos76vz5hvphkp8k17nt",
        "object": "namespace",
        "namespace_id": "awa6ltos76vz5hvphkp8k17nt",
        "account_id": "c5zc216uat483slypx67mu8i3",
        "email_address": "ben.bitdiddle@gmail.com",
        "name": "Ben Bitdiddle",
        "provider": "gmail",
        "organization_unit": "label"
    }
]

New account object:

:::json
{
    "id": "awa6ltos76vz5hvphkp8k17nt",
    "account_id": "awa6ltos76vz5hvphkp8k17nt",
    "object": "account",
    "name": "Ben Bitdiddle",
    "email_address": "benbitdiddle@gmail.com",
    "provider": "gmail",
    "organization_unit": "labels"
}

Note that the old account_id value on the namespace object does not carry over.

SDK Changes

If you are using an SDK, you should upgrade to the latest stable version. It will reflect the transition from namespaces to accounts.

Ruby

After creating the API client object, access resources directly from that object rather than specifying a namespace.

:::ruby
 nylas = Nylas::API.new(config.nylas_app_id, config.nylas_app_secret, nylas_token)
 
# Previously we had to get a namespace
# namespace = nylas.namespaces.first
# thread = namespace.threads.first

# Now, just use the API object
thread = nylas.threads.first

See more examples in the documentation in the nylas-ruby repo.

Python

After fetching an APIClient object, use that object to access resources.

:::python
client = APIClient(APP_ID, APP_SECRET, token)

# the old way to fetch a thread
# thread = namespace.threads.first()

# now use the client object
thread = client.threads.first()

You used to have to specify the namespace when using the client object to access other api objects. Now, you access them without using the namespace:

:::python
# previously specified a namespace object
# messages = client.namespaces[0].messages

# now use the client object
messages = client.messages

See more examples in the documentation in the nylas-python repo.

Node.js

:::javascript
//  Previously a namespace was required
//  Nylas.with(accessToken).namespaces.first({}).then(function(namespace){
//      namespace.threads.first().then(function(thread) {
//          console.log(thread.subject);
//          console.log(thread.snippet);
//      })
//  });

// Now, simply use the Nylas object
var nylas = Nylas.with(accessToken);
nylas.threads.first().then(function(thread) {
   console.log(thread.subject);
   console.log(thread.snippet);
})

See more examples in the documentation in the nylas-nodejs repo.

How long will the namespaces be supported?

Before announcing this change, we’ve worked with existing production customers to begin migrating their applications and found the switch to be surprisingly quick and painless. The full namespaces API will be officially disabled on October 15, 2015.

I have more questions!

For full details, see the Accounts. And for additional questions, feel free to contact support.

Have more questions? Submit a request

Comments