Although there are many ways to handle API versioning, we have chosen to use a URI-based versioning scheme (i.e., /api/:apiVersionId/resource/:resouceId.)
We expect to have both minor and major versions over time and, in general, we will only support a small number of API versions at the same time. The URI-based versioning scheme we have selected allows us to modify a specific resource without necessarily requiring all resource endpoints to be at the same version. We only expect to release major versions when these would create breaking changes for API consumers, whereas minor versions are more likely to reflect an evolution in the product that requires API support (for example, adding a new field to a resource).
If an API version of a resource is deprecated, we will prove feedback to this effect elsewhere in the documentation as well as in warning messages to applications calling these deprecated resources.