[jballanc]

Very good read, and thorough. I particularly like the transaction example. It seems like a common idiom that trips people up with REST.

However, I do have a problem with REST that I've been dealing with lately. Specifically, the question of web-hooks. Many services today allow you to pass a URL that they will hit with a POST request whenever something happens. A good example is the GitHub post-receive hook (http://help.github.com/post-receive-hooks/). So, to be a good student of REST, I create an /update resource for the POST (similar to the /transaction example from the article). However, /updates might come in a variety of formats. Not just JSON vs XML, but GitHub vs Gitorious vs Beanstalk vs etc.

So, how do I handle these "formats". Presumably the "Accept" header is out of the question (unless the provider happened to know about MIME's vendor extensions and used them). So then is it acceptable to add a parameter? Use "/update?from=GitHub" for example? Or, is it appropriate to use an extra path element like "/update/GitHub", since the resource really is a "GitHub update", not just a vanilla "update"?

[ianterrell]

There's no right answer, but it's helpful to think about it from a data modeling point of view.

If where the update comes from would be stored as an attribute (i.e. column in the table), use the parameter option (/update?from=GitHub). If, however, they'd be separate types of updates (i.e. separate tables), use the separate URIs (/update/github or /github_update).

This is an analogy, of course, as there's no need for a 1-to-1 resource-persistance mapping, but it's a useful way of thinking about it, I think.

[icebraining]

I don't see what's the problem. Github is the client, so they POST to you the data, so they should include a 'Content-Type' header with the format of such data. Then you can process it accordingly.

[ericmoritz]

What I've seen in the past (mainly from Pylons) is to have an extension on the end of the URL so: /updates/ has a default format say XML and then there's a JSON resource called /updates.json, /updates.txt, etc.

Keep in mind what the R in REST stands for. Each resource is a representation of internal data. You can have multiple representations under different URLs even though they're powered by the same internal data structure. Ideally you'd use the Accept header to do it but sometimes you need to be practical.

[icebraining]

I disagree. A resource is a concept, not a representation of it. A resource in a car dealership is a 'car', not an ' XML document about a car'. One of the examples given by Fielding are "today's weather in LA"; that's not the representation, it's the actual concept.

The concept of internal data structure doesn't enter the picture at all; for all the client knows, the response might even be generated by a monkey typing on a keyboard.

So if you're using different URLs, you're saying that those are different resources, not multiple representations of the same resource.

Sure, it may be useful and 'practicality beats purity', but it's bending the concept.

[stanleydrew]

"Each resource is a representation of internal data. You can have multiple representations under different URLs even though they're powered by the same internal data structure."

False. Each resource is a resource. The representation and the resource are completely independent.

[Omni5cience]

One small nitpick, it's actually the RE in REST