First post!
Excited to read about the new API; JSON responses will make much life
easier.
I’m also pleased to see the API returning URIs for resources instead of
just identifiers. I’m a big fan of this style of REST API as it reduces the
amount of knowledge the client needs of the API. In particular, if you have
some kind of offline representation of a resource (a local persistent
model), they can just keep a reference to their paths - great.
However, I was disappointed to see that you’ve gone down the route of
embedding the API version in the URI. What you’ve essentially done is made
migrating to a new API version harder than it needs to be.
Conceptually, I don’t believe a resource should need to change it’s URI.
Project X should ideally always exist at /api/projects/x. The API version
should dictate what exactly gets returned from that resource (it could be
a different schema for example). However, by embedding the API version in
the URL, you’ve essentially committed to changing the resource URIs when
the API version number changes. For me, the client, this means having to go
through and update all of the paths in my offline persistent store, rather
than simply requesting the new version via content negotiation.
Of course, any version change and any resulting schema change would mean
I’d have to update my app, but it would be nice if my app could continue to
fetch it’s remote representation from the same place and simply request
what version it expects to handle (assuming a new version didn’t
automatically remove support for the previous version).
There’s a great article here that explains this in more detail:
http://barelyenough.org/blog/2008/05/versioning-rest-web-services/
I’d be interested in hearing the reason for going down this route and if it
there is any chance of this being reconsidered so close to launch.
Thanks!