5 ms·

Huh? The whole point of having a version in the URL is so you can roll out a new set of URLs and their corresponding endpoints without touching the old ones.

Huh? The whole point of having a version in the URL is so you can roll out a new set of URLs and their corresponding endpoints without touching the old ones. When v2 of the API comes out, you still support v1. That's no different than using headers. If you sunset or change an API call, the header isn't going to save you any trouble. In fact, since the client now won't get a 404, but rather something else, the cost of debugging goes up pretty substantially.

almost 15y ago
But how do you deal with the partial upgrade scenario? I might want to use a few of the new features in my client code but not have the time to upgrade (and test!) everything just yet. Of course version numbers in URLs can have their place too. But I think they should only really be used in situations where you have upgraded so much that the original URL space just makes no sense. And if you can avoid huge breaking upgrades like that through good initial design then all the better :)
- nirvdrum 15y ago
  The same way you'd handle it on a per-header basis . . . you just use the new API version in the URL where needed. Sorry, I feel like I must be missing something here.
  - almost 15y ago
    You are a little. In a properly RESTful API you simply don't construct URLs most of the time. Instead you follow links. If you change the URL structure you break the links. If that's what you want then a version number in the URL makes sense, but in a properly RESTful API that's probably not what you want. I think for a lot of people the reason they don't see the benefit of things from REST is they try to use them in isolation. You say "this is useless for my RPC style API!" and you are right.
    - nirvdrum 15y ago
      But, if you follow a link and that link is generated by the server, I still don't see how encoding a version number in the URL makes things any harder. FWIW, I've made an effort to follow the purity of it, but the APIs I see that try to do true ReST are insanely obtuse. If you know of any real world case studies where a provider went from "fake" ReST to true ReST, I'd love to read it. The contrived examples are not helping me out in the comprehension department.
- richardlblair 15y ago
  How frequently do you think restful apis move to a new version? Typically you don't release a new version until you need to do significant changes to the entire layout of your api. In which case the old version is not even relevant. With this in mind, you would not want to promote using a new version of the api for one resource with an old version of the api for another resource. Just thinking about it sounds dirty. Your migration strategy should include sufficient time for you to assist your clients to move to your newer versions.
  - almost 15y ago
    I think little upgrades happen all the time. And sometimes you need a way to handle those.
- richardlblair 15y ago
  You also have to consider which of these 2 are easier to understand: api.example.com/v2/account or api.example.com/account Accept: application/vnd.steveklabnik-v2+json And I'm not talking about how easy it is for Developers to understand. I'm talking about how easy it is for Everybody to understand.
  - nirvdrum 15y ago
    I'd argue the former is a lot easier/cleaner to document as well.
Vitaly 15y ago
you are somewhat missing the point. the idea of proper REST is that you NEVER should generate your urls. you take them from the resources. now suppose you have an application that consumes RESTful API. if you do it "wrong" you probably store record ids in your local db and then access stuff from the API by constructing your own urls. a more proper way of doing it is to store the compete resource urls and not just ids. but in this case you have a version update problem. When you release a new version of the app that supports new version of the API you will now need to go over all the stored resource urls and update the version, probably doing some regexing etc. with version in the headers you can store full resource urls and not have to change them every time api version changes.

almost 15y ago

But how do you deal with the partial upgrade scenario? I might want to use a few of the new features in my client code but not have the time to upgrade (and test!) everything just yet. Of course version numbers in URLs can have their place too. But I think they should only really be used in situations where you have upgraded so much that the original URL space just makes no sense. And if you can avoid huge breaking upgrades like that through good initial design then all the better :)

nirvdrum 15y ago
The same way you'd handle it on a per-header basis . . . you just use the new API version in the URL where needed. Sorry, I feel like I must be missing something here.
- almost 15y ago
  You are a little. In a properly RESTful API you simply don't construct URLs most of the time. Instead you follow links. If you change the URL structure you break the links. If that's what you want then a version number in the URL makes sense, but in a properly RESTful API that's probably not what you want. I think for a lot of people the reason they don't see the benefit of things from REST is they try to use them in isolation. You say "this is useless for my RPC style API!" and you are right.
  - nirvdrum 15y ago
    But, if you follow a link and that link is generated by the server, I still don't see how encoding a version number in the URL makes things any harder. FWIW, I've made an effort to follow the purity of it, but the APIs I see that try to do true ReST are insanely obtuse. If you know of any real world case studies where a provider went from "fake" ReST to true ReST, I'd love to read it. The contrived examples are not helping me out in the comprehension department.
richardlblair 15y ago
How frequently do you think restful apis move to a new version? Typically you don't release a new version until you need to do significant changes to the entire layout of your api. In which case the old version is not even relevant. With this in mind, you would not want to promote using a new version of the api for one resource with an old version of the api for another resource. Just thinking about it sounds dirty. Your migration strategy should include sufficient time for you to assist your clients to move to your newer versions.
- almost 15y ago
  I think little upgrades happen all the time. And sometimes you need a way to handle those.
richardlblair 15y ago
You also have to consider which of these 2 are easier to understand: api.example.com/v2/account or api.example.com/account Accept: application/vnd.steveklabnik-v2+json And I'm not talking about how easy it is for Developers to understand. I'm talking about how easy it is for Everybody to understand.
- nirvdrum 15y ago
  I'd argue the former is a lot easier/cleaner to document as well.

Vitaly 15y ago

you are somewhat missing the point. the idea of proper REST is that you NEVER should generate your urls. you take them from the resources. now suppose you have an application that consumes RESTful API. if you do it "wrong" you probably store record ids in your local db and then access stuff from the API by constructing your own urls. a more proper way of doing it is to store the compete resource urls and not just ids. but in this case you have a version update problem. When you release a new version of the app that supports new version of the API you will now need to go over all the stored resource urls and update the version, probably doing some regexing etc. with version in the headers you can store full resource urls and not have to change them every time api version changes.