Hacker News Reader

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.

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 :)

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.

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.

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.

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.

I think little upgrades happen all the time. And sometimes you need a way to handle those.

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.

I'd argue the former is a lot easier/cleaner to document as well.

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.

If I want to share a link to your API, and you're using accept headers for versioning, how do share that URL?

I think that not only is using accept headers worse, I think it is flat out wrong. That's not what the accept header is for. It's for client specific things only.

The version of the API you need is NOT client specific.

I agree, lots of the Header only people live in a Utopian view of services. Many times these services are needed at the javascript, even plugin (flash, unity, etc) level that don't work well with hidden headers since all they have is a url and a body to make it work. The Academic view of REST is ideal but usage in the real world is difficulty with headers only.

A situation that may arise is people not even aware they are using the wrong version of the api. And which one do you default to? Do you start with the version header always or do you add it into the system on version 2? Then do you require the version header? What happens if you didn't add that in version 1? Which one do you default to the new one? Is it really easier to change one line header than one line service prefix?

It is much much easier when maintaining a large service with more uri focused api routes/actions/verbs at times. It still is defined as rest but has some rpc elements to it. You don't even have to go down to the the model like /api/profile/[uuid]. You can do things like /api/signup /api/login and match those sensible abstractions into the rest api that lives above the model layer. This is always more flexible for minimizing versions and allowing core model changes without having to change much and provides a better consumer experience of the api. This is more of a REST and RPC mix that works well if you have to work with things beyond just backend services such as games, interactives, scripted experiences etc.

I make services fully RESTful when I can but I have to build services that run in scripted clients without easy access to headers, this is where header based versioning is more difficult for the consumer of the service. What I have been doing is looking first for a header, then for the url version, the routes are abstractions anyways so I route those accordingly.

I am liberal in what I accept, conservative in what I send like a good service should be.

Can you elaborate on Unity not working well with headers? I've just started doing some web-stuff with it and found that so far it's been okay.

Services are a bit painful in Unity due to the WWW class: http://unity3d.com/support/documentation/ScriptReference/WWW...

You can use System.Net.* but if you want support across iOS, Android, Web, and Desktop you need to use WWW. Which does not allow you to read or set headers.

I have decent services working with it in JSON using LitJson but it is something they should work on and has prevented me from using headers much in Unity. Even the WWWForm class is weak but there are hidden methods to set and read headers, just they don't work on all platforms yet.

My biggest hiccup in making true REST has actually been in games where web standards and tools are still pretty fresh. So many C/C++/C#/Python/Lua etc proprietary web libs that to make things work you have to have some fallback to uri based states or resources. I typically implement that as a fallback i.e. the version 1 api with headers or url route to the same place.

Ahh yeah, I noticed that things are different from platform to platform. Thankfully we mostly work with the web player rather than the mobile platforms, so it's been pretty painless so far. I'm really loving using coroutines with the web stuff, they fit nicely together.

Thanks for the info :)

It depends what you want to share though. Are you sharing the location of a resource or are you sharing a specific version of that resource?

If I'm viewing some resource in some client that supports version X and I send it to you and you view it in a client that supports version Y (maybe this happens automatically, maybe new versions are in the process of being rolled out, maybe your on the mobile client that hasn't been updated yet) isn't it better that my client gets a representation of it that it can understand?

(I don't think there's one answer for everything, I think both can make sense in different situations. But I think versioning via Headers can be very powerful and can interact well with of RESTful types of things you might want to do, it would certainly make no sense in an RPC style API)

You have swayed me, old man. My next API will use headers for versioning, thank you. As far as the custom verbs are concerned, you might be right, I'll need to think about it when I next need to design an API. Thanks again!