Version REST APi as a whole, or by endpoint
I had a discussion with a colleague of mine today regarding versioning of a REST Api. We currently have an API with support for versioning by providing the correct version in the URL. So for instance: https://ourapi.com/api/v1/something Now we want to make a few contract changes to one of our "endpoints", and with that said.. we would like to introduce a new version of the API. The discussion we had is basically, should we version by "endpoints" or should we version the api as a whole? Lets pretend we have three endpoints https://ourapi.com/api/v1/people https://ourapi.com/api/v1/fruits https://ourapi.com/api/v1/animals We now make a contract change to the https://ourapi.com/api/v1/animals endpoint and we keep the old version unchanged as version 1, and the new version (version 2) can now be called using https://ourapi.com/api/v2/animals Should we now also "migrate" the other two endpoints to version 2 as well, even if we havent changed anything? So for our entire API we would have the following endpoints: https://ourapi.com/api/v1/people https://ourapi.com/api/v1/fruits https://ourapi.com/api/v1/animals https://ourapi.com/api/v2/people https://ourapi.com/api/v2/fruits https://ourapi.com/api/v2/animals Or should we just version the changed endpoint? https://ourapi.com/api/v1/people https://ourapi.com/api/v1/fruits https://ourapi.com/api/v1/animals https://ourapi.com/api/v2/animals The reason for versioning all endpoints would in this case be that my colleagues application currently uses a "base-url-variable" (containing https://ourapi.com/api/v1), and then for each "component" in the application he concatenates the base with the following path. So if we would simply up the version by one for all endpoints, all he would need to do is change the base-url, instead of changing the version for each component. Another "pros" for this would be that if someone visits the API documentation (swagger-ui in our case) he/she would only see a handful of possible endpoints for version 2, while many more for version 1. Which might be confusing (which one should I use?.. are the version 1 endpoints soon to be obsolete/deprecated? etc..?) However... Im not so sure that´s the correct way of doing things.. Since after all.. we haven´t really changed anything for the other endpoints, so why should they be "upped" a version? Wouldnt that just make it unclear of whats actually changed between version 1 and version 2? Besides that, in this case, version 1 and version 2 of the people and fruits-collection would still both use the same code.. so any changes to that endpoint would be reflected to all versions. (this might be a separate problem) Is there any common pratice to this? (I guess not, but would be nice to hear your thoughts..)
I had a discussion with a colleague of mine today regarding versioning of a REST Api.
We currently have an API with support for versioning by providing the correct version in the URL. So for instance:
https://ourapi.com/api/v1/something
Now we want to make a few contract changes to one of our "endpoints", and with that said.. we would like to introduce a new version of the API. The discussion we had is basically, should we version by "endpoints" or should we version the api as a whole?
Lets pretend we have three endpoints
We now make a contract change to the https://ourapi.com/api/v1/animals endpoint and we keep the old version unchanged as version 1, and the new version (version 2) can now be called using https://ourapi.com/api/v2/animals
Should we now also "migrate" the other two endpoints to version 2 as well, even if we havent changed anything? So for our entire API we would have the following endpoints:
- https://ourapi.com/api/v1/people
- https://ourapi.com/api/v1/fruits
- https://ourapi.com/api/v1/animals
- https://ourapi.com/api/v2/people
- https://ourapi.com/api/v2/fruits
- https://ourapi.com/api/v2/animals
Or should we just version the changed endpoint?
- https://ourapi.com/api/v1/people
- https://ourapi.com/api/v1/fruits
- https://ourapi.com/api/v1/animals
- https://ourapi.com/api/v2/animals
The reason for versioning all endpoints would in this case be that my colleagues application currently uses a "base-url-variable" (containing https://ourapi.com/api/v1), and then for each "component" in the application he concatenates the base with the following path. So if we would simply up the version by one for all endpoints, all he would need to do is change the base-url, instead of changing the version for each component. Another "pros" for this would be that if someone visits the API documentation (swagger-ui in our case) he/she would only see a handful of possible endpoints for version 2, while many more for version 1. Which might be confusing (which one should I use?.. are the version 1 endpoints soon to be obsolete/deprecated? etc..?)
However... Im not so sure that´s the correct way of doing things.. Since after all.. we haven´t really changed anything for the other endpoints, so why should they be "upped" a version? Wouldnt that just make it unclear of whats actually changed between version 1 and version 2? Besides that, in this case, version 1 and version 2 of the people and fruits-collection would still both use the same code.. so any changes to that endpoint would be reflected to all versions. (this might be a separate problem) Is there any common pratice to this? (I guess not, but would be nice to hear your thoughts..)
