

Dudes, this is so not REST - mccutchen
http://jens.mooseyard.com/2011/03/dudes-this-is-so-not-rest/

======
mikeryan
After reading the title I was all set to come in here and complain about
"REST" Nazis and make some comment about how real life situations tend to
supersede strict adherence to conventions.

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.

~~~
tptacek
I came here to say the same thing. For those of you who aren't going to bother
reading the Rdio API spec (I did, because there's something I want to hack
together with it): the whole API is literally just a single URI that accepts a
"method" param, where the method is a list of verbs like "get all tracks in
this playlist" or "add a friend".

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.

~~~
nikcub
I don't like API version numbers in the 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.

~~~
Groxx
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.

~~~
nikcub
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.

~~~
jerf
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.

~~~
enduser
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).

~~~
jerf
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.

------
jcromartie
Actually, what the blog author is talking about is a resource-oriented
architecture (ROA), which is typically implemented in a RESTful fashion over
HTTP but has recently been conflated with REST itself. ROA != REST.

~~~
shubber
Just to amplify: there's more than a pedantic difference beteen the two. REST
has a lot of serious advantages related not only to application architecture
and interoperability but also to system architecture and scalability. There's
a lot in the original REST dissertation about removing shared state and
enabling cacheability.

The crowd that mistakes ROA for REST (I think) sees the stuff in REST that
relates directly to development and gets excited - but the stuff related to
making their app scale, they ignore. If you don't want to learn a little bit
about everything, at least follow the rules that relate to the things you
don't know about.

~~~
KevBurnsJr
"we'll make the URLs pretty, but we'll ignore the stuff about statelessness."

------
vegashacker
Why does it matter? Ok, I agree that you probably shouldn't label something
with an incorrect term, but does not having more than one URL, and not using
the different HTTP methods really make a difference in terms of programmer
usability?

I personally find that sometimes I have trouble spotting the "oh! I forgot to
make it DELETE instead of GET" bugs. When the parameters of the API are all in
the url and/or query, it feels better encapsulated.

(promise I'm not flaming, and I fully expect to get told, yes it matters, and
here's why! ;)

~~~
tptacek
Yes. In this case, it makes an enormous difference. Your application can't
just go to rdio/api/1/artist/whatever to look up the tracks for an artist; it
has to make a SOAP-style request for the tracks for a given artist. This isn't
a style nit.

~~~
masklinn
It can probably be argued to be: you can't just go to
rdio/api/1/artist/whatever, but you can get the exact same thing via RPC
calls.

I often think that, via REST APIs and content negotiations, API can become
browseable and self-descriptive but I've yet to see _any_ example of such a
thing. Furthermore, just because an API is restful doesn't mean it's well-
designed, and doesn't mean it has descriptive APIs (the artist's track could
just as well be in rdio/api/64D89CAC?q=42, that wouldn't inherently make the
API non-restful)

~~~
deno
> I often think that, via REST APIs and content negotiations, API can become
> browseable and self-descriptive but I've yet to see any example of such a
> thing.

It should be trivial with AtomPub/GData/OData APIs. REST itself is not
specific enough for that.

------
mortice
I once worked on a project where 'REST' was synonymous with 'putting query
data into the URL before the query string', and this was done so that the
webserver could cache the response.

I died a little inside every time I wrote a 'Restful' servlet there.

------
thurn
This is an increasingly common extension of the REST paradigm. Google ran into
a number of problems with the restrictions of REST, so their new APIs all work
this way. See their justification in this video:
[http://www.google.com/events/io/2010/sessions/how-google-
bui...](http://www.google.com/events/io/2010/sessions/how-google-builds-
apis.html)

~~~
megrimlock
Slide 87 of the pdf has the best summary, but the main thing w/r/r REST is
that get/put of entire resources can be too heavy.

1\. custom methods let you get/put specific fields, without having to transfer
the whole thing or split resources up as you add new methods.

2\. custom methods avoid needing to implement complex or heavy state mutations
on the client. the example was rotating an image 90 degrees; you wouldn't want
to download an entire full-res image to your wimpy battery-powered phone,
rotate it, and re-upload it when you can just do that on the server.

