Feedback

Elliotte Harold wrote:

Possibly confusing, some of your examples do not actually match what the HTTP server sees:

PUT http://myserver/myaddressbook/johndoe/mywedding.img

PUT http://myserver/myaddressbook/johndoe/workphone

are both inaccurate. The server will see

PUT /myaddressbook/johndoe/mywedding.png

PUT /myaddressbook/johndoe/workphone

I was trying to convey the actual operation done by the client.  For instance, doing a PUT on http://myserver/myaddressbook/johndoe/workphone (request body omitted).  Do you know of a better notation?

I'd just say what it does in a way that doesn't look at all like an actual HTTP request, possibly in a non-code font in a regular text paragraph. Then show the actual HTTP request. Anything halfway in between is just going to confuse.

----

Benjamin Carlyle wrote:

* In REST it is likely that multiple resources will be served from a

single defined set of state, ie a service. For example an object or a

set of objects are likely to have several resources associated with them

that act as the network interface to these objects. I would suggest that

instead of "Each Dream service (being) a resource", each dream service

should make a set of resources available.

SteveB 19 Feb 2007: language was corrected

----

S. Mike Dierken wrote:

This introduction will cover some basics of HTTP [...]

You probably should mention that REST does not mean "HTTP" and mention why

you chose to talk about HTTP (like, it display many of the characteristics

described by the REST style).

SteveB 10 Jan 2007: since the context of the article is REST web-services it should be OK to combine both

Compare this to mounted network drives, whose names have no way of being

resolved by a recipient.

Huh? I would need an explanation of how that's similar, so this could be

clarified or replaced with something more understandable.

SteveB 10 Jan 2007: clarified the example

Similarly, we can also query a complex resource, such as a blog, to get

parts of the data:

This isn't querying a resource, it simply /is/ a resource. You might say

something like a resource can represent complex information like "all the

blog comments after a particular timestamp written by 'anonymous' ". The

client doesn't need to know just how complex things could be for the server

- it just does a GET.

SteveB 19 Feb 2007: for the purpose of this documentation, I assume that a resource is identified by a URI up to its query string.  Hence, http://foo/bar and http://foo/bar?query identify the same resource.  I've added language to make this clear.

All data resources support GET, but not all behavioral resources do.

What's a "data resource" compared to "behavioral resource" - you might

rephrase that to say that some resources are read-only.

SteveB 19 Feb 2007: patterns make the distinction clear.

While a GET request cannot have side-effects, it can return only parts of

the resource.

This means that GET is both an atomic read, as well as a query operation.

This is not correct - GET does not return parts of a resource. At least, not

the way you suggest with query terms.

You might want to describe that a GET could be a simple static file or a

complex query operation - both are simply retrievals of data.

SteveB 19 Feb 2007: well, here we'll just have to limit the scope to how Dream identifies resources and operations on them

If two PUT operations occur simultaneously, one of them will win and

determine the final state of the resource.

What happens to the other one? I think that both win. REST gives rise to all

sorts of win-win situations.

SteveB 19 Feb 2007: while both may succeed, a resource can only be in one state and that state is defined by that last operation that succeeded.

In the case of two simultaneous DELETE operations, one of them may fail

since the resource

will have already been deleted.

Nope. It's important to realize that /both/ succeed. There should be no

error code. The protocol does not assume a "locate object or fail, activate

object or fail, invoke method on object" - it just says "make sure the

resource is gone when the request completes". An absent resource is just as

gone as a recently deleted one.

SteveB 19 Feb 2007: this has been corrected.

The POST operation is very generic and no specific meaning can be attached

to it.

There is meaning associated with it, and unique aspects regarding

repeatability and caching.

SteveB 19 Feb 2007: without meaning, no optimizing assumptions w.r.t to repeatability or caching can be made; thus both statements are true.

In general, use POST when only a subset of a resource needs to be modified

and it cannot be accessed

as its own resource; or when the equivalent of a method call must be

exposed.

Rather than suggesting a generic method calls is appropriate via POST,

perhaps you could narrow it down to modification operations that don't fit

into PUT or DELETE.

SteveB 19 Feb 2007: agreed, but it's already saying that with the "it cannot be accessed as its own resource."

We can also update individual properties of the entry, because they are

exposed as nested resources.

There isn't a concept of a 'nested resource'. And this example only works

because the server implements it that way, it's not part of REST or HTTP (or

even most Web server frameworks unfortunately). And there is no requirement

that the second resource that is the 'property of the entry' use a URI with

paths - it could just as easily be:

 PUT http://myserver/myaddressbook/johndoe?prop=27

 PUT http://myserver/myaddressbook/phones...ndoe&type=work

