API interface versions should change very infrequently, but it must inevitably change over time. As the API version changes, app developers need to change their code accordingly. So you need to set versions so developers can access the latest incarnation of the API. An API version should reflect a significant change in the signature of the API. (An API revision, by contrast, reflects a minor update, such as a change in a policy setting. Revisions are usually deployed with minmal fanfare, although the may change the behavior of an API in some way that is not reflected in the interface defintion).
Basic versioning recommendations
As an API provider, you need to determine when it's appropriate to release a new version. Here are some guidelines you can use to make that decision:
- Never release an API without a version.
- Make the version mandatory.
- Specify the version with a "v" prefix. Place the prefix to the far left in the URL so that it has the highest scope, e.g., /v1/dogs.
- Use a single ordinal number, such as v1, v2, and so on.
- Make the version part of the API base path
Note: This is an interface not an implementation, so don't use the dot notation, like v1.2. This implies a granularity of versioning that doesn't work well with APIs. - Maintain at least one version back.
- Set up a reasonable deprecation policy. Give developers plenty of time and warning before dprecating features. Depending on your developer's platform, that can be six months or two years. For example, mobile apps take longer to rev than web apps.
