5 ms·

Please namespace your URLs by a version, such as "v1" (not just "1", which looks like a resource ID). If anything, this will motivate you even more to maintain

Please namespace your URLs by a version, such as "v1" (not just "1", which looks like a resource ID). If anything, this will motivate you even more to maintain backwards compatibility when you update your API, since there is nothing more infuriating to a developer than waking up one day to find an API call has changed (I'm looking at you Facebook). Namespacing by version also is pretty "clean." Imagine updating your API in the future without the namespace. You'd have to implement the version in some difficult way (for the end developer) such as during authentication or as a request param or cookie or something ridiculous. This all adds complexity to the developers using the API. Its _much_ easier for a developer to just say "The prefix for all RESTful API calls is http://foobar.com/v1 http://foobar.com/v1. No developer will say thats not clean. So please, put a version number in your API, put it at the beginning, and put it in the "vX" format.

qixxiq 16y ago
Thanks, my main problem was that /1/ did look dirty. The /v1/ is much better, and solves the problem.
- psadauskas 16y ago
  No, please don't do this. Having a version string in the uri is bad. The version means nothing about the resource, and everything about the representation. Please see some of the links further down in the comments for a more detailed explanation.
  - qixxiq 16y ago
    I've read through all the links, and whichever way I go its a compromise. I'm choosing the /v1/ route because its a neat solution to the problem, it will work without serious issues and developers understand it easily. Yes its not 110% REST, but I believe its the best solution to my problem. The fact that other major API's are taking the same route (Amazon,Twitter) just enforces the idea.
jmillikin 16y ago
> Namespacing by version also is pretty "clean." Imagine updating your API in the future without the namespace. You'd have to implement the version in some difficult way (for the end developer) such as during authentication or as a request param or cookie or something ridiculous. Why? Assuming the author is actually using REST, worst case for updating is adding another resource somewhere. There should be no need to update client applications at all.
psadauskas 16y ago
No, this is incorrect. If you have versions in your url, then the same client (eg, with ID 1) has two resource identifiers, /v1/clients/1 and /v2/clients/1. In fact, you have the same resource, /clients/1, but multiple versions of the representation. There's links further down, the one by Peter Williams in particular, that describes a way to do this using content negotiation and the Accept header. Updating is easy, just add the representations to the resources that need the newer version (eg, "views" in rails). Updating with a new v2 in your URI means updating ALL your resources, or writing lots of redundant code to route multiple incoming uris to the same resource. This gets unmanageable, fast. Putting versions in the URI increases complexity, for you, and writers of clients.
- epochwolf 16y ago
  > Putting versions in the URI increases complexity, for you, and writers of clients. Perhaps, but it you have tests for your api you can tell if you break them. Also, there is no reason you need to duplicate code if a section of the api didn't change. You only need to duplicate code if something major changes. Everything else can just be silently routed to the previous version's interface.

qixxiq 16y ago

Thanks, my main problem was that /1/ did look dirty. The /v1/ is much better, and solves the problem.

psadauskas 16y ago
No, please don't do this. Having a version string in the uri is bad. The version means nothing about the resource, and everything about the representation. Please see some of the links further down in the comments for a more detailed explanation.
- qixxiq 16y ago
  I've read through all the links, and whichever way I go its a compromise. I'm choosing the /v1/ route because its a neat solution to the problem, it will work without serious issues and developers understand it easily. Yes its not 110% REST, but I believe its the best solution to my problem. The fact that other major API's are taking the same route (Amazon,Twitter) just enforces the idea.

jmillikin 16y ago

> Namespacing by version also is pretty "clean." Imagine updating your API in the future without the namespace. You'd have to implement the version in some difficult way (for the end developer) such as during authentication or as a request param or cookie or something ridiculous. Why? Assuming the author is actually using REST, worst case for updating is adding another resource somewhere. There should be no need to update client applications at all.

psadauskas 16y ago

No, this is incorrect. If you have versions in your url, then the same client (eg, with ID 1) has two resource identifiers, /v1/clients/1 and /v2/clients/1. In fact, you have the same resource, /clients/1, but multiple versions of the representation. There's links further down, the one by Peter Williams in particular, that describes a way to do this using content negotiation and the Accept header. Updating is easy, just add the representations to the resources that need the newer version (eg, "views" in rails). Updating with a new v2 in your URI means updating ALL your resources, or writing lots of redundant code to route multiple incoming uris to the same resource. This gets unmanageable, fast. Putting versions in the URI increases complexity, for you, and writers of clients.

epochwolf 16y ago
> Putting versions in the URI increases complexity, for you, and writers of clients. Perhaps, but it you have tests for your api you can tell if you break them. Also, there is no reason you need to duplicate code if a section of the api didn't change. You only need to duplicate code if something major changes. Everything else can just be silently routed to the previous version's interface.