Versioning

As we are introducing further improvements and fixes to the API, we try our best to make sure that our changes are backward-compatible. However, that’s not always possible; when we introduce a non backward-compatible change, we label it with a new version. The previous versions of the API still remain available and can be invoked using their own labels. In order to keep things simple, the version labels are formatted as a date, e.g. “2018-05-07”.

All API keys have a specific API version associated with them. This version controls the behavior of the API. Unless you change the version, the API behavior is going to remain the same, and any non-backward-compatible changes we make will not impact your application.

For users who want to upgrade, there are two ways:

1. The default version can be changed via the portal
2. The “MBTA-Version” header can be specified with each request
   • For example,

     MBTA-Version: 2018-05-07

Newly created API keys will default to the current version at the time they were created. You can always check what version your key is using via the portal.

Anonymous access without an API key will always default to the latest version. It can also be overridden with the “MBTA-Version” header.

Backwards-compatible changes

The following are changes that do not result in a new release:

• New resources
• New attributes on existing resources
• New relationships for existing resources
• New filters for existing resources
• Re-ordering of fields or values
• Changing the format or value of IDs
  • In particular, trip IDs can be changed at any time
  • However, IDs will always be strings

Upgrading to a new version

To upgrade to a new version, we suggest:

1. Update your code to work with both the old and new versions, then
2. Upgrade your default API version via the portal.

Keeping up-to-date

New releases will be posted to the developer group. We recommend subscribing to be notified about updates.

The documentation always reflects the latest version.

For non-backwards-compatible changes, see the changelog.

Experimental features

Occasionally, we will provide data or features in the API that are "experimental" and that may change or be removed with no prior notice. These will be noted in the Swagger documentation. In order to opt-in to use these features, a request must include the `x-enable-experimental-features: true` header.