Just Put the Version in the URL

Nothing gets a debate going around API design quite like versioning. Versioning is when we decide that we need to change an existing endpoint but maintain both the original and the changed implementations. There are two decisions we have to make around versioning. The first is to decide what constitutes a new version. The second is how to model that in our API.

We recommend you adopt a simplified semantic versioning policy for our APIs. Semantic Versioning states that a version is three numbers separated by dots, for example, 1.4.5. The first is the major version, and when this changes, it indicates breaking changes to the underlying API. Code that worked with version 1 should expect to not work with version 2. Changes to the other two numbers (called minor and ...