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. 1. 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 and "The Use of Post", a response to same, archived at o Jim Whitehead's list of HTTP-extending possibilities , and the minutes of a WebDAV meeting on the topic; o Discussion on the xml-dist-app mailing list about the correct HTTP response code to use for SOAP 1.2 faults, archived at; o "On the use of HTTP as a Substrate for Other Protocols" an expired Internet-Draft (currently) available at; and a response archived at; 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. 2. The Model In this model, as with software component models such as OpenDoc (), Java Beans v1.2 (aka BeanContext, ), Linda () (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. 3. 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. 4. Author's Address Mark A. Baker Ottawa, Ontario, CANADA. phone:+1-613-261-5172 mailto:distobj@acm.org 5. 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.