But then I read the article and I have to admit this is a pretty egregious break with how REST services are supposed to work.
There's a case to be made for relaxing the definition of REST to accept "just a bunch of URIs" APIs that don't follow the discoverability/transparency conventions of REST. But you can't call "here's a list of verbs" a REST interface.
What you'd want to see in a Rdio REST interface would be:
* /rdio/api/1/playlists * /rdio/api/1/playlist/foo * /rdio/api/1/artist/1 * /rdio/api/1/artist/1/tracks/2
&c &c &c. But, from what I can tell, none of the state inside Rdio's database is mapped to a URI.
It implies that a resource is different just because you are using a newer version of the API.
My own most recent implementations use Accept: and Content-Type to define version compatibility, which is what content negotiation is supposed to be about.
Versioning in the old web API sense meant changing the way the protocol works, and REST will always be REST and the resources will always be resources.
All that is likely to change between 'API versions' is formats, which you negotiate with headers, and adding new fields, which old clients can either ask not to get through content negotiation or can safely ignore.
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.
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.
"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.
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.
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.
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.
That doesn't make REST "bad", but I think it does start to make the quasi-religious aspect of it less obviously correct.
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.
Anything else requires the client knowing how to mangle URIs (e.g. adding /avatar.jpg, /contact.vcf).
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.
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
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 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.
You should disclaim that these URLs could just as well be
* /rdio?q=1&s=63
* /rdio?q=1&s=63-8
* /rdio/4E7?q=1
* /rdio/4E63?q=1
and still be part of a RESTful API.
/rdio/api/1/artist/1/tracks/2
/rdio?api=1&artist=1&tracks=2
Does it change how caching might work?
/rdio/api/1/artist/1/tracks/2/artist/1
I just did a quick check and Django, for example, will just take the second of any duplicated GET params.
http://www.w3.org/TR/REC-html40/interact/forms.html#form-content-type
the idea is that you can build a generic 'REST' client and point it to almost anything that is a 'REST API' and it will work, in the same way we can now with web browsers
a REST client will never figure out /api/1/ - which is why resources go in the path and query parameters go in as, well, query parameters :)
from the server side you are right that modern front controllers and routing can make it all the same (heck, I can route resources to different subdomains, if I want), but a proxy does not know what the front controller logic is (ie. working backwards to what part is what).
That's a stupid idea. REST is built on two things: content types and resource location. The content types indicate the meaning and location of the resources, if the client does not understand the content-type, it can not do anything.
You can not "build a generic 'REST' client and point it to almost anything that is a 'REST API' and it will work", that makes no sense. Indeed, that's not what web browsers do: the driver of the API on a website is the user, not the browser.
> a REST client will never figure out /api/1/ - which is why resources go in the path and query parameters go in as, well, query parameters :)
That's completely irrelevant.
here is what my generic REST client looks like:
* HTTP[s] * JSON * Atom and RSS * Caching layer
some controller login in between all of these. I inherit this to implement simple models and controllers in the client and just tell it which resources I want (like fields in a database)
how is that not a generic client?
for twitter I have classes called users and statuses, with each method defined. for google I have similar classes. this all took minutes for me to get working - I thought that was the entire point of REST?
read the original desertion, sec. 5.2.2 connectors:
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch...
> if the client does not understand the content-type, it can not do anything.
generic doesn't mean understanding the payload, it means understanding the protocol
Also, I believe safari will ignore your caching/expires headers if you use GET params.
Nice urls with http verbs but no hateos is what most "REST" APIs are though.
Sorry sir, I'm not wrong, those would be perfectly valid as part of a REST service, including as alternatives to tptacek's description. Readability of the URLs has nothing at all to do with RESTfullness.
The only thing REST says about the data transmitted (the URL in this case) is that it's the container for the application's state, and most interpretations of this is that the URL is entirely opaque. And indeed, Fielding has suggested/explained this several times.
Those are not REST because they are not resource-based.
Correct REST:
http://blah.com/widget/:id - GET, PUT, POST, DELETE
How does that fit with your /rdio/4E7?q=1 ? Where's the resource? What is the id? What is q anyway?
You can pass parameters with a ? in REST... for example, you might do
GET http://blah.com/resource/123?format=xml
But there's still a clearly identified resource which the GET is performed on.
Sure, technically, by stretching things a bit, you could claim that /rdio?q=1&s=63-8 is a REST GET request for resource id "63-8".
And, technically, you'd be right, much like technically, this is valid C: http://stackoverflow.com/questions/18642/what-is-the-most-un...
But just because it's valid doesn't mean it's in any way good. Those are horrible examples. So no, those URLs could not "just as well" be those nasty examples you give. They could, much more poorly, be those examples, and still be technically valid. By the same reasoning, "Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo" is just as good english as Shakespeare.
Your arguments about nice looking URLs in fact have absolutely nothing to do with REST, except that REST says you must use your transport protocol according to its standards, where appropriate. It says nothing about how URLs should look. I you're talking about the HTTP spec, call it by its proper name please. We don't gain much from conflating different terms like this, it's just a source of confusion.
There is absolutely no difference between path segments and query parameters from the perspective of resource identification.