"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.
The main reason people don't want to put the output format into the URL is that URLs are supposed to represent canonical consumer-independent foreign keys in REST.
If you want to put the output format into the URL, I like the .json .xml extensions better. Not that there's anything wrong with the request parameter approach, but the file extension approach also plays nice with user OSes.
Also, I'd ideally use both approaches. So the consumer can pick between using /resouce/1 with an Accept header, or just using /resource/1.xml /resource/1.json directly. The nice thing about the Accept header is that file extensions can have some ambiguity whereas the MIME types are pretty standard and come with RFCs backing them up.
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.
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.
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 :-)
However, not providing the URL of a resource makes assumptions that the consumer knows how to manipulate the data you are providing into a usable URL. If you want your resources to be discoverable and easily consumed by programs which have no knowledge of your specific application, then it can be a good way of doing it.
The point of using URLs is that URLs have a reasonably strong assurance of (global) uniqueness and are somewhat self-documenting -- the same reason XML namespaces are URLs.
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.
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.
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.
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.