I can see it both ways.

APIv2 is not the same resource as APIv1, so why send it to the same location? Similarly, APIv1/user/1 may very well not contain the same information as APIv2/user/1, so are they really the same resource? They likely refer to the same semantic resource, but if user/1 != user/1, they're not the same from a data standpoint, which is what APIs are generally used for.

It is the same resource. User #1 is the resource. The URL refers to the user, or the user's account. Unless the user creates a new account for use with API v2, the URL should be the same. API v1 and v2 may represent the resource differently, but they are the same resource and should have the same URL.

The correct method for selecting a specific representation is to use the Accept header on the request. For example, if I were requesting somedomain.com/Groxx I could specify Accept: image/png if I wanted a picture of you, or Accept: text/x-vcard if I wanted your contact information.

I believe you are incorrect. From the 1.1 spec:

"The Accept request-header can be used to specify certain media types which are acceptable for the response."

Similar to how when you access some linked data URLs you can specify rdf/xml or rdf/n3 in the Accept header to receive the same data in a specific format.

It's not used to specify whether you want a picture of someone or their contact information all from the same URL.

The REST folk disagree with you. If the picture and the contact information are different representations of the same resource (which is not that much of a stretch conceptually), then they absolutely should be reached at the same URL. At that point, the only way you have left to distinguish what you want is the mime type.

Out of curiosity: how do the REST folk feel about differentiating between resources with urls like /user/1.json and /usr/1.html ? That has been pretty popular, from the little I've seen, and has the advantage of being GET-able with a browser, where header modification is not.

You should use content negotiation for this. The client should have an Accept header that specifies what it wants (which could be "application/json" but really should be something that tells you more about the contents than simply how it can be parsed, such as "application/vnd.mything.MyResource+json" which would be documented in your API with what fields it contains and what it means etc.).

You should also question whether you really need multiple representations for each resource -- in many cases, it's more trouble than it's worth to automatically generate, say, both JSON and XML responses, since it just divides your attention to creating sensible serializations for your API.

If you expect to have clients which cannot modify the headers of their requests, you can support fallbacks like specifying the Accept header in a query parameter. Putting it in the actual URL though is doing a disservice to fully compatible HTTP clients, though.

But if JSON is so inherent to the resource that content negotiation doesn't even matter, it can be fine to include that in the URL, as you might include descriptive filename extensions like ".png" or ".wav" in a URL.

That is still a case of using two URIs to refer to the same resource. If you use one URI per resource, URIs (and bookmarks) can be shared between clients dealing with different media types. Suffixed URIs require mangling to request a different media type.

Clearly it is a pragmatic trade-off and is popular (Google and Twitter do it). The correct answer will be arrived at by considering the total architecture of your application.

As soon as you decide to create two URLs such as /user/1.json and /usr/1.html you are creating two distinct resources. The litmus test for determining if two URLs refer to the same resource is you do a GET on both and only one of them returns a 200 the other returns a 303 with the Location header set to the URL that returned a 200.

That's a good reason to differentiate by header (plus no .jpg vs .jpeg shenanigans in the url). Though I can't say I've ever heard of it being used... I'll have to keep it in mind if I'm ever architecting something that anticipates many different kinds of clients in a large API, however.

Not sure how all REST folk feel, but Roy doesn't have any problem with using the convention of file extensions to indicate resources with different formats. http://tech.groups.yahoo.com/group/rest-discuss/message/1396...

Well, to be clear, he says you should certainly use the Accept header, and if you want to be nice you should provide the formatted URLs as well.

Yeah, but he's explicitly saying that they are different resources with differing types, not the same one with differing types.

Wrong in theory, inevitable (or at least pragmatic) in practice.

If version 1 of a resource is not a subset of version 2 of a resource, and they are not accessing the same record, then they should be separate resources

what 'API' is signaling is what the client is capable of understanding, which is what content negotiation headers are for

I think of it no different to the same resources for web browser consumption (for humans) - I don't place new designs of a website into /design1/ /design2/ etc.

