Versioning our API allows us to roll out new changes over time while continuing to support existing products so developers have plenty of time to move to the new version.
Below is our policy:
- All API resources have the same version and will be incremented together
- Keep the version unchanged when introducing a non-breaking change
- Increment the minor version (e.g. 7.0 to 7.1) when introducing a breaking change
- Increment the major version (e.g. 7.1 to 8.0) when introducing substantial functionality
- Version APIs and SDKs independently, e.g. V7.0 API is encapsulated in V2.0 of SDK
- Allow multiple versions of APIs or SDKs with different functionality to exist
Each version of our API is guaranteed to be supported for at least one year. A version will no longer be usable one year after the date that a subsequent version is released.
If API version 7.0 is released on July 1st, 2014 and API version 7.1 is released December 1st, 2014 then v7.0 would expire on December 1st, 2015, one year after the release of v7.1.
Below is an example of the timeline: