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

REST is not just file storage

Expand Messages
  • Roy T. Fielding
    There seems to be a common thread with most posts here. People have been busy modeling everything as a resource and now they want to know how to do everything
    Message 1 of 7 , May 5, 2008
    View Source
    • 0 Attachment
      There seems to be a common thread with most posts here. People
      have been busy modeling everything as a resource and now they
      want to know how to do everything in a PUT or DELETE instead of
      any of the other HTTP methods. That is wrong. That is thinking
      HTTP is just a "Save as..." dialog.

      REST is not limited to GET, PUT, and DELETE. Anyone who says so
      is just making things up as they go along. REST is limited to the
      client being told what to do next by the current state of where
      they are now, aside from the entry point(s) we call a bookmark.
      That is feasible because the set of methods is uniform, not because
      it is limited to CRUD. POST is an equal party in the REST interface,
      particularly when actions are being applied to the resources that
      are a composite of multiple source resources. So is PATCH.

      Doing RESTful actions on multiple resources is no different from
      selecting multiple tunes in iTunes and using the info dialog
      to set certain properties across all selected tunes. It is a UI issue.
      The UI builds a set of actions to perform and then performs them
      in whatever way is most efficiently provided by the set of resources
      being operated upon. If those resources (or, rather, the index to
      those resources) say they can be operated upon as a group by POST
      of a selection form, then so be it -- that is perfectly RESTful
      even without the benefit of per-resource cache invalidation.
      Likewise for PATCH or PUT to a meta-resource, or PROPPATCH to a
      WebDAV resource, it is RESTful if there is some engine described
      by a representation provided by the origin server that instructs
      the client on what to do next.

      The goals are to remove coupling and maximize the number of
      reusable resources.

      ....Roy
    • wahbedahbe
      Yes! And it s not just here -- this same take on REST can be found all over the web. For some reason, people just don t appreciate the hypermedia engine aspect
      Message 2 of 7 , May 5, 2008
      View Source
      • 0 Attachment
        Yes! And it's not just here -- this same take on REST can be found all
        over the web. For some reason, people just don't appreciate the
        hypermedia engine aspect of REST. Leaving it out is a bit like a joke
        without a punchline -- an elaborate setup that's missing that final,
        key element.

        Unfortunately, the misinformation dominates the available (mostly
        online) literature. Many seem to venture into REST without spending
        the time to understand or even read your thesis, and then off they go
        blogging about the wonders of these CRUD-based "RESTful" interfaces,
        and it just gets worse.

        There is a real lack of good introductory information though. On your
        blog, you criticized the RESTful Web Services book of not stressing
        the hypermedia engine enough -- and its pretty much the best thing out
        there.

        Worse, people haven't been given any good examples to learn from.
        Well, we obviously have the HTML web -- but unfortunately there hasn't
        been too much success building automated clients that can do much more
        than follow links with GET. And machine-driven agents are why most
        people are interested in REST. There's the Atom Publishing Protocol,
        but let's face it -- while RESTful, it's really not THAT much more
        than a big "Save As..." dialog is it? There's nothing wrong with that,
        but it doesn't really help deal with the confusion.

        An excellent example IMHO that's been mostly ignored is CCXML
        (http://www.w3.org/TR/ccxml/). It's an XML language for controlling
        phone calls (redirecting them, joining them to conferences, etc.).
        Unfortunately, it has a steep learning curve for those not familiar
        with telephony, especially if your goal is to learn from it rather
        than use it. Its basic model -- a state machine that interacts with a
        set of local resources via events and with resources via HTTP -- is
        fairly attractive though. Fortunately, this model is being distilled
        into SCXML (http://www.w3.org/TR/scxml/) which I think is very
        promising. Disclaimer: I used to participate in the W3C working groups
        behind these formats so I'm obviously biased.

        Even though both these languages use HTTP pretty minimally (actually
        it's quite abysmal; they could be improved a lot in this regard) they
        do a much better job of decoupling the client and the server than most
        of the ROA/CRUD stuff that gets thrown around. And they are
        particularly interesting because they aren't focused on presenting
        information to a human user. Rather, they provide an event-based
        controller that acts as an adapter between client side resources and
        network resources. This is a very compelling architecture for
        machine-driven agents, one that meets the constraints of REST, but
        likely wouldn't be deemed "RESTful" by many.

        The community desperately needs a good set of authoritative tutorials
        and examples that gets the whole picture across. Something that's easy
        to digest and gets you off on the right foot. Something that's edited
        and/or approved by the experts (you know who you are ;-). The
        information is out there, but you really have to dig to get to it. And
        it's impossible for the newcomer to filter out the misinformation.
        There has to be a way to make it easier...

        Andrew Wahbe

        --- In rest-discuss@yahoogroups.com, "Roy T. Fielding" <fielding@...>
        wrote:
        >
        > There seems to be a common thread with most posts here. People
        > have been busy modeling everything as a resource and now they
        > want to know how to do everything in a PUT or DELETE instead of
        > any of the other HTTP methods. That is wrong. That is thinking
        > HTTP is just a "Save as..." dialog.
        >
        > REST is not limited to GET, PUT, and DELETE. Anyone who says so
        > is just making things up as they go along. REST is limited to the
        > client being told what to do next by the current state of where
        > they are now, aside from the entry point(s) we call a bookmark.
        > That is feasible because the set of methods is uniform, not because
        > it is limited to CRUD. POST is an equal party in the REST interface,
        > particularly when actions are being applied to the resources that
        > are a composite of multiple source resources. So is PATCH.
        >
        > Doing RESTful actions on multiple resources is no different from
        > selecting multiple tunes in iTunes and using the info dialog
        > to set certain properties across all selected tunes. It is a UI issue.
        > The UI builds a set of actions to perform and then performs them
        > in whatever way is most efficiently provided by the set of resources
        > being operated upon. If those resources (or, rather, the index to
        > those resources) say they can be operated upon as a group by POST
        > of a selection form, then so be it -- that is perfectly RESTful
        > even without the benefit of per-resource cache invalidation.
        > Likewise for PATCH or PUT to a meta-resource, or PROPPATCH to a
        > WebDAV resource, it is RESTful if there is some engine described
        > by a representation provided by the origin server that instructs
        > the client on what to do next.
        >
        > The goals are to remove coupling and maximize the number of
        > reusable resources.
        >
        > ....Roy
        >
      • dev
        ... At first I thought that using non-standard methods like PATCH would be wrong as it wouldn t allow for serendipitous reuse . But what you are saying is
        Message 3 of 7 , May 6, 2008
        View Source
        • 0 Attachment
          >want to know how to do everything in a PUT or DELETE instead of
          >any of the other HTTP methods. That is wrong. That is thinking
          >HTTP is just a "Save as..." dialog.

          At first I thought that using non-standard methods like PATCH would be
          wrong as it wouldn't allow for serendipitous reuse . But what you are
          saying is using non-standard methods is fine as long as there is an
          engine which can tell the client what to do next. That engine should
          support introspection via GET. Is this correct ?

          Regards
          Devdatta

          2008/5/6 Roy T. Fielding <fielding@...>:
          >
          >
          >
          >
          >
          >
          > There seems to be a common thread with most posts here. People
          > have been busy modeling everything as a resource and now they
          > want to know how to do everything in a PUT or DELETE instead of
          > any of the other HTTP methods. That is wrong. That is thinking
          > HTTP is just a "Save as..." dialog.
          >
          > REST is not limited to GET, PUT, and DELETE. Anyone who says so
          > is just making things up as they go along. REST is limited to the
          > client being told what to do next by the current state of where
          > they are now, aside from the entry point(s) we call a bookmark.
          > That is feasible because the set of methods is uniform, not because
          > it is limited to CRUD. POST is an equal party in the REST interface,
          > particularly when actions are being applied to the resources that
          > are a composite of multiple source resources. So is PATCH.
          >
          > Doing RESTful actions on multiple resources is no different from
          > selecting multiple tunes in iTunes and using the info dialog
          > to set certain properties across all selected tunes. It is a UI issue.
          > The UI builds a set of actions to perform and then performs them
          > in whatever way is most efficiently provided by the set of resources
          > being operated upon. If those resources (or, rather, the index to
          > those resources) say they can be operated upon as a group by POST
          > of a selection form, then so be it -- that is perfectly RESTful
          > even without the benefit of per-resource cache invalidation.
          > Likewise for PATCH or PUT to a meta-resource, or PROPPATCH to a
          > WebDAV resource, it is RESTful if there is some engine described
          > by a representation provided by the origin server that instructs
          > the client on what to do next.
          >
          > The goals are to remove coupling and maximize the number of
          > reusable resources.
          >
          > ....Roy
          >
        • Roy T. Fielding
          ... Serendipitous reuse comes from providing a URI for everything that is of value as a resource (even when that value is not used by your own application).
          Message 4 of 7 , May 6, 2008
          View Source
          • 0 Attachment
            On May 6, 2008, at 1:06 AM, dev wrote:
            > >want to know how to do everything in a PUT or DELETE instead of
            > >any of the other HTTP methods. That is wrong. That is thinking
            > >HTTP is just a "Save as..." dialog.
            >
            > At first I thought that using non-standard methods like PATCH would be
            > wrong as it wouldn't allow for serendipitous reuse.
            >

            Serendipitous reuse comes from providing a URI for everything that is
            of value as a resource (even when that value is not used by your own
            application). As long as you are using GET for retrieval, then reuse
            will be there. POST can be used in serendipitous ways as well, but
            there are no special tricks in HTTP that make POST actions any more or
            less reusable than any form of RPC/RMI -- we simply rely on the
            media type telling us where to POST to describe the service on the fly
            (late-binding is always better than compiled contracts because any
            late binding can self-identify its own expected "contract").
            More importantly, it is very hard to see that it is safe to reuse
            a POST in unforeseen ways, whereas that is required of GET.

            Even when POST is used to perform the equivalent of GET, for whatever
            crazy reason, it can be compensated somewhat by responding to the POST
            with 303 or 201 + Location, or simply by limiting the 200 response
            content to a list of references to reusable resources.

            PUT, DELETE, and PATCH are essentially editing operations on the
            mapping from URI to representation. In many cases, those will translate
            down to what is essentially file-like CRUD operations, but only for
            a very small subset of resources. If you think of it in MVC terms,
            then those operations should only be active when M=V. It is the
            application's job to determine when M=V; i.e., which models are
            capable of being edited by representation exchange, which models can
            be edited by indirect action on some other resource(s) (e.g., edit
            links in Atom or wiki post forms on pages), and which models can't
            be edited at all via HTTP.

            In any case, there are plenty of RESTful services that do nothing
            but GET and POST. The key is how those methods are used, not what
            methods are used. To give a specific example, what makes a wiki
            more or less RESTful is almost always determined by how it (ab)uses
            GET and sessions -- whether it uses PUT or POST for editing pages
            is sugar topping in comparison.

            > But what you are
            > saying is using non-standard methods is fine as long as there is an
            > engine which can tell the client what to do next. That engine should
            > support introspection via GET. Is this correct ?
            >

            I wouldn't go as far as saying all "non-standard methods" are fine.
            The methods still need to be standardized in order for intermediaries
            to take part in the conversation and for generic clients to know how
            to follow the instructions. The methods still need to be resource-
            neutral
            in terms of semantics. However, for actions that do not benefit
            from intermediaries (non-retrieval actions), the focus of REST is to
            make the results visible as reusable resources after the action is
            complete rather than worry too much about the standard-ness of any
            non-GET method name.

            ....Roy
          • Assaf Arkin
            ... Anyone remembers Royce and the Waterfall Model? In a 1970 he criticed the waterfall approach and argued for iterative development. Most people s take
            Message 5 of 7 , May 6, 2008
            View Source
            • 0 Attachment
              On Mon, May 5, 2008 at 2:17 PM, Roy T. Fielding <fielding@...> wrote:
              > There seems to be a common thread with most posts here. People
              > have been busy modeling everything as a resource and now they
              > want to know how to do everything in a PUT or DELETE instead of
              > any of the other HTTP methods. That is wrong. That is thinking
              > HTTP is just a "Save as..." dialog.
              >
              > REST is not limited to GET, PUT, and DELETE. Anyone who says so
              > is just making things up as they go along. REST is limited to the
              > client being told what to do next by the current state of where
              > they are now, aside from the entry point(s) we call a bookmark.
              > That is feasible because the set of methods is uniform, not because
              > it is limited to CRUD. POST is an equal party in the REST interface,
              > particularly when actions are being applied to the resources that
              > are a composite of multiple source resources. So is PATCH.

              Anyone remembers Royce and the Waterfall Model? In a 1970 he criticed
              the waterfall approach and argued for iterative development. Most
              people's take from that piece was to just go and do more waterfall.
              After all, if someone wrote about it, and it was published in the
              Proceedings of IEEE, then it must be good, right?

              When I talk to people about REST, almost always the conversation
              revolves around one of two interpretations of REST. That "REST is not
              SOAP": the catchy sound byte is the battle between REST and SOAP, and
              if you're not doing SOAP then you must be doing REST. Or that "REST
              is CRUD": developers intuitively grasp how to do SQL or EJB or insert
              your favorite data access layer, over HTTP; data storage on the cloud
              is the Next Great Thing, coupled with all the easy-CRUD frameworks
              playing catch up to Rails.

              The EJB over HTTP interpretation works because you can explain it in a
              Twitter message, grok it in seconds, try it out on a handful of Web
              2.0 services, and prototype something with your new shiny framework of
              choice. I don't see that changing by bringing up hypermedia as the
              something of something else. If you can't explain it in one short
              sentence, don't be surprised when some other short explanation catches
              on.

              I tried "REST is links and forms", and that one works quite nicely,
              because it starts we something that people grasp, and everything else
              like GET vs POST, caching, naming resources, moving beyond HTTP, all
              fall nicely into place. If someone asks how do to this or that, you
              start with "why don't you show me your links and forms?"


              -- Assaf
              http://labnotes.org



              > Doing RESTful actions on multiple resources is no different from
              > selecting multiple tunes in iTunes and using the info dialog
              > to set certain properties across all selected tunes. It is a UI issue.
              > The UI builds a set of actions to perform and then performs them
              > in whatever way is most efficiently provided by the set of resources
              > being operated upon. If those resources (or, rather, the index to
              > those resources) say they can be operated upon as a group by POST
              > of a selection form, then so be it -- that is perfectly RESTful
              > even without the benefit of per-resource cache invalidation.
              > Likewise for PATCH or PUT to a meta-resource, or PROPPATCH to a
              > WebDAV resource, it is RESTful if there is some engine described
              > by a representation provided by the origin server that instructs
              > the client on what to do next.
              >
              > The goals are to remove coupling and maximize the number of
              > reusable resources.
              >
              > ....Roy
            • dev
              ... Along with addressability , isn t a uniform interface necessary too[1] ? I am not saying uniform interface means that PUT should always do this , DELETE
              Message 6 of 7 , May 7, 2008
              View Source
              • 0 Attachment
                > Serendipitous reuse comes from providing a URI for everything that is
                > of value as a resource (even when that value is not used by your own

                Along with addressability , isn't a uniform interface necessary too[1] ?

                I am not saying uniform interface means that PUT should always do this
                , DELETE should always do this to the resource , so that the client
                can guess what method to call on a resource directly . That should be
                done via a nudge from the application itself via a hypermedia engine.
                The 'serendipity' should come by first a GET on the resource and then
                based on the representation returned do something.

                But what I /AM/ saying is that those 4 methods only should be used ,
                and not the other methods. How would using PATCH still be a part of
                uniform interface ?


                > application). As long as you are using GET for retrieval, then reuse
                > will be there.
                Thats what I meant by 'you introspect with a GET' , and then decide what to do.

                > PUT, DELETE, and PATCH are essentially editing operations on the
                > mapping from URI to representation. In many cases, those will translate

                You mean , POST is used for invoking some functionality of the actual
                underlying application , while PUT/DELETE are for manipulating the
                interface model ? (and if the M=V then that would also imply changing
                something in the application )

                Reading your first post again, I think I am still not clear on the last line :

                >it is RESTful if there is some engine described
                >by a representation provided by the origin server that instructs
                >the client on what to do next.

                Do you mean that the representation returned from the origin server
                has a set of (hypermedia) links
                that allow it move about in the application?


                Regards
                Devdatta


                [1] http://steve.vinoski.net/pdf/IEEE-Serendipitous_Reuse.pdf
              • Andrew S. Townley
                ... My understanding (and I m sure I ll get corrected if I m wrong) is that the interface is uniform due to the way the service tells the client what
                Message 7 of 7 , May 7, 2008
                View Source
                • 0 Attachment
                  On Wed, 2008-05-07 at 15:37 +0530, dev wrote:

                  > But what I /AM/ saying is that those 4 methods only should be used ,
                  > and not the other methods. How would using PATCH still be a part of
                  > uniform interface ?

                  My understanding (and I'm sure I'll get corrected if I'm wrong) is that
                  the interface is uniform due to the way the service tells the client
                  what operations it can perform, not that the operations are particularly
                  part of a particular set. Of course the client needs to understand what
                  to do if it gets some hypermedia serving an equivalent function as an
                  HTML form that says "invoke operation(PATCH) on URI" instead of "invoke
                  operation(GET) on URI", but, as I see it, the way that the operation and
                  its parameters is expressed using hypermedia is really where the
                  uniformity comes in, e.g. the service has a uniform way to describe the
                  available state transitions away from the current resource. The
                  mechanics of actually performing those operations is secondary because
                  it boils down to support for the underlying transfer protocol used.
                  Probably not as important now, but may be extremely important for
                  anything after HTTP/1.1.

                  > >it is RESTful if there is some engine described
                  > >by a representation provided by the origin server that instructs
                  > >the client on what to do next.
                  >
                  > Do you mean that the representation returned from the origin server
                  > has a set of (hypermedia) links
                  > that allow it move about in the application?

                  Again, my understanding is that this is the essence of "hypermedia as
                  the engine of application state", so I think the answer is "yes".

                  ast
                  --
                  Andrew S. Townley <ast@...>
                  http://atownley.org
                Your message has been successfully submitted and would be delivered to recipients shortly.