New V3 API version available: 2021-01-09

93 views

Skip to first unread message

Developer at MBTA

unread,

Dec 23, 2020, 2:41:28 PM12/23/20

to MBTA Developers

Hi developers,

Today we released a new version of the V3 API: 2021-01-09. You can try out this version right now using the methods described in our Versioning doc. As the name suggests, it will become the default version for new API keys (and anonymous requests that don’t specify a version) on January 9th, 2021.

The major change in this version is that it drops a backward-compatibility feature related to the stop ID restructuring also occurring on January 9th. On this date, stop IDs returned by the API will change as described in that announcement, across all API versions. However, in versions before 2021-01-09, any request parameters that specify an “old” stop ID are treated as though they had also specified the corresponding “new” stop ID(s). This allows existing requests using a previous API version to work on both sides of the transition without changes. Because of this, you may want to hold off on migrating production apps to the new version until after January 9th, when the differences in behavior will become visible.

To illustrate using the /stops endpoints (though note this applies across all endpoints, anywhere a stop ID can be specified in a parameter):

/stops?filter[id]=Lynn
- with API version < 2021-01-09
  - before January 9th, returns 1 stop: Lynn
  - after January 9th, returns 3 stops: ER-0115, ER-0115-01, and ER-0115-02
- with API version >= 2021-01-09
  - before January 9th, returns 1 stop: Lynn
  - after January 9th, returns 0 stops

/stops?filter[id]=ER-0115
- regardless of API version
  - before January 9th, returns 0 stops
  - after January 9th, returns 1 stop: ER-0115

/stops/Lynn
- with API version < 2021-01-09
  - before January 9th, returns stop Lynn
  - after January 9th, returns stop ER-0115
- with API version >= 2021-01-09
  - before January 9th, returns stop Lynn
  - after January 9th, returns a 404 error

/stops/ER-0115
- regardless of API version
  - before January 9th, returns a 404 error
  - after January 9th, returns stop ER-0115

Note that since the /stops/:id endpoint can only return a single resource, it cannot include the new stops being created for specific platforms at Lynn station, and just returns the new “no specific platform” stop.

Finally, independent of the stop ID migration, this API version includes some minor changes:

The /predictions endpoint now correctly returns an error if a date filter is specified; previously it would accept one, but not do anything with it.
The /shapes endpoint no longer accepts direction_id as a filter or a sort key; these were mistakenly not removed in version 2020-05-01 when the corresponding attribute was removed from shapes.

A summary of these changes will soon be added to our Changelog. If you have any questions, please ask away in this thread!