(... of course this should just update some orientation metadata instead of
resampling the image -- it's just an example)

~~~
_sh
As for your point 2, if you consider a REST resource as a collection of
fields, you can update it without custom verbs:

    
    
      GET /resources/picture/orientation => 0
      PUT /resources/picture/orientation?value=90
    

REST is not so much about a simple API, but a scalable service. Custom verbs
break scalability.

------
hoop
'''Maybe we should just give up on the term REST, since it’s become so diluted
as to mean nothing more than "HTTP API that’s not as hard to use as SOAP"?'''

To be fair, I thought we were at this point already. It seems safer to assume
that when one advertises a "RESTful API" they are really referring to a "REST-
like" API which basically means "Hey, we don't use sessions!"

While I believe that the term is already diluted to that point, I still think
it's valid to point out when people are doing it wrong.

~~~
wahnfrieden
It's diluted for sure, but it still carries a strict interpretation that is
worthwhile and that some of us are still using.

My main problem with its dilution is that it's usually totally meaningless --
usually other terms like RPC or just plain old "proper HTTP" accurately
describe what someone is calling REST, to there point where its supposed
RESTfulness can be nothing more than for the sake of buzzword compliance.

------
csears
REST is now just a generic term for any HTTP API that's not SOAP. Like Xerox
and Kleenex, the popular usage is technically incorrect, but in practice, it
doesn't matter.

Most REST API consumers today are more like CURL than a web browser. In the
CURL-like case, the RPC pattern works quite well. HATEOS and other browser-
centric REST ideas often just don't fit naturally into a simple API consuming
app. People need to move on.

~~~
russellperry
"Like Xerox and Kleenex, the popular usage is technically incorrect, but in
practice, it doesn't matter."

The integrity of some acronyms is worth defending. I wouldn't want 'ACID'
diluted to mean anything less than its strict definition, and I think the same
holds true for 'REST'. The benefit of these distinctions is twofold: 1) we
encourage the advantages of good RESTful practices and 2) we can communicate
consistently without spending unnecessary effort qualifying our meaning. If
REST means 'Anything but SOAP' then at some point we'll have to come up with
another shorthand for 'Real REST' or spend lots of time re-stating the
principles of REST every time we need to communicate architectural strategies
that use them.

I should be able to say 'Singleton' or 'MVC' or 'ACID' and know that there is
enough integrity to those ideas that a competent coder will know what I mean
without me having to pseudo-code or UML the concept for them. The same should
hold true for REST.

------
davidmathers
"It screams RPC. There is so much coupling on display that it should be given
an X rating."

\-- Roy Fielding @ [http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hyperte...](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven)

------
extension
This sort of API is not RESTful at all, regardless of whether the method name
is in the HTTP header or a form variable. It's still an application-specific
protocol that requires out-of-band knowledge to use. REST resources are
supposed to be self-describing, which doesn't make much sense for an API like
this. RPC is what is required here, so just tunnel RPC over HTTP in whatever
way is most practical. And don't call it REST.

If you want a bucket of cold water over the head on this topic:
[http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hyperte...](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven)

------
hinathan
Instead of fetishizing REST for its own sake, how about appreciating an HTTP
API that can be used (read/written) with a browser via form elements and
hrefs?

~~~
figure8
I completely agree with you. There will always be a contingent of developers
who believe enforced standards trump simplicity. As we see here, when the
CORBA then SOAP crowd realized they'd lost that fight, their ilk started
judging other projects by adherence to strict API structural definitions like
formal "REST". That said, I do believe this constant dialog between ad-hoc
simplicity and rigid standards is good for the industry; in each area,
accepted practice evolves to meet the needs of its current application.

~~~
deno
REST is as simple as it gets. You could make that argument if someone were to
advocate using REST outside of HTTP. But HTTP _is_ inherently REST, so you
should have a good reason to _not_ use REST rather than the other way around.

~~~
masklinn
> REST is as simple as it gets.

It is not. It's quite complex actually. And I'm betting what most people who
believe they have a clue think of "REST" is actually "RPC over pretty urls".

~~~
deno
But that's just because of a general ignorance of how HTTP protocol works. If
someone were to be explained, how it should work from the beginning, I'm sure
they'd have no problem with grasping the subject.

Actually some Google engineers do a very good job of explaining how AtomPub
and GData APIs work just with short Youtube videos.

------
mccutchen
We might be getting close to this point: _Maybe we should just give up on the
term REST, since it’s become so diluted as to mean nothing more than “HTTP API
that’s not as hard to use as SOAP”?_

This is a shame, because RESTful APIs are (for me, anyway) usually a joy to
build and to use.

~~~
deno
There's already a specific term for the kind of API that rdio has: RPC. Remote
Procedure Call.

