
REST worst practices - rbanffy
http://jacobian.org/writing/rest-worst-practices/
======
lhnz
"HTTP Accept headers (and indeed, use of many fancy headers) are beyond what
most client developers will bother with; including the response format in the
URL with a ".xml" or ".json" is natural and obvious."

That was in a comment by Alex Payne [1] near the bottom. Obviously it's been
quite a few years since he wrote that but it's what I personally think, too.
The extent that many blog articles and comments take REST really adds far too
much complication. Are client-side developers going to understand how to use
your API? Always keep your target market in mind.

Honestly in my mind that's the most important point to take from this article.

[1] <http://al3x.net/about.html>

~~~
bct
Of course we have to be pragmatic about these things - if you have a business
that will live or die based on the success or failure of its API then you have
to make your decision based on that - but there are times that it makes sense
to push the boundaries of what developers are comfortable with, yes? Otherwise
how do we expect things to progress?

~~~
csytan
How would this be pushing the boundaries?

Putting the format in the URL itself is much easier than having to fiddle with
HTTP headers. Not to mention the ability to view API data directly within the
browser is a major advantage in discoverability.

~~~
cstejerean
Using accept headers and browser discoverability do not have to be mutually
exclusive. You can recognize browsers based on user agent and relax the
requirements on accept headers.

------
jiggy2011
I've never been a big REST fan since I'm not sure that shoehorning into HTTP
is a great idea. Seems like using a protocol to solve problems it was never
really intended for.

When I am trying to connect 2 systems I prefer to think about functions rather
than resources , basically create "namespaces" and have something like:
www.myapp.com/api/namespace/function then simply pass all data in using POST
vars and serialize anything more complicated into JSON then just have to other
end return JSON or XML.

Sometimes I will implement a simple header system with some metadata that
should be sent and received with each request.

Getting too worried about POST/GET/PUT seems silly when you can just give your
functions appropriate names.

I prefer to think of this as SOAP extra light.

~~~
joemoon
I suspect you were being downvoted because you don't understand what REST is.
I don't mean this as an insult, most people that talk about REST haven't
actually read Roy Fielding's dissertation. It's a good read; I highly
recommend it.

If you do give it a read, you'll find that his paper isn't about "shoehorning
into HTTP". Actually, the title is pretty clear: _Architectural Styles and the
Design of Network-based Software Architectures_. After doing a great job of
classifying different types of problems and possible solutions to these
problems, Dr. Fielding describes REST as a solution to a particular kind of
problem. To quote (from his blog):

> REST is intended for long-lived network-based applications that span
> multiple organizations. If you don’t see a need for the constraints, then
> don’t use them.

It's fine if you don't want to use REST, but it's obvious from your comment
that you don't understand what REST is or when you might use it.

~~~
jiggy2011
Thanks, I've got that bookmarked and will give it a read when I get some time.

I apologize if I have mis-represented the arguments for/against REST it's just
my experience that a lot of debate around REST seems to be people discussing
which resource something should belong to or whether something should be POST
or PUT.

These sorts of conversations don't really make your software better (I often
feel the same way about OO inheritance).

------
vyrotek
I found that font difficult to read. Especially on top of a flying pony.

As Jare mentioned, I don't like the idea of returning url pointers. But, I
always run into a wall when it comes to deciding how 'deep' to load certain
entities. Does anyone have any interesting approaches to making it dynamic
based on the client request? Or should you just expect the client to make
additional calls to get more data.

~~~
lhnz
You're not the first person to wonder about this. Take a read over this link
[1] maybe?

[1] [http://www.stereoplex.com/blog/mobile-api-design-thinking-
be...](http://www.stereoplex.com/blog/mobile-api-design-thinking-beyond-rest)

~~~
6ren
HN comments on that link: <http://news.ycombinator.com/item?id=3337357>

IMHO, we'll end up with something equivalent to relational algebra. It's the
same problem: providing different representations of one data model (e.g. _how
far to expand links_ is an instance of _denormalizing a flat list_ ). But it
won't happen til providing different representations becomes critical.

~~~
vyrotek
Thanks, very interesting. After reading the discussion about creating a query
language for REST I remembered that Microsoft has something called WCF Data
Services which is basically a SQL-like query language for web services.

Perhaps it is inevitable that we'll eventually need rich query languages to
really deliver what clients want.

~~~
6ren
You may be right about queries.

Though, queries are distinct from relations. They are a database concept,
existing before Codd's relations and also present in NoSQL etc.

I was thinking of the relational concepts that SQL builds on. A way to
separate these concepts is to do the query in two stages: (1) a relational
transformation over the database that denormalises it (joining lists) into a
list containing your answer; (2) a query to extract that answer. (These two
stages are usually redundant; it's just a way to think about it, not how to
write the query, nor for a DB to implement it.)

In a sense, the nesting of REST APIs means they are heavily _de_ -normalised:
to access some data, you have to start at the top and work your way down that
"path". They sometimes have multiple paths to the same data, each one
representing a different denormalisation. The reason this is not "relational"
is because you can only use pre-existing paths; you can't make up your own as
needed.

It's only in a narrow sense that REST APIs are normalised, in that you can
only return one list, with no joins in it.

Looking at WCF Data Services <http://en.wikipedia.org/wiki/WCF_Data_Services>,
those examples aren't (necessarily) relational, just queries, in that there is
no transformation, just selection of a sublist. It's not fair to judge it on
one example though. I found another eg <http://msdn.microsoft.com/en-
us/library/dd728279.aspx> it's analogous. Maybe I'll read the specs in detail
later. :-)

