Move API version out of path into query parameter and make number consistent. #233

Closed
evdb opened this Issue Jan 7, 2013 · 2 comments

Comments

Projects
None yet
3 participants
Contributor

evdb commented Jan 7, 2013

Currently the version number is in the path (/api/v123/person/...). Really it shouldn't be though from a purist point of view as the path should identify the resource, not the representation of the resource.

Instead we could make the API look for a version number in a query parameter (person...?v=123) and if missing default to the latest version.

This would also be a good time to make the version numbers more consistent - I messed up by making the initial API v1 and then confused issues further by making the improved one v0.1. I suggest that we stick with v0.1 and hide any reference to v1 and deprecate it as soon as the admin interface no longer needs it.

Owner

mhl commented Jan 7, 2013

For what it's worth, I'd vote to keep v1 as it is (since that version has been public for some time) and call v0.1 v2 instead.

As far as the main subject of this issue goes, I assume that if you do that, then you'll make sure that the old URLs still work? I think it should be a very low priority change, though - it's surely excessively purist to say that you can't have a prefix before identifying the resource.

Contributor

evdb commented Jan 7, 2013

v0.1 to v2 makes sense. And yes I'd avoid breaking old links.

It is a bit purist, but it also makes sense to not encode the version in the path. For example if there are two external sites referencing the same person in PopIt, but using different API versions to do so, then with the version in the path it would be harder to compare the urls. If however the version is something that is not included in the url, but only added by the code that interacts with the API, then the urls would be the same and so easily compared/shared.

Low priority, but I think worth getting right :)

dracos closed this Jul 5, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment