The quest for a better API

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.

Since "vc" is not pointed at the current version, but at a configurable verison that never has to change from v1 if you don't want it to, it is not preventing Lithium from moving forward with a new version of the API.  I believe we support exactly what you want here.  If you want to change your calls to "v1" you can.  If you want them left as "vc" but don't want Lithium to ever change the mapping from "vc" to v1 for your communties, Lithium can do that.

We are both repeating the same points.

• Yes, you are right, "vc" can remain static and pointing to "v1" if that's what I want
• Yes, I am right, "vc" is something that nobody should use and the API should be frozen per version.

Thanks for your feedback wmertens.  I agree that it's probably a reasonable best practice to use specific versions in your REST API calls instead of "vc" because you know you are always safe in case the configured version of the RESTAPI gets changed to a higher version.

...can you also see that providing a "vc" version ties your hands as far as changing the API goes?

Lithium should be updating the API all the time, and a given version should not be getting any changes once published...

I don't see how "vc" ties are hands as far as the API goes.  "vc" points to "v1" and always will, unless you ask Lithium to point it at a later version (when a later version is available), then LIthium can point "vc" to that version just for your community.  If you want to change individual calls at that point, you can do that and leave "vc" pointed to "v1".

It won't -- "vc" points to "v1" and always will, unless a customer asks us to point it at a later version (when a later version is available), then we can point "vc" to that version just for that customer.