BTW: A query returns a subset of the database. It seems sensible to return
only the subset needed. But there's an odd trade-off in REST: caching more
than a specific query needs is more likely to be useful for the next query (in
effect, it distributes the database over network caches). Bandwidth is
plentiful, so let's return 10KB instead of 10 bytes. But latency is a problem
(IMHO); presently, we need several requests to get the data we want.

I just had an idea: a rich REST API query language (as you say), and _also_
have a client-side query language, and a client-side optimisation engine that
transforms each query into a form that maximises cache hits. e.g. get much
more information than needed, if it happens to be cached nearby. It is like
the query optimisations that databases presently use, but on the client, on
the other side of the expensive network.

You could also over-request, to populate the cache for future queries (your
own and from other users). This might need a lot of tuning, based on actual
usage patterns between users. Existing web-caching experience might guide
this.

Finally: at the moment, I think it's clearly true that different ways of
accessing the same data are not that important. Perhaps they'll never be, for
web-data that is always used in the same way. The "enterprise" needed
relations because they have heaps of apps using centralised data in different
ways (manufacturing, inventory, sales, analysis, etc). However, as the
enterprise moves into the cloud, and as developers start to construct services
out of services (with much deeper integration than a simple mash-up; more like
using remote libraries), this will become extremely important to _some_ users.

whoa, long post. just trying to get my thoughts in order. hope it's of some
use.

------
bprater
Quick note to readers: this article is from 2008.

~~~
fosk
Luckily HTTP hasn't changed since then.

------
jethroalias97
I don't really understand the obsession with using HTTP methods. OP brings up
a good point that using only GET/PUT/POST/DELETE to only represent CRUD is
extremely limiting, but suggests that using even more obscure HTTP methods
would be less limiting? I would argue not only is it limiting, it is also
obscure, what is it about "PUT" that implies update vs. create?

If you look at the twitter API (<https://dev.twitter.com/docs/api>) (commonly
held up as exemplary REST) you will see exactly 2 methods, GET and POST. GET
means no state change other than logging, POST implies state change. This
makes so much more sense because then you can use ?command= and have any
command you want and not have people confused about what it means.

~~~
bct
> commonly held up as exemplary REST

Not by people who know what they're talking about.

> This makes so much more sense because then you can use ?command= and have
> any command you want and not have people confused about what it means.

That's textbook RPC. It's a pattern that works well for many things, but it's
definitely not REST.

~~~
sopooneo
Very sincerely, why is REST an idea worth pursuing?

~~~
jamesbritt
Have you read Roy Felding's REST dissertation?

~~~
virmundi
Yes, I have. To me there seems to be an abstraction leak. Specifically he's
baked HTML into his entire thesis. The idea of interconnecting hypermedia
together is great. It does how ever limit on to using spec'ed hypermedia like
HTML. HTML is one of the only spec media that can link out of the box.

One of his goals was that a document would be able to provide links to another
document in a natural, intuitive way. It is ment to be so intuitive in fact
that the interchange of the document doesn't need a schema or WSDL like
system. HTML has this ability. JSON however doesn't.

If one wants to nest links in JSON, one has to tell the client how those links
will appear. On has to define the structure beyond merely syntaxical
correctness. This is where REST falls down, IMHO.

So I recommend pursuing pieces of REST. But a full HATEOS concept seems to
meaningfully limit on to symantec HTML.

~~~
jamesbritt
_If one wants to nest links in JSON, one has to tell the client how those
links will appear. On has to define the structure beyond merely syntaxical
correctness. This is where REST falls down, IMHO._

Then use HTML. Or some other representation with known link semantics.

I don't see how failures or shortcomings of JSON indicate a problem with REST.
They are orthogonal; JSON has nothing to do with REST, it's just a
serialization format some people like.