Bear in mind the more things like "Well, you just have to properly use the content negotiation headers" you add to your API, the more the "simplicity" argument of REST goes out the window. I'm not sure I've ever seen really correct use of the content-negotiation headers and claiming it's a solution is dubious... sort of like how I'm still waiting to see proper use of XML Namespaces in the wild. They seem relatively simple to me but the evidence suggests strongly otherwise.

That doesn't make REST "bad", but I think it does start to make the quasi-religious aspect of it less obviously correct.

That's part of my reasoning. Setting proper headers is, yes, more proper... and something essentially nobody does, and many simple API libraries don't support without making using them massively more complicated than prefixing all the URLs with "api/2".

It's a correctness vs usability debate. I'd love to go for correct, but it's extremely painful to enforce in your users in practice.

Using content negotiation, I can--if the server supports it--take the same URI (e.g. http://www.jerf.org/) and pass it to an image viewer to see your face, to my address book to fetch your contact info, etc.

Anything else requires the client knowing how to mangle URIs (e.g. adding /avatar.jpg, /contact.vcf).

I know what content negotiation is; I've never seen it done right. The theory is all beautiful but in practice content negotiation never seems to work right because you never get two people to agree very well on what things are. Another manifestation of the usual semantic classification problem.

It has a dubious track record in X as well. X has been able to do content negotiation for decades for the clipboard but even now it's still spotty and buggy, and that's with everything actually running on the same system. It looks easy. Heck, it looks very easy. It isn't. I can't even tell you exactly why it isn't as easy as it looks (beyond the semantic thing I mentioned above), but the state of the world is pretty clear.

What, realistically, is the difference between knowing how to mangle URIs vs. knowing what content types are available for negotiation?

@awj: if your API does HATEOAS properly, so that your responses inline URLs to other related resources (aiding discoverability of your API through hypertext), then the client can naively take the URLs given to it and cleanly apply Accept headers to them as appropriate.

if you don't want to use content negotiation, then stuff it into query parameters - that is what most API's do (and most that support full content negotiation do anyway)

eg.?v=1&format=xml

but interesting to note is that why is encoding easy to do as part of content negotiation, yet everything else is hard? you never see ?e=UTF-8 or &c=gzip

Many APIs simply specify that the encoding is constant (always UTF-8) so this is not an issue. And many HTTP libraries simply handle the content encoding transparently.

The challenge is some HTTP library APIs commonly used for developing clients offer the following interface: - GET $URL

If you are lucky, then it might also support POST and offer a second parameter for the request body. If are really lucky, there is a way to specify arbitrary methods, but this is fairly rare.

I'm all in favor of supporting fallbacks for more limited clients. But query params are not a great idea since they can prevent caching from happening.

Add a random number to the end as a param to force no-caching.

My point was that it's not a good thing for requests for cacheable content, that might not be cached since you used a query param to access it. Some caches ignore requests with query params since "queries" are often not static.

I completely agree from a pure REST perspective, but if you want developers to be able to quickly get up to speed with your API, requiring them to know the finer points of HTTP and how to manipulate headers within their clients is asking a lot.

Is it though? They are developers, developing applications for the web. I don't think its a huge barrier to expect people to learn the basic protocols, and tools like curl reasonably well.

Do you have full control over the clients which make requests (e.g. it's only AJAX or 3rd party clients written to your api spec - i.e. not browsers making raw requests against some of your urls?)

I backed away from using content-negotiation for an API, part of which would have served data and part content.

e.g. to access file metadata, get /path/to/file with Accept: api/v1 and do a 'normal' GET to get the file contents.

I came across some suggestions that some browsers (recent IE I think, unsure) which suggested that cacheing was broken wrt Accept header - which made me worry that people hitting accessing the resource might get the wrong version.

I don't know if your api is vulnerable to this, if you've come across the problem or have any deployment wisdom to share.

The problem is the data model may change between versions so the URL hierarchy will change. Or instance you may have split customer and staff into separate concepts but later decide your service is better imagined as a network and thus only have users.

How do you do authentication?

With the methods provided via HTTP.