API versioning is a crucial feature for maintaining backward compatibility while continuously improving our API. In this article, we will outline how we carry out versioning.
Access the original endpoint version (v1)
In the original version (v1) of our API, endpoints do not require any version prefix. This means the endpoints are used as is, without any additional versioning information in the URL.
Example endpoints for v1:
Get all users:
GET /usersGet a single user:
GET /users/{id}Create a new user:
POST /usersUpdate a user:
PUT /users/{id}Delete a user:
DELETE /users/{id}
Access subsequent endpoint versions (v2, v3, etc.)
When a breaking change is introduced to the API, a new version is created. These newer versions are prefixed with /2/, /3/, /4/, and so on. Older versions will be marked as deprecated and will eventually be removed.
Example endpoints for v2:
Get all users:
GET /2/usersGet a single user:
GET /2/users/{id}Create a new user:
POST /2/usersUpdate a user:
PUT /2/users/{id}Delete a user:
DELETE /2/users/{id}