Versioning
Change in an API is unavoidable as your knowledge and experience of a system improve. To manage the impact of this change we have decided to use URI versioning.
URI Versioning
One way to version a REST API is to include the version number in the URI path.
When we introduce the version in the URI space, the Representations of Resources are considered immutable. So when changes need to be introduced in the API, a new URI space needs to be created.
For example, say an API publishes the following resources – users and privileges:
http://api.salla.dev/admin/v1/customers
http://api.salla.dev/admin/v1/products
Now, let's consider that a breaking change in the users API requires introducing a second version:
http://api.salla.dev/admin/v2/customers
http://api.salla.dev/admin/v2/products
When we add new Version
APIs only need to be up-versioned when a breaking change is made. Breaking changes include:
a change in the format of the response data for one or more calls
a change in the request or response type (i.e. changing an integer to a float)
removing any part of the API.
Changlog
The changelog lists every available version.