

REST worst practices - luckystrike
http://jacobian.org/writing/rest-worst-practices/

======
snorkel
"Further, the output format ought to be determined hubristically from the HTTP
Accept header; that lets clients select output formats without resorting to
ugly ?format=xml crap."

I have to disagree. First of all, do not assume anything based on mime types
the browser (or whatever user agent) asked for. It's very hacky to expect
consumers to mess with their user agent's Accepts header to get the response
format they want. Specifying the desired format such as ?format=xml is simple,
clear, specific, and reliable. I prefer default format be XML and other
formats available by passing a format parameter.

The REST of article has some good suggestions. I made a pun there. Did you
catch it? "REST of the article". Because it's about REST? That's comedy gold.

~~~
seldo
This sentence also stood out to me, but mainly because he used "hubristically"
when he meant "heuristically".

Unless he really thinks that determining what format to send the response in
from the HTTP header is an overwhelmingly arrogant move...

~~~
jacobian
Heh, d'oh. Fixed; thanks.

~~~
jjs
> ought to be determined _huristically_

Third time's a charm! :P

------
seldo
The idea that links to foreign keys (IDs) should be in the format of a URL is
an interesting idea. In practice, I don't think it's a good idea since it
makes assumptions about what API consumers want to _do_ with the data -- it
assumes they want to fetch it, when there could be several other actions they
could take.

Including the link URL as a template in a separate field is a potential
possibility, but (a) it will add a ton of duplicated data to collections
results, (b) it relies on your consumer parsing and inserting the field into
their call every time, which if they care about the efficiency of their own
code they're probably not going to do, so you don't get any added flexibility.

~~~
LogicHoleFlaw
It was my understanding that representing foreign keys as URLs is a basic
principle of REST. The URL is the canonical representation of the object in
question. The URL is needed for all actions upon it, not just fetching.

~~~
seldo
If you're being strict about REST, you're absolutely right. But I have spent a
lot of my career building REST APIs for people and from that I've learned that
what most people mean when they say "RESTful" is "easy to use, and easy to
read". Arguably including the foreign keys as URLs makes it easier to use, but
I'm arguing that it's not :-)

------
igorgue
Django Piston (<http://bitbucket.org/jespern/django-piston/wiki/Home>) is a
project that makes easy to implements all "good" REST practices in Django. In
other words they don't do the things that Jacob says are bad or ugly.

------
benreesman
I'll keep my personal opinion of REST to myself, as I've had that flamewar
before and it isn't particularly productive.

But I will share something a colleague just said because it made me laugh: "I
have kids dude, so I'm used to hearing people argue vigorously about stupid
stuff. This whole REST dicussion has the feeling of a bunch of nerds arguing
about which Star Trek movie is worst."

Again, I don't really want to get into a discussion with you REST fanatics,
hopefully the upvotes from people who chuckle will cancel out the downvotes
from the REST people.

------
noss
See also, [http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hyperte...](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven)

------
davidmathers
Don't miss the great response from Alex Payne in the comments about "best
practices" vs real word realities.

------
minalecs
maybe its my lack of understanding, but can't you define type by accept
header, such as application/json, or application/xml. Also depending on your
api, you could follow the whole one model one request, or you could return
more, as the author of the api, what is limiting you .. when you say
/hero/superman, it can return profile, and powers and more .. why not ?? you
should do whatever you feel your user base needs... just because a posted
speed limit says go 35, doesn't mean that you can't go 40.

