Internet-Draft                                               Mark Baker
                                                         September 2001

              An Abstract Model for HTTP Resource State
             draft-baker-http-resource-state-model-00.txt

Status of this Memo

   This document is an Internet-Draft and is subject to all provisions
   of Section 10 of RFC2026.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as
   Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six
   months and may be updated, replaced, or obsoleted by other
   documents at any time.  It is inappropriate to use Internet-
   Drafts as reference material or to cite them other than as
   "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire in March, 2002.

Abstract

   The documented semantics of HTTP 1.1 methods, in particular POST,
   are not well understood, as demonstrated by debates such as whether
   IPP should have used POST or a new method, how to properly bind
   SOAP to HTTP, and the ever more common use of POST for tunneling
   new protocols such as XML-RPC.  This note attempts to define an
   abstract model for the state of HTTP URL scheme addressable
   resources consistent with HTTP 1.1, but hopefully more descriptive.

. Introduction

   The debate about the proper use of HTTP 1.1 [HTTP] and POST has been
   ongoing for quite some time.  Public debate has yielded many
   interesting discussions and positions on the topic.  Some of these
   include;

   o "Don't Go Postal[...]", an objection to the use of POST by IPP
     archived at
     <http://www.ics.uci.edu/pub/ietf/http/draft-cohen-http-ext-postal-00.txt>
     and "The Use of Post", a response to same, archived at
     <http://www.ics.uci.edu/pub/ietf/http/draft-debry-http-usepost-00.txt>
   o Jim Whitehead's list of HTTP-extending possibilities
     <http://www.xent.com/FoRK-archive/feb98/0238.html>, and the
     minutes of a WebDAV meeting on the topic;
     <http://www.ics.uci.edu/pub/ietf/webdav/paloalto/minutes.html>
   o Discussion on the xml-dist-app mailing list about the correct
     HTTP response code to use for SOAP 1.2 faults, archived at;
     <http://lists.w3.org/Archives/Public/xml-dist-app/2001Jun/thread.html#15>
   o "On the use of HTTP as a Substrate for Other Protocols" an expired
     Internet-Draft (currently) available at;
     <http://www.ietf.org/internet-drafts/draft-moore-using-http-01.txt>
     and a response archived at;
     <http://lists.w3.org/Archives/Public/xml-dist-app/2000Dec/0061.html>

   This note aims to define an abstract model for the state of
   resources identified by HTTP URLs, that is consistent with the
   semantics of the HTTP methods defined in [HTTP], in the hopes that
   it might help better explain the meaning of the HTTP methods with a
   holistic approach.

   Please send comments initially to the author.  Should the need
   arise, a new mailing list will be established or an existing
   one reused.

. The Model

   In this model, as with software component models such as OpenDoc
   (<http://www-4.ibm.com/software/ad/opendoc/>), Java Beans v1.2 (aka
   BeanContext, <http://java.sun.com/products/javabeans/>), Linda
   (<http://www.cs.yale.edu/Linda/linda.html>) (and other tuple space
   systems), all resources are modelled as containers for state.
   Static HTML (and other) pages are modelled as containers with a
   single (non-composite) immutable piece of state.  Other resources
   exposing GET and PUT, but not POST, are modelled as containers for a
   single piece of mutable state.

   Resources exposing POST, when viewed through this model, and due to
   the definition of POST in [HTTP] section 9.5 as "accepting as a
   subordinate", present the notion of the state of a container being
   composite; a function of the previous state or states of the
   container, in combination with the new entity body being POSTed.

   However, not all resources exposing the POST method need take full
   advantage of the expressiveness of the composite state view.  Some,
   like virtually all processors of POSTed HTML forms, are content to
   maintain no state themselves (while not exposing GET), but instead
   simply provide their functionality through the immediate effect of
   processing the form.  From HTTP 1.1 [HTTP] section 9.5, this use
   would be described by the following "function";

     "- Providing a block of data, such as the result of submitting a
        form, to a data-handling process;"

   This use of POST is consistent with this model, as the container
   would be said to be stateless.

   The other three functions described in 9.5 are;

     "- Annotation of existing resources;

      - Posting a message to a bulletin board, newsgroup, mailing list,
        or similar group of articles;

      [...]

      - Extending a database through an append operation."

   All three of these fit well with the contained state model proposed
   above.  The first, annotation, aims to augment the state of a
   resource with an annotated "note".  The annotation is not performed
   to the exclusion of the existing state, but rather as an extension
   to it.  This would be represented in the composite state model as
   adding the POST entity body to the container.

   The second function above, of posting a message to a forum, can be
   easily described with a containment model; the forum, be it a
   bulletin board, a mailing list, or similar, is the container whose
   state is comprised of all articles that have been posted to it (and
   perhaps other information).  Posting a new entity to that container
   augments the existing state of the forum container.

   The third function, assuming "append" means - in the case of a
   relational database - to add a new table, is similarly described
   with the database as a container for tables.  A new table is added
   relative to the existing set of tables (the state of that
   container), not as a replacement.

. HTTP methods and the Model

   The HTTP methods that require a new explanation of their behaviour
   when viewed through this abstract model are listed below.

3.1 GET

   GET returns a representation of the state of the container.  The
   representation may or may not include information that the state
   is composite or singleton (comprised of a single piece of state).
   For example, a reasonable representation of a bulletin board may be
   the plain text "Mark's Bulletin Board", whereas another
   representation, perhaps in HTML, may include links to the messages
   posted to it.

   The safety of GET, as described in [HTTP] section 9.1.1, is
   described as not changing the state of the resource after the GET
   invocation has completed.

3.2 PUT

   In this model, PUT aims to either explicitly set the state of the
   container to the value provided in the entity body (and to the
   exclusion of the existing state in the container, whether composite
   or singleton), or to create a new resource with the initial state
   set to the state provided in the PUT entity body.

   Resources created or updated by a PUT operation are always initially
   logically a singleton.  This in no way prevents that resource from
   also accepting POST invocations.

3.3 POST

   A POST invocation requests that the provided entity body be added
   to the identified container.  As described above, the resource is
   free to determine how it processes this content, but that processing
   is modelled as a side-effect of the logical inserting of the entity
   body into the container.

   Some resources  more obviously represent a "typical" container (one
   that in some way maintains and exposes the identity of the posted
   entities).  [HTTP] section 9.5 provides for the exposing of the
   identity of provided entity bodies through the use of the 201
   (Created) response code and the Location header.  For example, if a
   new message were posted to a bulletin board, the board would make
   the post available to be accessed by creating a new URL for it and
   return that URL in the Location header of a 201 response.

   Likewise, for resources that do not maintain this identity
   information, the use of 200 or 204 (No Content) is explicitly
   prescribed.

. Author's Address

   Mark A. Baker
   Ottawa, Ontario, CANADA.
   phone:+1-613-261-5172
   mailto:distobj@acm.org

. References

[HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L.,
       Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol --
       HTTP/1.1", RFC 2616, June 1999.