Comparison with Nylas
Morgen APIs work differently than Nylas APIs in many ways. If you are familiar with Nylas, you may find it helpful to compare Morgen APIs with Nylas APIs.
End Users
Nylas does not have the concept of end user. When an end user is redirected to Nylas to connect their account, they are redirected to a page where they can select which account they want to connect. Nylas then connects to that account and returns an access token to you (the application). The application can then use that access token to operate on the connected account on behalf of the end user. This means that you need to store the access token(s) for each user account in the your database, associating those tokens with your internal User ID.
Morgen associates each authenticated account to a User ID. You will not receive an access token for each connected account. Instead, you only need the User ID, your Client ID and your Client Secret to generate a JWT that allows you (the application) to list the accounts an end user has connected, and to operate on those accounts on behalf of the end user.
The User ID is provided by you (the application). Most likely, you want to use your internal User ID to avoid having to maintein a mapping between your internal User ID and the Morgen User ID.
Authentication options
Nylas offers Hosted Authentication and Native Authentication. Hosted Authentication is a simple way to authenticate end users, with a single redirect to Nylas. Native Authentication is more complicated, but allows you to authenticate end users without redirecting them to Nylas and thus fully controlling the user experience.
Morgen authentication flow (see below) is similar to Nylas Hosted Authentication. However, the choice of the provider to connect should be made before redirecting the user to Morgen. This means that you need to provide a list of providers to the end user before redirecting them to Morgen.
Morgen also supports a flow similar to Nylas Native Authentication on request.
Different authorization flow
Nylas authorization is in two steps. First, you need to redirect the end user to a page where they can select which account they want to connect. Then, Nylas redirects the end user back to your application with an authorization code. Finally, you need to exchange the authorization code for an access token for the connected account.
Morgen does not require you to exchange a code for an access token. Instead, you can generate a JWT that allows you (the application) to list the accounts an end user has connected, and to operate on those accounts on behalf of the end user.
No Sync Policy
Nylas requires an application to specify a sync policy, indicating how many days of data history Nylas will sync. Only events within the specified sync policy will be returned by the Nylas APIs.
Morgen does not have a sync policy. In fact, Morgen does not sync calendar events at all. When you list the events for a connected account, you must specify time range to retrieve events for. Events will be retrieved on the fly from the calendar provider, map the events to the Morgen event model, and return the events to you.
Because Morgen does not keeps a copy of the user calendar events in its database, the API response time is likely to be longer than Nylas and bounded by the response time of the calendar provider. For user facing applications, you may want to consider caching the events in your application and follow a stale-while-revalidate strategy (opens in a new tab).
Variable-length IDs
Nylas returns fixed-length, Nylas-generated IDs for the returned entities (accounts, calendars and events).
Morgen does not generate IDs for the returned entities. The IDs, even though should be treated as opaque, are generated based on the provider external IDs and thus can vary significantly in length. For example, IDs for events from Office 365 are longer than IDs of Google Calendar events. If you store IDs in your database, you should not make any assumption about the length of the IDs.
Different data model
Nylas uses a proprietary data model for calendar and event data.
Morgen data model is based on the recently published JSCalendar (opens in a new tab) standard. The JSCalendar standard is a JSON-based representation of the iCalendar standard and we believe it is a more future-proof option. Morgen data model is a subset of the JSCalendar standard, and we plan to support the full JSCalendar standard in the future.
A peculiarity of the JSCalendar standard is that it makes extensive use of dictionaries instead of arrays. By providing a key to each dictionary entry, the standard allows for easy and unambiguous patching of nested objects (e.g. an event attendee). Every update operation of the Sync Service is a patch operation, meaning that only the properties that are sent in the request are updated.
Always expanding recurring events
Nylas expand_recurring parameter is used to specify whether recurring events should be expanded or not when listing events.
Morgen does not have an expand_recurring parameter. Instead, Morgen always expands recurring events when listing events.
It is not possible to get a list of recurring events without expanding them.
A single parameter to edit recurring events
Editing recurring events is a complex operation. If you are building a user-facing application, you probably want to provide the user the ability to apply changes to a single instance of a recurring event, to all instances of a recurring event, or to future instances of a recurring event.
Nylas requires you to operate differenly depending on which of the options above you want to support. For example, if you want to support editing a single instance of a recurring event, you need to retrieve expanded events and update the event instance you want to edit. If you want to support editing all instances of a recurring event, you need to retrieve the master event, and update that. If you want to support editing future instances of a recurring event, you need to do it in two steps by first updating the master event to put an end date on the recurrence, and then creating a new recurring event with the updated fields.
Morgen provides a single method to edit all events, while still supporting the three options above by setting the
seriesUpdateMode parameter. See the Edit an event section for more details.