~~~
randomdata
I am not sure who wrote it, or where to even find it again, but I have read
exactly what virmundi is referring to. It is possible he is confusing authors.

The long and the short of the document was that a REST client _must_ be able
to navigate the entire API when given just a single endpoint URL, much like
you can navigate an entire website just by entering the homepage URL into your
browser, but without the dependance on HTML.

The leap the document made, and what virmundi seems to be referring to, is
that a REST client that speaks, say, JSON is not enough to traverse any random
service, as everyone will provide a completely different JSON representation
of their data. When you start hardcoding site-specific keys in which to find
the action descriptions, you lose all of the flexibility the author claimed
REST would provide in the first place.

~~~
virmundi
Part of my comment is backed by the implicit constraint on HATEOS,
<http://en.wikipedia.org/wiki/HATEOAS>.

I've downloaded the original thesis. I'll look there to see what's mentioned
about the hypermedia linking process.

------
Jare
I'm not sure about the rest of the stuff, but the idea that you should return
links instead of IDs strikes me as horrible. Your REST API should define a way
to ID the objects it deals with, and a way to access information about those
objects. An example of such information would be an API to return the URL for
a photo given its ID (expecting the client to construct that URL is certainly
brittle).

My personal best practice would be to build batching facilities for your APIs.
Batching is incredibly important when your application data grows.

~~~
wmf
In REST there is no need for IDs at all. There is only URLs; the URL of an
object is the only way to refer to it.

~~~
sashthebash
I almost completely agree, but a problem I often encounter in REST API design
is: how to do searches?

Let's say we have an "Event" Resource and it belongs to a "Location" Resource
and the Event belongs to "Category" Resources. If you want to provide an
endpoint to search events with a GET requests and filter based on Location and
Categories (which are identified by URLs) you can end up with really long
query strings.

/events?location=URL1&categories[]=URL2&categories[]=URL3&categories[]=URL4&...

This is not only ugly, it can bring up problems on both clients and servers.

Any suggestions on how to handle this?

~~~
icebraining
Why use GET instead of POST? Just POST a document with the parameters to
filter, and the server creates a new resource with the search results and
returns its URL to the client, which can then GET it.

~~~
boucher
There's really no need to create a separate URL; it's reasonable for POST
requests to contain response bodies.

------
Tangaroa
Another worst practice is referring to JSON as the "REST file format" as
ESRI's products did two years ago when I last worked with them.

------
fakecoder4life
The thing I wonder about with stuff from jacobian.org is whether the guy can
actually write ANY code. My gut feeling is he a guy that has very good
political skills and somehow used this a way to mind control geeks.

Basically, I can't understand why anything he writes is somehow hackernews
worthy...is he self-promoting?

~~~
masklinn
> The thing I wonder about with stuff from jacobian.org is whether the guy can
> actually write ANY code. My gut feeling is he a guy that has very good
> political skills and somehow used this a way to mind control geeks.

So you have no idea who he is, apparently did not look for any information
(such as his gh page or his being one of Django's lead devs) and decided he
was all about "political skills". And somehow failed to realized the article
linked above is 3 years old.

> Basically, I can't understand why anything he writes is somehow hackernews
> worthy...

But that does not prevent you from judging him as "a politician who can't
write code". Nice.

> is he self-promoting?

He "self-promotes" 3 years old articles by not even posting them himself? What
sense does that make?

Here's an idea: maybe he wrote good content, and he's not too bad a writer.
But you know, if you want to insult him you could at least do it to his face,
he's a member on HN after all: <http://news.ycombinator.com/user?id=jacobian>

~~~
fakecoder4life
is it possible that being a Django "lead dev" is a political position? I
noticed he is a literature major at UC Santa Cruz, a school that doesn't give
actual letter grades.

Maybe he is the ultimate "trick baby"....or is Django something we cannot
question on hacker news. I think this dude is full of shit myself.

~~~
rbanffy
And you say that hiding behind a throwaway id... very brave of you.

Instead of insulting people, try to learn to properly discuss ideas. Learn to
point out failed reasoning and to defend your own concepts with sound
reasoning or facts. Once you start, it's not that hard and it makes the
discussion so much more useful. We have limited time. We shouldn't waste it.

~~~
masklinn
For what it's worth and though I shamefully fed it, this seems to be a troll
account created solely to insult a few people of the python community: only
three comments insulting Jacob here and Jesse Noller in an other thread. I'm
pretty sure the guy is not looking for discussion, he should just be flagged
and ignored.

~~~
rbanffy
Thanks, masklinn, for the nice detective work.