SteveB 19 Feb 2007: "nesting" is a generic concept, while it cannot be generalized, the statement already limits itself to "nested resource." Although this concept might be specific to certain resources, it does not invalidate the statement or its usefulness.

----

Bill Venners wrote:

I just read the article. It is quite nice, but isn't there one problem with it? Statements like:

GET     /resource     Retrieve the entire resource.  Query parameters may be available to retrieve only parts of the resource.

And:

For example, the following GET operation retrieves the definition of the EightBallService (Dream SDK/Tutorials/8-Ball):

GET http://myserver/host/blueprints/Mind...ghtBallService

This operation will return the following XML document:

<blueprint>

...

</blueprint>

To obtain the output in JSON, simply add the dream.out.format=jsonp query parameter to the URI:

http://myserver/host/blueprints/Mind...t.format=jsonp

({

...

}

My understanding as that URIs in HTTP are opaque, and that each URI references a *different* resource. Therefore:

http://myserver/host/blueprints/Mind...t.format=jsonp

Does not retrieve a different format of the resource at:

GET http://myserver/host/blueprints/Mind...ghtBallService

It retrieves a different resource. In other words, my understanding of the HTTP spec's use of the term "resource," and also Roy's use of it in his thesis, gives no special meaning to a question mark in a URI.

I do exactly what you are describing, because the user trying to figure out our information architecture from the URIs may indeed apply special meaning to that question mark. (In my model for URI design, the part of the URI left of the question mark defines a conceptual thing from the user's perspective, but not a resource from the HTTP or REST perspective.) So I think it makes sense to do what you're doing from a usability perspecitve, but my feeling is your article may be inaccurate when it says you can apply query parameters to a URI to get a subset or different format for a single resource.

SteveB 19 Feb 2007: this has been addressed by clarifying the language.  In both cases, a "representation" of the resource is retrieved and not the resource itself.  Also, text was added to clarify that the article assumes that URIs up to their query part, identify resources uniquely.

----

Bill Venners wrote:

> I'm not sure I'm following your point. Are you saying I could express

> it better without using the term 'resource'? But what should it be

> called then?

Yes, since you're attempting to explain REST, and the term "resource"

I think means in REST what it means in HTTP, which is very specific.

I CC'd the list because I wasn't 100% sure of that, so see if anyone

has a different definition of "resource" in the HTTP and/or REST

context.

SteveB 19 Feb 2007: clarified the article by using "resource" to describe the server side thing and "representation" to describe what goes across the wire.

> If I understood you correctly, you are stating the

> "http://server/recipes" and

> "http://server/recipies?dream.out.format=jsonp" identify two different

> resources, because they are different URIs. Is that correct? And if

> yes, is there a less strict interpretation that would weaken this

> equality relationship to only apply to the scheme, authority, and path

> components of the URI (i.e. excluding user name, password, path

> parameters, query parameters, and fragment)? I think such an equality

> relationship would be useful and feel intuitive. And would certainly

> be deserving of a name by which it could be referred to.

>

I agree. Our URIs in our new architecture do a similar thing. But I

don't call them "resources." I call them whatever they are: article,

forum post, etc. I also do the "container" pattern a lot as you named

it. You could call these things (for lack of a better word) resources

if you want, but it seems like overloading the term in an article

trying to explain REST. You might try coming up with a better name

than "thing" that isn't "resource."

On the other hand, I'm not really sure it's an article about REST if

you're going in that direction. It may be more an article about user-

friendly web information architecture and URI design. At least that's

how I think of those patterns you described, that the URI to the left

of the question mark defines one "thing" in the *user's* mental model

of your website. The stuff to the right of the question mark the user

can think of as stuff that customizes their view of the "thing." But

those different URIs giving views of the same "thing" are not

representations of resources in the HTTP terminology, which is where

I believe REST lives. In that worldview each different URI is a

different "resource" that may have multiple "representations."

For example:

http://www.artima.com/articles

Is a view of the collection of articles that shows the most recently

published 15 articles.

http://www.artima.com/articles?p=7

Shows page seven of the same list, the collection of articles shown

in most-recently-published order. Here the "thing" in the user's mind

is the collection of articles. But from the HTTP perspective, from my

reading of the spec, these are two distinct resources each of which

could have multiple representations, not two representations of the

same resource.

Anyway, my feefback is simply to be very clear on the terms in your

article, and since it is an article attempting to explain REST, try

to use "resource" and "representation" as it is used in the HTTP spec

and Roy's paper. (And I welcome clarification from others if I'm not

understanding these terms correctly.)

SteveB 19 Feb 2007: added language to that effect.

----

Benjamin Carlyle wrote:

> Let's look at the following use case (for Dream):

> 1) we have a URI that points to an XML document (e.g.

> http://server/recipes)

> 2) doing a GET on this URI gives us the document verbatim

