idnits 2.17.1 draft-baker-http-resource-state-model-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 312 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 4 instances of too long lines in the document, the longest one being 6 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 2001) is 8191 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2616 (ref. 'HTTP') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 7 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet-Draft Mark Baker 2 November 2001 4 An Abstract Model for HTTP Resource State 5 draft-baker-http-resource-state-model-01.txt 7 Status of this Memo 9 This document is an Internet-Draft and is subject to all provisions 10 of Section 10 of RFC2026. 12 Internet-Drafts are working documents of the Internet Engineering 13 Task Force (IETF), its areas, and its working groups. Note that 14 other groups may also distribute working documents as 15 Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six 18 months and may be updated, replaced, or obsoleted by other 19 documents at any time. It is inappropriate to use Internet- 20 Drafts as reference material or to cite them other than as 21 "work in progress." 23 The list of current Internet-Drafts can be accessed at 24 http://www.ietf.org/ietf/1id-abstracts.txt 26 The list of Internet-Draft Shadow Directories can be accessed at 27 http://www.ietf.org/shadow.html. 29 This Internet-Draft will expire in May, 2002. 31 Abstract 33 The documented semantics of HTTP 1.1 methods, in particular POST, 34 are not well understood, as demonstrated by debates such as whether 35 IPP should have used POST or a new method, how to properly bind SOAP 36 to HTTP, and the ever more common use of POST for tunneling new 37 protocols such as XML-RPC. This note attempts to define an abstract 38 model for the state of HTTP URI scheme addressable resources 39 consistent with HTTP 1.1, but hopefully more descriptive. 41 1. Introduction 43 The debate about the proper use of HTTP 1.1 [HTTP] and POST has been 44 ongoing for quite some time. Public debate has yielded many 45 interesting discussions and positions on the topic. Some of these 46 include; 48 o "Don't Go Postal[...]", an objection to the use of POST by IPP 49 archived at 50 51 and "The Use of Post", a response to same, archived at 52 53 o Jim Whitehead's list of HTTP-extending possibilities 54 , and the 55 minutes of a WebDAV meeting on the topic; 56 57 o Discussion on the xml-dist-app mailing list about the correct 58 HTTP response code to use for SOAP 1.2 faults, archived at; 59 60 o "On the use of HTTP as a Substrate for Other Protocols" an expired 61 Internet-Draft (currently) available at; 62 63 and a response archived at; 64 66 This note aims to define an abstract model for the state of 67 resources identified by HTTP URIs, that is consistent with the 68 semantics of the HTTP methods defined in [HTTP], in the hopes that 69 it might help better explain the meaning of the HTTP methods with a 70 holistic approach. 72 2. Goals and Non-goals 74 The primary goal to be met by this model is that it be consistent 75 with the semantics of HTTP 1.1 as defined in [HTTP]. By 76 "consistent", it is meant that it can not be used to describe 77 invalid states or state transitions of an HTTP addressable resource. 79 It is hoped that this model will be more or less complete with 80 respect to HTTP 1.1 semantics, but it is explicitly a non-goal that 81 it be so. By "complete", it is meant that the model be capable of 82 describing all possible states or state transitions of any HTTP 83 addressable resource. 85 3. The Model 87 In this model, as with software component models such as OpenDoc 88 (), Java Beans v1.2 (aka 89 BeanContext, ), Linda 90 () (and other tuple space 91 systems), all resources are modeled as containers for state. 93 The pictorial representation of an HTTP addressable resource is as 94 follows. 96 R 97 +-----+-------------+ 98 | | | 99 | +-+-+ +---+ | 100 POST <>-+-<>| P |<-->| S | | 101 | +---+ | T | | 102 | | A |--+--> GET 103 PUT >--+----------->| T | | 104 | | E | | 105 | +---+ | 106 | | 107 +-------------------+ 109 The perimeter of the resource is entirely opaque. Access to the 110 state is provided only through the HTTP method set (shown here are 111 the methods that operate on the resource directly). Encapsulated 112 within the perimeter is the state of the resource, and a POST 113 processing block "P" whose role is to take action based upon the 114 content that is POSTed to the resource. Possible actions can 115 include modifying the state of the resource, the creation of new 116 subordinate resources, and manipulation of existing subordinate 117 resources (or some combination thereof). The latter two are 118 represented by "R" in the diagram. 120 3.1 Types of resources 122 The following is a non-exhaustive list of some of the different types 123 of HTTP addressable resources, when classified by the way in which 124 changes in state occur. 126 3.1.1 Read only resources 128 Many HTTP addressable resources today, such as the vast majority of 129 HTML web pages, expose only the GET method. These resources are 130 immutable with respect to HTTP clients on the Web, as no means is 131 provided by which one may manipulate the state. 133 +-------------------+ 134 | | 135 | +---+ | 136 | | S | | 137 | | T | | 138 | | A |--+--> GET 139 | | T | | 140 | | E | | 141 | +---+ | 142 | | 143 +-------------------+ 145 3.1.2 Simple state holding resources 147 These resources use the PUT method to explicitly set the state 148 of the resource to the state represented in the body of the 149 invocation. GET is used to subsequently retrieve that state. 151 +-------------------+ 152 | | 153 | +---+ | 154 | | S | | 155 | | T | | 156 | | A |--+--> GET 157 PUT >--+----------->| T | | 158 | | E | | 159 | +---+ | 160 | | 161 +-------------------+ 163 Should the resource not exist, but the web server permit it, the 164 invocation may result in the resource being created. If this is 165 the case, then the initial state of the resource will be that 166 provided in the body of the PUT invocation. Any existing state 167 that may have existed before the PUT, will be unavailable for 168 access through further invocation of HTTP methods on this same 169 resource. 171 3.1.3 Composite state resources 173 Resources exposing POST, when viewed through this model, and due to 174 the definition of POST in [HTTP] section 9.5 as "accepting as a 175 subordinate", present the notion of the state of the resource being 176 composite; a function of the previous state of the resource, as well 177 as the new resource representation being POSTed. 179 In this model, this is represented through the relationship of "P" 180 with the state of the resource. While the job of PUT is to set the 181 state explicitly, POST changes the state relative to the current 182 state, where the relative change is determined by "P". 184 R 185 +-----+-------------+ 186 | | | 187 | +-+-+ +---+ | 188 POST <>-+-<>| P |<-->| S | | 189 | +---+ | T | | 190 | | A |--+--> GET 191 | | T | | 192 | | E | | 193 | +---+ | 194 | | 195 +-------------------+ 197 3.1.3.1 Identity-preserving composite state resources 199 A specialized type of "composite state resource" described in 200 section 3.1.3, this resource has the additional property that "P" 201 assigns a new identity to the representation of the resource being 202 POSTed, while making those resources available through "R". 204 Pictorially, this is identical to 3.1.3. The sole semantic 205 difference being that upon POSTing of the content, a 201 (Created) 206 response status is returned, with a Location header value being the 207 URI of the newly created resource. 209 Bulletin boards or newsgroups are good examples of this type of 210 resource, as they preserve the identity of the messages POSTed to 211 them, thereby making them individually accessible by users of the 212 bulletin board. 214 3.1.4 Processing resources 216 Not all resources exposing the POST method need take full advantage 217 of the expressiveness of the composite state view. Some, like 218 virtually all processors of POSTed HTML forms in use today, are 219 content to maintain no state themselves (thereby making GET 220 unnecessary), but instead simply provide their functionality through 221 the immediate effect of processing the form and returning the results 222 of that processing (with the possibility of creating subordinate 223 resources via "R", though that is also not in common use). 225 R 226 +-----+-------------+ 227 | | | 228 | +-+-+ | 229 POST <>-+-<>| P | | 230 | +---+ | 231 | | 232 | | 233 | | 234 | | 235 | | 236 +-------------------+ 238 4. Comparison with existing method definitions 240 The meaning of GET and PUT are well understood. The view of them 241 implicit in this model is believed to be clearly consistent with the 242 definition in [HTTP]. That is not the case for POST, so this 243 section will compare the authoritative definition with the one 244 suggested by this model. 246 4.1. POST 248 The definition of POST in [HTTP] section 9.5 describes four 249 functions that POST is meant to provide; 251 "- Annotation of existing resources; 253 - Posting a message to a bulletin board, newsgroup, mailing list, 254 or similar group of articles; 256 - Providing a block of data, such as the result of submitting a 257 form, to a data-handling process; 259 - Extending a database through an append operation." 261 The first, annotation, aims to augment the existing state of a 262 resource with an annotated "note". For example, one might annotate 263 an editorial with a comment. This would be represented in the 264 composite state model as adding the POSTed comment to the resource. 265 This may happen with or without the granting of that annotation 266 a new identity. 268 The second function above, of posting a message to a forum, can be 269 easily described with this model. The forum, be it a bulletin board, 270 a mailing list, or similar, is a resource whose state is comprised of 271 all articles that have been posted to it (and perhaps other 272 information). Posting a new message to that resource augments its 273 existing state with the new message. This is likely to be done in an 274 identity-preserving manner, as described in section 3.1.3.1. 276 The third function is described by either section 3.1.4 (if there 277 is no state maintained as a result of the processing), or by 278 sections 3.1.3 or 3.1.3.1, should state be maintained. 280 The fourth function, assuming "append" means, in the case of a 281 relational database, to add a new table, is similarly described with 282 the database as a container for tables. A new table is added 283 to the existing set of tables (the state of that container), not as a 284 replacement, hence the need for POST rather than PUT. 286 5. Author's Address 288 Mark Baker 289 Planetfred Inc. 290 44 Byward Market, Suite 240 291 Ottawa, Ontario, CANADA. K1N 7A2 292 tel:+1-613-795-1818 293 mailto:mbaker@planetfred.com 295 6. Acknowledgements 297 The author would like to thank the following for their suggestions 298 and corrections; Mike Dierken, Jeff Mogul, Mark Nottingham. 300 7. References 302 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 303 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- 304 HTTP/1.1", RFC 2616, June 1999. 306 Appendix A. Changes 308 -01; added ascii art. Found that I needed to simplify the model to make 309 a reasonably simple diagram, so that worked out well despite requiring 310 a rewrite of much of the content. Added a section about consistency vs. 311 completeness.