I mean, come on, how can you say you have REST (with R standing for
Representational) if you have section called “Methods” in your API
documentation. HTTP API sounds okay, but in fact their API is not even HTTP
specific (actually, it abuses HTTP).

------
MatthewPhillips
I've worked with APIs that return XML containing one node, which contains
escaped XML. So when I read something like this it doesn't seem that bad.

~~~
wahnfrieden
That's fine. Just don't call it REST. Does buzzword compliance matter so much?
Call it what it is: RPC.

------
Stormbringer
In the Java world REST was pretty cool for about 18 months. And then
annotations came out, and instead of all the JAX-RPC bondage and discipline,
you get JAX-WS, where to make something a webservice literally all you need to
do is shove the @WebService annotation on it and you are good to go†.

All the WSDL and SOAP crap gets auto-generated for you. Thereby eliminating in
a single stroke REST's advantage.

Now, it is true that there is some stuff†† you can do with SOAP that you can't
do with JAX-WS, but really unless you like making life difficult for yourself
then don't.

Especially for a big Java to Java solution there doesn't seem to be any
compelling reason to go with REST anymore. Even if _everything_ you do maps
exactly to the four SQL ops (select, update, insert, delete) it is still just
as easy to use the annotation as it would be to use REST.

†C# has something similar I think.

††Example: JAX-WS is limited to what you can do with a method and parameters
in Java. In your SOAP schema you can specify for instance that the array you
get passed shall have between 1 and 3 members, two is okay but 4 is right out.
Whereas in Java (and hence JAX-WS) if you have an Array parameter, you can't
specify that it must have a certain number of elements in it.

~~~
Ingaz
The simplest method of creating SOAP-services is use of SQLServer SOAP
Endpoint.

Just one line for SOAP from stored procedure or function.

Is it beautiful? I don't think so. SOAP remains SOAP, ugly remains ugly.

------
robbles
The author gives WebDAV as an example of a good standardized REST API.

Is adding new HTTP methods (like PROPFIND, MOVE, COPY, etc.) considered to be
RESTful? I always thought you were supposed to structure all actions around
the main 6, and add extra functionality in the data payload or query
parameters.

------
adolph
Summary:

Rdo: "Yeah, we have POST!"

Thought Palace: "What about the rest?"

------
whackberry
FTA > In fact this is why Tim Berners-Lee used the word “method” in the HTTP
protocol in the first place.

Does he have a source for this? Coincidentally I had just read the HTTP 0.9
the other day and I didn't see "method" being used that way at all. I think
method, in HTTP, just means "a means to retrieve / put data", not method in
the object oriented sense.

------
ianloic
Yep, our API isn't really technically REST in the classical use of the term.
We changed some of our wording and made a blog post:
<http://developer.rdio.com/blog/read/No_REST_for_the_wicked>

------
thomasfl
This is a good example of a REST anti pattern. It can be easier to understand
REST, when you know what it's not.

------
mkramlich
So it's an HTTP-based API rather than true REST. Move on. _shrug_

------
amitraman1
Yes! Yes! Yes!

"HTTP API that’s not as hard to use as SOAP"

My current employer calls our API ...

... RESTful like .

------
TorKlingberg
I am all with you on using GET and POST properly, but is there any REST API
that actually uses PUT and DELETE?

~~~
wahnfrieden
Take a look at Sun Cloud API. It's one of the best examples.

For APIs that need regular browser support, it's fine to add fallbacks like
query params to specify PUT or DELETE. But these are hacks.

------
sabat
_It’s object-oriented, where objects are identified by URLs_

I'm not so sure that "object-oriented" is the right term here, but totally
agree with the premise: this isn't REST. It's more like XML-RPC Jr.

------
tariq
how about calling it RESTish? <http://news.ycombinator.com/item?id=2242162>

~~~
masklinn
How about calling it what it is, namely RPC?

~~~
wahnfrieden
Yes. The terms "RESTish" or "lower REST" are just a way to stay buzzword
compliant, not actually a way of elucidating anything. They're catch-all
buzzword substitutes for more accurate terms.

They're particularly bad since a strict interpretation of REST can still be
valuable, yet it makes REST itself seem overly nebulous and fluffy.

People advocating terms like "RESTish" or looser definitions of REST seem to
think that REST is an ultimate goal of any decent web API. It's not, REST
doesn't need to be used everywhere, your API isn't crap if it's not REST. So
stop calling it REST like you're embarrassed to admit it's "just" RPC.

(Sorry for ranting in reply to you -- you seem to get it)