> 3) doing a GET?dream.out.format=jsonp gives us the document in a

> different representation (sending 'Accept: application/json,

> text/javascript' should trigger the same conversion)

> 4) doing a GET?dream.out.select=/list/entry[author='Julia Child']

> gives us the XML sub-document that matches the xpath expression

>

> I would say that #2-#4 all refer to the same "resource", but chose to

> represent it in different ways.

Here is the vocabulary I use:

#2-#4 all refer to different _resources_ becuase they have diffent uris.

>From the client perspective no relationship can be drawn between these

resources without additional information, ie some sort of hyperlink. It

is perhaps peculiar that resources don't always exist within the server.

Sometimes they are implemented as objects in their own right, but other

times a single object might offer many resources or vice versa.

Resources themselves exist between clients and servers as a shared

interface concept.

These different resources all _demarcate_ related _application state_ on

the server side. Each resource selects a piece of state (ie information)

in the server that might be part of a single object, might be a whole

object, or might be parts of several different objects. If we were

talking about databases a resource might demarcate a subset of rows

across multiple tables.

When we GET a resource, we retrieve a _representation_ of that resource.

This representation is a document that contains the information

demarcated by the resource. The same resource might choose to return its

state in several formats, providing several different representations of

its state. Different representations may offer different levels of

semantic fidelity. For example, atom data could be returned in a simple

csv or text file... but then the information couldn't be used in a news

reader client application.

SteveB 19 Feb 2007: added language to that effect.

---

Bill Venners wrote:

> Hmm. Let me ask a pointed question to see if I understand this. By

> Roy's definition of resource as mapping, is it true that:

>

> http://www.artima.com/articles

>

> and

>

> http://www.artima.com/articles?p=4

>

> Must at any time t return the same representation for those two URIs

> to refer to the same resource?

>

No, Content negotiation could lead to even

http://www.artima.com/articles alone returning different representations

to different clients at the same time.

I think it's helpful to stop trying to imagine what the resource is. See

http://cafe.elharo.com/web/rest-is-l...tum-mechanics/

All you know is representations, nothing more.

----

Bill Venners wrote:

Yes, in hindsight perhaps the HTTP spec shouldn't have said that

about the query parameters. But Steve can declare in his article that

for any system that implements his Entity pattern as he defines it,

all URLs that are identical up to the query parameters refer to the

same resource. And in my case, I can say that in my architecture an

article is a resource, and that any article URIs that are identical

up to the query parameters refer to the same article resource.

SteveB 19 Feb 2007: added language to that effect.

----

Bill Venners wrote:

So at any time t, the values in the set must be the same for any two

URIs that claim to reference the same resource. Therefore page four

and page one of my articles list are two different resources as the

term resource is used in REST. And therefore I think that given

Steve's "REST for the rest of us" article is attempting to explain

REST, he should perhaps not say things like:

GET /resource Retrieve the entire resource. Query parameters may

be available to retrieve only parts of the resource.

For lack of a better term, and since "resource," "entity" and

"representation" are taken, I might call the conceptual thing an

"object" and its query-param-accessed variations "views." /articles

refers to a conceptual collection of articles object at Artima, and

you can get different views of that object by adding query

parameters, such as /articles?p=4 or /articles?t=java. Each one of

those views is a different resource in REST terms.

SteveB 19 Feb 2007: using the terms "resource" and "representation" should be sufficient to cover all cases.

----

Elliotte Harold:

> I am trying to understand the definition of resource in the HTTP and

> REST context, that's all.

I find it useful to work in a Copenhagen-like model in which there is no

resource, and no need to define it. All we can observe are the URIs and

representations. Based on these we can predict server behavior without

ever understanding what a resource really is. Unlike quantum mechanics,

it's not true that there really aren't any hidden variables, but it's

very useful to act as if there aren't any.

----

Benjamin Carlyle wrote:

I think this is exactly the point, though. HTTP's REST replaces the

doSomething concept with a "make something so" concept. If you think

about it, all doSomething can be modelled this way. Instead of "make

this kind of state transition", just "make your state this". You have to

get into specific examples to see how this works. The first example of

starting or stopping a function is the same as setting a running

resource to false or true.

----

Paul Haugen wrote:

* resource state: state of a resource, known only by its

representations. If you PUT, you change the resource state.

* application state: ("hypermedia is the engine of...") described by

hyperlinks in representations of resources from the server, navigated

by the client.

* session state: in REST, known only to the client.