The quest for a better API
Hi everyone, I added these two ideas: "API-first" development REST API versioning should be actually used I would appreciate your help in voting them up if you agree with them. Thanks...
Forum Discussion
Regarding this Idea:
REST API versioning should be actually used
"vc" actually stands for "version configured" -- it is meant to point to whatever version of the Lithium REST API your community is configured (behind the scenes) to use. This allows you to make all your REST calls to a single version of the REST API and then when another version comes out, Lithium can change the configuration to point to a new version on stage, you can test the changes, then we can change the configuration to point to the new version on production. You can of course at any time decide to use a specific version of the REST API. Currently there is only a single version of the API, version 1, but you you could use "v1" in your REST calls instead of "vc", but this would then require you to change all your URLs to "v2" when a second version of the API is released that you want to start using with the new version. If you want to start using some URLs on v2 (when one comes out) and keep some on v1, then you would want to move away from using "vc" at that point, but becaues "vc" is always tied to a version of the REST API that is configured, it will always be tied to version 1 until you are ready for it to be moved to another verison.
Well that's the problem... By targeting "vc" with API calls, you remove all possibilities of upgrading the API without breaking something.
When you write something that calls "/restapi/vc/foo", and the foo call needs some change, it will break that code when you change the version vc tartgets.
If, however, you define that from now on "vc" = "v1" and always allow older API versions, my code cannot break even if the new API versions don't have the "foo" call.
In that situation, once I have working enterprise glue code, I never need to change it to use new versions of the API, since it's working as I want and the old API calls remain available.. If I want to use a new API version, I can use the new versions only for the calls I'm changing.
So my point is that providing "vc" is a misfeature.
"vc" doesn't point to the current version of the REST API, but to a "configured" version of the REST API that will never change unless you want it changed, so basically "vc" is already always locked to "v1" unless you want it to change, in which case we can change it. You can start using v1 in your calls if you want to and those calls will not be affected if you have us change "vc" to point to a different version later on. You can also choose to have us keep "vc" pointing at "v1" forever, effectively doing what you want (vc = v1). "vc" is there for cases where you want to do a mass upgrade of all API calls from one verison of the API to another version of the API. If you only want to change calls one-by-one to a specific version, you can do so at your leasure.
Ok, fair enough, but there is no reason to want to mass-upgrade to a new API version.
When an application worked with the old API it will not gain any new features when it's using a new API version. At best, nothing will happen and at worst, everything will break. In the mean time the mere fact that "vc" exists keeps Lithium from changing/extending the existing API.
