Upgrade a v2 project to use v3 Calendar APIs
This page explains what you need to do to upgrade your projects to use the Nylas v3 Calendar API.
The first step for every project migrating from Nylas v2.x to Nylas v3 is to assess and upgrade your authentication systems. Once you have your authentication working using v3, you can then upgrade your project to use the v3 Calendar API.
Recap: General updates in v3
You should already be aware of these changes, but as a reminder:
The Nylas API endpoints and production domains have changed in v3. They now follow the [service].[region].nylas.com schema:
api.nylas.com→api.us.nylas.comcanada.api.nylas.com→api.us.nylas.comireland.api.nylas.com→api.eu.nylas.com
In v3, Nylas removes the concept of "connected accounts" and instead works with "Grants". The grant_id for an account is used as a locator in most requests, so you may need to look up the user's grant_id before you can make API calls on their behalf.
Nylas v3 removes the concept of "Nylas Scopes" and uses the provider's scopes directly. See the Scopes documentation for more details. If you're authenticating with Microsoft, you must also translate your v2 application's scopes into the new Microsoft Graph scopes used in v3.
Coming soon and deprecated endpoints
Calendar and Events endpoints are available for Google, Microsoft Graph, IMAP, and Virtual Calendars in Nylas v3. Microsoft Exchange Web Services is no longer supported, and Calendar and Events support is coming soon for iCloud. Updates to Scheduler are also coming soon.
The Generate ICS file POST /events/to-ics endpoint and the Return room resources information GET /resources endpoint are in progress and coming soon to v3.
The Multiple consecutive meetings availability endpoint (POST /calendars/availability/consecutive) has been removed.
If your project requires any of these endpoints, contact Nylas Support before you begin the upgrade process.
Architecture changes
Nylas v3 no longer syncs data from providers, but instead queries them directly. This means that Nylas now relies on the provider as the source of truth, however some providers may require tuning to best handle their differing behavior. This is especially true for recurring events.
Syntax changes in v3
In v3 a Calendar ID is required for almost all calls. However, Nylas v3 includes a new endpoint that allows you to GET all calendars that a user has access to.
You can approach finding the calendar ID in the following ways:
- Get a list of all calendars for the grant ID, and find the ID of the calendar you want to work with, and use that.
- Use the
primaryparameter to specify the main calendar associated with the Grant on the service provider.- For Virtual Calendars, the
primarycalendar is the first calendar created for a grant, and it cannot be deleted. - iCloud calendars do not have a
primarycalendar, so you need to query for the ID first.
- For Virtual Calendars, the
Calendar Availability request changes
The endpoint to check for calendar availability (POST /calendars/availability) is unchanged, however some of its fields have been renamed for clarity. See the updated Calendar availability documentation, and the Availability v3 API reference for more details.
This endpoint does not require a grant ID or calendar ID because you can specify multiple participants to check for availability.
As a reminder for those of you who skip around when reading documentation (no shade), the Multiple consecutive meetings availability endpoint (POST /calendars/availability/consecutive) has been removed. If your project requires this endpoint, contact Nylas Support.
Recurring events in v3
The format for recurring Events has been simplified. Recurring Events no longer accept a recurrence timezone, and instead use the timezone specified in your when object to calculate the time for event instances. The when object is a time: in epoch time, and a timezone: in IANA format. See the Recurring events for more details.
Migrate Calendar endpoints
You can compare the v2 request schemas with the v3 request schemas.
- Return all calendars:
GET /calendars→GET /v3/grants/<grant_id>/calendars - Create a calendar:
POST /calendars→POST /v3/grants/<grant_id>/calendars - Return a calendar:
GET /calendars/<id>→GET /v3/grants/<grant_id>/calendars/<calendar_id> - Update a calendar:
PUT /calendars/<id>→PUT /v3/grants/<grant_id>/calendars/<calendar_id> - Delete a calendar:
DELETE /calendars/<id>→DELETE /v3/grants/<grant_id>/calendars/<calendar_id> - Check a calendar for free/busy status:
POST /calendars/free-busy→POST /v3/grants/<grant_id>/calendars/free-busy
Migrate Events endpoints
You can compare the v2 request schemas with the v3 request schemas.
- Return all Events:
GET /events→GET /v3/grants/<grant_id>/events - Create an Event:
POST /events→POST /v3/grants/<grant_id>/events - Return an Event:
GET /events/<id>→GET /v3/grants/<grant_id>/events/<event_id> - Update an Event:
PUT /events/<id>→PUT /v3/grants/<grant_id>/events/<event_id> - Delete an Event:
DELETE /events/<id>→DELETE /v3/grants/<grant_id>/events/<event_id> - Send RSVP:
POST /send-rsvp→POST /v3/grants/<grant_id>/events/<event_id>/send-rsvp
Calendar and event webhook triggers
The webhook triggers for calendar and events notifications have not changed, however Nylas has changed the webhook notification format and some behavior. Nylas now sends webhook notifications enriched with information about the object that changed, and does not send historical webhooks. See the Webhooks changes in v3 for more information about the changes, and the Calendar webhook schemas and Event webhook schemas for more information.