idnits 2.17.1 draft-sayre-atompub-protocol-basic-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.2b on line 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 663. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 635. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 642. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 648. -- The document has an RFC 3978 Section 5.2(b) Derivative Works Limitation clause. If this document is intended for submission to the IESG for publication, this constitutes an error. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- 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 (October 3, 2005) is 6779 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'AtomFormat' ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) -- Possible downref: Non-RFC (?) normative reference: ref. 'XOXO' Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Sayre 3 Internet-Draft October 3, 2005 4 Expires: April 6, 2006 6 The Atom Publishing Protocol (Basic) 7 draft-sayre-atompub-protocol-basic-02.txt 9 Status of this Memo 11 By submitting this Internet-Draft, each author represents that any 12 applicable patent or other IPR claims of which he or she is aware 13 have been or will be disclosed, and any of which he or she becomes 14 aware will be disclosed, in accordance with Section 6 of BCP 79. 15 This document may not be modified, and derivative works of it may not 16 be created. This document may only be posted in an Internet-Draft. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on April 6, 2006. 36 Copyright Notice 38 Copyright (C) The Internet Society (2005). 40 Abstract 42 This memo presents a protocol for using XML (Extensible Markup 43 Language) and HTTP (HyperText Transport Protocol) to edit content. 45 The Atom Publishing Protocol is an application-level protocol for 46 publishing and editing Web resources belonging to periodically 47 updated websites. The Atom format is documented in the Atom 48 Syndication Format (draft-ietf-atompub-format-11.txt). 50 Editorial Note 52 To provide feedback on this Internet-Draft, join the atom-protocol 53 mailing list . 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 58 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 4 59 3. The Atom Publishing Protocol Model . . . . . . . . . . . . . 5 60 4. Collections . . . . . . . . . . . . . . . . . . . . . . . . 9 61 5. Media Collections . . . . . . . . . . . . . . . . . . . . . 12 62 6. Service Outlines . . . . . . . . . . . . . . . . . . . . . . 14 63 7. Selection . . . . . . . . . . . . . . . . . . . . . . . . . 16 64 8. Security Considerations . . . . . . . . . . . . . . . . . . 18 65 9. Normative References . . . . . . . . . . . . . . . . . . . . 18 66 Author's Address . . . . . . . . . . . . . . . . . . . . . . 19 67 A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 20 68 Intellectual Property and Copyright Statements . . . . . . . 21 70 1. Introduction 72 The Atom Publishing Protocol (APP) is an application-level protocol 73 for publishing and editing Web resources using HTTP [RFC2616] and XML 74 [W3C.REC-xml-20040204]. 76 2. Notational Conventions 78 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 79 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 80 document are to be interpreted as described in [RFC2119]. 82 The APP namespace is "http://purl.org/atom/app#". This specification 83 refers to it by using the prefix "pub", but that prefix is arbitrary. 85 The terms 'URI' and 'IRI' are shorthand for the identifiers specified 86 in [RFC3986] and [RFC3987]. 88 3. The Atom Publishing Protocol Model 90 The Atom Publishing Protocol operates on collections of Web 91 resources. All collections support the same basic interactions, as 92 do the resources within the collections. The patterns of interaction 93 are based on the common HTTP verbs. This section illustrates the 94 editing cycle for Atom entries. 96 o GET is used to retrieve a representation of a resource or perform 97 a read-only query. 99 o POST is used to create a new, dynamically-named resource. 101 o PUT is used to update a known resource. 103 o DELETE is used to remove a resource. 105 3.1 Collections 107 The APP groups resources into "Collections", which are analogous to 108 the "folders" or "directories" found in many file systems. 110 3.2 Discovery 112 To discover the location of the collections exposed by an APP 113 service, the client must locate and request a Service Outline 114 (Section 6). Service Outlines describe the layout of an APP service. 116 Client Server 117 | | 118 | 1.) GET Outline URI | 119 |------------------------------->| 120 | | 121 | 2.) Service Outline Doc | 122 |<-------------------------------| 123 | | 125 1. The client sends a GET request to the Service Outline Resource. 127 2. The server responds with a Service Outline Document containing 128 the locations of collections provided by the service. The 129 content of this document can vary based on aspects of the client 130 request, including, but not limited to, authentication 131 credentials. 133 3.3 Listing 135 Once the client has discovered the location of a collection in the 136 outline, it can request a listing of the collection's membership. 137 However, collections might be extremely large, so servers are likely 138 to list a small subset of the collection by default. Clients that 139 wish to exercise greater control over the subset returned by the 140 server can check for an "app:select" template (see Section 7). 142 Client Server 143 | | 144 | 1.) GET to Collection URI | 145 |------------------------------->| 146 | | 147 | 2.) 200 OK, Atom Feed Doc | 148 |<-------------------------------| 149 | | 151 1. The client sends a GET request to the Collection's URI. 153 2. The server responds with an Atom Feed Document containing a full 154 or partial listing of the collection's membership. 156 3.4 Authoring 158 After locating a collection, a client can add entries by sending a 159 request to the collection; other changes are accomplished by sending 160 HTTP requests to its member resources. 162 3.4.1 Create 164 Client Server 165 | | 166 | 1.) POST to Collection URI | 167 |------------------------------->| 168 | | 169 | 2.) 201 Created @ Location | 170 |<-------------------------------| 171 | | 173 1. The client sends a representation of a member to the server via 174 HTTP POST. The Request URI is that of the Collection. 176 2. The server responds with a response of "201 Created" and a 177 "Location" header containing the URI of the newly-created 178 resource. 180 3.4.2 Read 182 Client Server 183 | | 184 | 1.) GET or HEAD to Member URI | 185 |------------------------------->| 186 | | 187 | 2.) 200 OK Atom Entry | 188 |<-------------------------------| 189 | | 191 1. The client sends a GET (or HEAD) request to the member's URI. 193 2. The server responds with an Atom Entry document. 195 3.4.3 Update 197 Client Server 198 | | 199 | 1.) PUT to Member URI | 200 |------------------------------->| 201 | | 202 | 2.) 200 OK | 203 |<-------------------------------| 205 1. The client PUTs an updated representation to the member's URI. 207 2. The server responds with a representation of the member's new 208 state. 210 3.4.4 Delete 212 Client Server 213 | | 214 | 1.) DELETE to Member URI | 215 |------------------------------->| 216 | | 217 | 2.) 204 No Content | 218 |<-------------------------------| 219 | | 221 1. The client sends a DELETE request to the member's URI. 223 2. The server responds with successful status code. 225 3.5 Success and Failure 227 HTTP defines classes of response. HTTP status codes of the form 2xx 228 signal that a request was successful. HTTP status codes of the form 229 4xx or 5xx signal that an error has occurred, and the request has 230 failed. Consult the HTTP specification for more detailed definitions 231 of each status code. 233 4. Collections 235 An Atom Collection is a set of related resources represented by one 236 or more Atom Feed documents [AtomFormat]. Atom Collections are 237 ordered the date their members were updated, with the most recently 238 updated member appearing first. 240 4.1 GET 242 Collections can contain extremely large numbers of resources. A 243 naive client such as a web spider or web browser would be overwhelmed 244 if the response to a GET reflected the full membership of the 245 collection, and the server would waste large amounts of bandwidth and 246 processing time on clients unable to handle the response. As a 247 result, responses to a simple GET request represent a server- 248 determined subset of the collection's membership. Collections MAY 249 provide parameterized GET requests (see Section 7). 251 An example collection feed: 253 255 My Posts1 256 urn:uuid:ce61592c-14e2-4557-978e-dfbd444aefa6 257 2005-12-21T04:11:00-08:00 258 259 260 title 25 261 2005-12-21T04:11:00-08:00 262 263 Foo 264 265 urn:uuid:941e12b4-6eeb-4753-959d-0cbc51875387 266 267 268 269 ... 270 272 Each member is represented by an Atom Entry, but those entries are 273 not an editable representation of the entry. To retrieve the source 274 representation of the entry, clients send a GET request to the URI 275 found in each entry's pub:edit element (see Section 4.3.1). Derived 276 resources are located by examining an entry's atom:link elements. 278 4.2 POST 280 In addition to GET, a Collection Resource also accepts POST requests. 281 The client POSTs a representation of the desired resource to the 282 Collection Resource. Note that some collections only allow members 283 of a specific media-type and a POST MAY generate a response with a 284 status code of 415 ("Unsupported Media Type"). 286 In the case of a successful creation, the status code MUST be 201 287 ("Created"). 289 Example request creating a resource in a collection. 291 POST /collection HTTP/1.1 292 Host: example.org 293 User-Agent: Cosimo/1.0 294 Content-Type: application/atom+xml 295 Content-Length: nnnn 297 ...data... 299 Example response. 301 HTTP/1.1 201 Created 302 Date: Mon, 21 Mar 2005 19:20:19 GMT 303 Server: CountBasic/2.0 304 ETag: "4c083-268-423f1dc6" 305 Location: http://example.org/stuff/foo13241234.atom 307 4.3 Entry Collections 309 Entry Collections are Collections that restrict their membership to 310 Atom entries. The entries are edited by sending HTTP requests to the 311 URI found in an individual entry's pub:edit element. Servers can 312 determine the processing necessary to interpret a request by 313 examining the request's HTTP method. 315 4.3.1 The 'pub:edit' Element 317 The pub:edit element has one attribute, 'href'. The value of this 318 attribute is an IRI reference interpreted relative to xml:base. 320 4.3.2 Role of Atom Entry Elements During Editing 322 The elements of an Atom Entry Document are either a 'Writable 323 Element' or a 'Round Trip Element'. 325 Writable Element - An element of an Atom Entry whose value is 326 editable by the client and not enforced by the server. 328 Round Trip Element - An element of an Atom Entry whose value is 329 enforced by the server and not editable by the client. 331 That categorization determines the elements' disposition during 332 editing. 334 +--------------------+------------+ 335 | Atom Entry Element | Property | 336 +--------------------+------------+ 337 | atom:author | Writable | 338 | | | 339 | atom:category | Writable | 340 | | | 341 | atom:content | Writable | 342 | | | 343 | atom:contributor | Writable | 344 | | | 345 | atom:id | Round Trip | 346 | | | 347 | atom:link | Writable | 348 | | | 349 | atom:published | Writable | 350 | | | 351 | atom:source | Writable | 352 | | | 353 | atom:summary | Writable | 354 | | | 355 | atom:title | Writable | 356 | | | 357 | atom:updated | Round Trip | 358 +--------------------+------------+ 360 Table 1 362 5. Media Collections 364 Media Collections are Collections that do not have uniform 365 restrictions on the representations of the member resources. For 366 example, they might contain JPEG images, text documents, MPEG movies, 367 and any other type of resource the server allows. 369 5.1 GET 371 Media Collections return an Atom feed much like Entry Collections, 372 but with a few additions. The listing MUST also contain an atom: 373 content element with a 'src' attribute pointing to the media 374 resource. This URI can be used to edit the uploaded media resource, 375 using PUT and DELETE. 377 Such entries MAY contain pub:edit elements used to edit the entry 378 metadata. As with other collection members, derived resources can be 379 located by inspecting an entry's atom:link elements. 381 An example Media Collection feed: 383 385 My Posts1 386 387 Foo 388 389 urn:uuid:ce61592c-14e2-4557-978e-dfbd444aefa6 390 2005-12-21T04:11:00-08:00 391 392 393 title 25 394 2005-12-21T04:11:00-08:00 395 urn:uuid:941e12b4-6eeb-4753-959d-0cbc51875387 396 397 399 this was awesome 400 401 402 ... 403 405 The Atom Syndication Format requires that each such entry contain an 406 atom:title and atom:summary element. This requirement can be 407 challenging to meet without requiring users to enter tedious 408 metadata, but servers SHOULD attempt to provide textual data about 409 the resource in the interests of accessibility. The atom:title 410 element will likely be provided by the client, as way for users to 411 associate their local resources with those they have uploaded to the 412 server (see POST below). 414 5.2 POST 416 To create media resources, clients POST the resource to the Media 417 Collection's URI. Clients SHOULD provide a 'Title' request header to 418 provide the server with a short string identifying the resource to 419 users. Clients MAY include a 'Content-Description' header [RFC2045] 420 providing a more complete description of the content. In addition, 421 servers MAY inspect the POSTed entity for additional metadata to be 422 exposed in an atom:entry when listed in a Media Collection. For 423 example, the server might inspect a JPEG file for EXIF headers 424 containing creator data. 426 An example request. 428 POST /collection HTTP/1.1 429 Host: example.org 430 User-Agent: Cosimo/1.0 431 Content-Type: image/jpg 432 Content-Length: nnnn 433 Title: A Trip to the beach 434 Content-Description: It was so fun. 436 ...binary data... 438 An example request. 440 HTTP/1.1 201 Created 441 Date: Mon, 21 Mar 2005 19:20:19 GMT 442 Server: CountBasic/2.0 443 ETag: "4c083-268-423f1dc6" 444 Location: http://example.org/stuff/beach.jpg 446 6. Service Outlines 448 In order for authoring to commence, a client must first discover the 449 capabilities and locations of collections offered. 451 The Service Outline Document is a XOXO outline [XOXO]. The top level 452 list items describe distinct groups of resources offered by the 453 service. For example, a user with an account containing three blogs 454 would have 3 items at the top of the outline. There is no 455 requirement that servers support multiple top-level items, and a 456 collection may appear in more than one location in the document. 458 Clients can read entries contained in a collection by visiting an the 459 URI located in the 'href' attribute of a XOXO outline item. This URI 460 also serves as the location a client POSTs new entries to. The 'rel' 461 attribute of the XHTML anchor element conveys the nature of a 462 collection's member resources. This specification defines two 463 initial values for the 'rel' attribute: 465 o entry 467 o media 469 These values correspond to the two types of collection defined by 470 this specification. Extensibility for 'rel' values is specified in 471 XHTML Modularization [W3C.REC-xhtml-modularization-20010410]. 473 6.1 The 'app:select' Attribute 475 Anchor elements in Service Outlines MAY also include an "app:select" 476 attribute. When present, this attribute provides a template for the 477 parameterized GET requests described in Section 7. After 478 substitution of the appropriate parameters, the resulting URI 479 reference is interpreted relative to the in-scope base URI. 481 An example Service Outline: 482 514 7. Selection 516 Some clients require more precise control over the server's response. 517 For example, the client might wish to construct a record of the 518 collection's complete membership without generating a very large 519 number of requests. Another possibility is that the client might 520 wish to limit the results to a small number of entries. 522 'count': the maximum number of Atom Entries to be included in the 523 response. The field is an integer. 525 'offset': the offset at which to begin the sequence of entries 526 that match a given request. The field is an integer. 528 'begin': Atom entries in the returned feed MUST have an atom: 529 updated date later in time than the 'begin' date. The field MUST 530 match the syntax of an Atom Date Construct [AtomFormat]. 532 'end': Atom entries in the returned feed MUST have an atom:updated 533 date equal or earlier in time than the 'end' date. The field MUST 534 match the syntax of an Atom Date Construct [AtomFormat]. 536 None of the parameters are required. 538 Example Selection URI (disregard line break) 540 http://example.com/foo?begin=2003-12-13T18:30:02Z\ 541 &end=2003-12-25T18:30:02Z&offset=2&count=4 543 Selection URIs are templated by surrounding the field names in 544 brackets. For example, the 'count' field would appear as '{count}' 545 in a template. 547 An example selection template. 549 http://example.com/entries?b={begin}&e={end}&i={offset}&c={count} 551 If no 'end' field is present: The 'end' date is considered to be 552 the updated date of the collection's most recently updated member 553 resource. 555 If no 'begin' field is present: The 'begin' date is considered to 556 be the update date of the collection's least recently updated 557 member resource. 559 If no 'offset' field is present: The 'offset' integer is 560 considered to be 0. 562 If no 'count' field is present: The 'count' integer is determined 563 by the server. 565 8. Security Considerations 567 APP relies on HTTP Authentication. See [RFC2617] for a more detailed 568 description of the security properties of HTTP Authentication. 570 9. Normative References 572 [AtomFormat] 573 Nottingham, M. and R. Sayre, "The Atom Syndication 574 Format", work-in-progress, August 2005. 576 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 577 Extensions (MIME) Part One: Format of Internet Message 578 Bodies", RFC 2045, November 1996. 580 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 581 Requirement Levels", BCP 14, RFC 2119, March 1997. 583 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 584 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 585 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 587 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 588 Leach, P., Luotonen, A., and L. Stewart, "HTTP 589 Authentication: Basic and Digest Access Authentication", 590 RFC 2617, June 1999. 592 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 593 Resource Identifier (URI): Generic Syntax", STD 66, 594 RFC 3986, January 2005. 596 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 597 Identifiers (IRIs)", RFC 3987, January 2005. 599 [W3C.REC-xhtml-modularization-20010410] 600 Altheim, M., Boumphrey, F., McCarron, S., Dooley, S., 601 Schnitzenbaumer, S., and T. Wugofski, "Modularization of 602 XHTML", W3C REC REC-xhtml-modularization-20010410, 603 April 2001. 605 [W3C.REC-xml-20040204] 606 Yergeau, F., Paoli, J., Sperberg-McQueen, C., Bray, T., 607 and E. Maler, "Extensible Markup Language (XML) 1.0 (Third 608 Edition)", W3C REC REC-xml-20040204, February 2004. 610 [XOXO] Marks, K., Celik, T., Pilgrim, M., and M. Peterson, "XOXO 611 1.0: Extensible Open XHTML Outlines", October 2004. 613 Author's Address 615 Robert Sayre 617 Email: rfsayre@boswijck.com 618 URI: http://boswijck.com 620 Appendix A. Contributors 622 This draft is a variant of the in-progress Atom Publishing Protocol 623 specification from the IETF Atompub WG, and owes a debt to the WG's 624 members. 626 Intellectual Property Statement 628 The IETF takes no position regarding the validity or scope of any 629 Intellectual Property Rights or other rights that might be claimed to 630 pertain to the implementation or use of the technology described in 631 this document or the extent to which any license under such rights 632 might or might not be available; nor does it represent that it has 633 made any independent effort to identify any such rights. Information 634 on the procedures with respect to rights in RFC documents can be 635 found in BCP 78 and BCP 79. 637 Copies of IPR disclosures made to the IETF Secretariat and any 638 assurances of licenses to be made available, or the result of an 639 attempt made to obtain a general license or permission for the use of 640 such proprietary rights by implementers or users of this 641 specification can be obtained from the IETF on-line IPR repository at 642 http://www.ietf.org/ipr. 644 The IETF invites any interested party to bring to its attention any 645 copyrights, patents or patent applications, or other proprietary 646 rights that may cover technology that may be required to implement 647 this standard. Please address the information to the IETF at 648 ietf-ipr@ietf.org. 650 The IETF has been notified of intellectual property rights claimed in 651 regard to some or all of the specification contained in this 652 document. For more information consult the online list of claimed 653 rights. 655 Disclaimer of Validity 657 This document and the information contained herein are provided on an 658 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 659 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 660 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 661 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 662 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 663 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 665 Copyright Statement 667 Copyright (C) The Internet Society (2005). This document is subject 668 to the rights, licenses and restrictions contained in BCP 78, and 669 except as set forth therein, the authors retain all their rights. 671 Acknowledgment 673 Funding for the RFC Editor function is currently provided by the 674 Internet Society.