Loading ...
Sorry, an error occurred while loading the content.

Re: [rest-discuss] RESTful representation of nouns?

Expand Messages
  • Roy T. Fielding
    ... Er, services that look like verbs are just confusing -- the question is whether they behave according to the uniform methods applied to them or not. If
    Message 1 of 12 , Apr 5 8:48 PM
    View Source
    • 0 Attachment
      On Apr 5, 2006, at 7:17 PM, Dr. Ernie Prabhakar wrote:

      > So, services (even those that look like verbs) can be stateless
      > resources, too, as long as they aren't implicitly masking -other-
      > resources?

      Er, services that "look like verbs" are just confusing -- the question
      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"
      >> more RESTful simply by choosing a different URI syntax, e.g.
      >>
      >> http://myconverter.com/pdf/http://example.com/get_it_here.html
      >
      > Ah, I get it. If, for example, it always returned the result as:
      >
      > http://myhost.com/convert?result.html
      >
      > That would be non-RESTful (er, unprincipled? :-), because it doesn't
      > actually create real resource.

      You mean, if it redirected (or gave 202 response with a link) the client
      to a different resource called

      http://myhost.com/convert?result.html

      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.).

      ....Roy
    • Nic
      ... Oh that s just nomenclature. Try: http://myhost.com/mydocument instead. Nic
      Message 2 of 12 , Apr 6 2:02 AM
      View Source
      • 0 Attachment
        "Dr. Ernie Prabhakar" <drernie@...> writes:

        > Thanks, Nic, Roy. The fog is clearing slightly. :-) The key issue
        > appears to be:
        >
        > On Apr 5, 2006, at 4:26 PM, Roy T. Fielding wrote:
        >> OTOH, a translation service like
        >>
        >> /convert?format=pdf
        >>
        >> 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:
        >
        > http://myhost.com/convert
        >
        > seems like it represents a verb, especially when given parameters:
        >
        > http://myhost.com/convert?format=pdf
        >
        > or even when given other nouns:
        >
        > http://myhost.com/convert?format=pdf&uri=http//example.com/
        > get_it_here.html
        >
        > 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?

        Oh that's just nomenclature.

        Try:

        http://myhost.com/mydocument

        instead.


        Nic
      • Benjamin Carlyle
        ... REST is a model for managing state mutation and transfer in a large scale distributed architecture. People often get caught up in whether a simple
        Message 3 of 12 , Apr 6 8:05 AM
        View Source
        • 0 Attachment
          On Wed, 2006-04-05 at 15:37 -0700, Dr. Ernie Prabhakar wrote:
          > I want to provide a web service that, say, converts HTML documents
          > into various formats. The naive RPC method would seem to be to
          > create a special URL string for each type, e.g.:
          > /convert.cgi?format=pdf&document=mydocument.html
          > /convert.cgi?format=doc&document=mydocument.html
          > etc.

          REST is a model for managing state mutation and transfer in a large
          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
          like this:
          >> POST /doc2pdf
          >> (doc document)
          << 200 OK
          << (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
          straightforward.

          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.

          Benjamin.
        Your message has been successfully submitted and would be delivered to recipients shortly.