Re: [rest-discuss] RESTful representation of nouns?
- On Apr 5, 2006, at 7:17 PM, Dr. Ernie Prabhakar wrote:
> So, services (even those that look like verbs) can be statelessEr, services that "look like verbs" are just confusing -- the question
> resources, too, as long as they aren't implicitly masking -other-
is whether they behave according to the uniform methods applied to them
or not. If you send it a GET, what happens? If you send it a POST,
what happens? How about PUT? As long as the service doesn't go out of
its way to violate some other constraint (such as GET resulting in a
modified resource state), then how it looks shouldn't matter.
>> That's a different beast -- it is a gateway, and it would "look"You mean, if it redirected (or gave 202 response with a link) the client
>> more RESTful simply by choosing a different URI syntax, e.g.
> Ah, I get it. If, for example, it always returned the result as:
> That would be non-RESTful (er, unprincipled? :-), because it doesn't
> actually create real resource.
to a different resource called
right? It would still be RESTful. It just wouldn't be very useful,
since all that identifies is a resource whose state is the most
recently completed conversion. OTOH, if that is the resource that
you happen to want (as in, for example, a monitoring app), then maybe
it is useful enough.
A better way to think of the problem is to work backwards from the
end result. What do you want the state of the system to be at the
completion of N requests (potentially parallel, multiple clients)?
Hint: A RESTful system progresses from one steady-state to the
next, and each such steady-state is both a potential start-state
and a potential end-state. I.e., a RESTful system is an unknown
number of components obeying a simple set of rules such that they
are always either at REST or transitioning from one RESTful
state to another RESTful state. Each state can be completely
understood by the representation(s) it contains and the set of
transitions that it provides, with the transitions limited to a
uniform set of actions to be understandable. The system may be
a complex state diagram, but each user agent is only able to see
one state at a time (the current steady-state) and thus each
state is simple and can be analyzed independently. A user, OTOH,
is able to create their own transitions at any time (e.g., enter
a URL, select a bookmark, open an editor, etc.).
- "Dr. Ernie Prabhakar" <drernie@...> writes:
> Thanks, Nic, Roy. The fog is clearing slightly. :-) The key issueOh that's just nomenclature.
> appears to be:
> On Apr 5, 2006, at 4:26 PM, Roy T. Fielding wrote:
>> OTOH, a translation service like
>> can simply be a POST of file-upload with the response being the
>> converted representation.
>>> However, that doesn't seem very RESTful.
>> Why? POST is RESTful too, when it is used correctly.
> This is what confuses me. My (naive) understanding is that every URI
> represents a noun, that is, a resource. The URL:
> seems like it represents a verb, especially when given parameters:
> or even when given other nouns:
> So, if I read Roy correctly, the service described by that URL is --
> or at least could be -- RESTful. Does this mean that the belief "URLs
> must represent nouns" is a complete myth? Or is there something else
> going on here?
- On Wed, 2006-04-05 at 15:37 -0700, Dr. Ernie Prabhakar wrote:
> I want to provide a web service that, say, converts HTML documentsREST is a model for managing state mutation and transfer in a large
> into various formats. The naive RPC method would seem to be to
> create a special URL string for each type, e.g.:
scale distributed architecture. People often get caught up in whether a
simple conversion activity of this kind is RESTful. They want to add new
URIs to the process and store the result somewhere on the server side.
This is not useful. The starting point for understanding a RESTful
architecture is to think about the state that needs to be retained on
the server side in order to keep things ticking along. In this case and
cases like it, there is no server-side state. Because there is no
server-side state, there are no server-side resources that need to exist
to manage or delimit that state.
The server side does not retain the converted document, so it returns
the document in the HTTP response and forgets about it. If it wanted to
keep the document around for other users of the service to view, it
should store it and represent the stored state as one or more resources.
If it wanted to keep public statistics on the number or types of
documents converted, it should store statistical state and represent the
stored state as one or more resources.
The difference between REST and RPC in the null-state case is not very
wide, especially when we are already constraining ourselves to the
document transfer problem domain. The REST version on the wire looks
>> POST /doc2pdf<< 200 OK
>> (doc document)
<< (pdf document)
The RPC version looks like this:
>> ConvertDoc2Pdf(doc document)<< (SUCCESS, pdf document)
This difference is still important. If we think about what the software
looks like that invokes the request, REST looks like this:
resource = getResource("http://example.com/doc2pdf")
document = resource.POST(document)
RPC looks like this:
docConverter = getDocConverter("http://example.com/doc2pdf")
document = resource.ConvertDoc2Pdf(document)
The RPC approach allows for a lot more of the variation at the code
level to be translated into variation all the way down to the network
level and back up again to the application level on the server side.
REST takes a uniform approach, and only the code that wants to handle
things in a domain-specific way has to do so. The code that gets
messages to that code and directs them back away can be generic and
REST pushes unformity of verbs and message structure at the network
level, and in fact forces us to rethink the application level
significantly. If the uniform version works, why waste time inventing a
more specific or type-safe version? Why validate the whole data
structure down in some network stack when you can transport the raw data
to where it is used and only process what is needed when it arrives? Why
insist on converting a message into an intricate structure of data when
you are just going to reencode it again for transmission or display it
to a user? Why not just retain it as strings until you know what you
will do with it?
The difference between REST and RPC is much clearer when we add
server-side state to the picture and the existence of intermediataries
between server and client. This what Fielding's work is mostly about.
However, there is a world view in REST that says "types don't work on
the network unless everyone understands them". It says that html is
interchangable, but the xml schema you dreamed up yesterday is not. It
says only parse what you need to, and ignore what you don't understand.
It says that the network with all of it's different agencies and
opposing interests is not an environment where traditional
object-orientation works. When we look at what does work, we find
ourselves thinking about compatability in different ways.
REST is not the end goal. It is not an absolute good in it's own right.
It is the benefits of REST that cause use to follow its philosophy. REST
is better than object-orientation for the same reason as we have web
browsers instead of CORBA-browsers. Uniformity is key. Simplicity at the
network level is key. Managing state transparently as resources is
important for its own reasons, but when you are looking at stateless
services such as document converters they really don't come into the
picture that much.