idnits 2.17.1 draft-sayre-atompub-protocol-basic-05.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 525. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 497. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 504. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 510. -- 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.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 250: '...ith certain media-types, so a POST MAY...' 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 25, 2005) is 6729 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) == Outdated reference: A later version (-01) exists of draft-sayre-atompub-protocol-outline-00 -- Possible downref: Normative reference to a draft: ref. 'APPO' -- 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) Summary: 8 errors (**), 0 flaws (~~), 3 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 25, 2005 4 Expires: April 28, 2006 6 The Atom Publishing Protocol (Basic) 7 draft-sayre-atompub-protocol-basic-05.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 28, 2006. 36 Copyright Notice 38 Copyright (C) The Internet Society (2005). 40 Abstract 42 This memo presents a protocol that uses XML and HTTP to publish and 43 edit Web resources. 45 Editorial Note 47 To provide feedback on this Internet-Draft, join the atom-protocol 48 mailing list . 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 54 3. The Atom Publishing Protocol Model . . . . . . . . . . . . . 3 55 4. APP Feeds . . . . . . . . . . . . . . . . . . . . . . . . . 6 56 5. Media Feeds . . . . . . . . . . . . . . . . . . . . . . . . 7 57 6. APP Outlines . . . . . . . . . . . . . . . . . . . . . . . . 9 58 7. Security Considerations . . . . . . . . . . . . . . . . . . 10 59 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 60 Author's Address . . . . . . . . . . . . . . . . . . . . . . 11 61 A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 11 62 B. Change History . . . . . . . . . . . . . . . . . . . . . . . 11 63 Intellectual Property and Copyright Statements . . . . . . . 13 65 1. Introduction 67 The Atom Publishing Protocol (APP) protocol uses HTTP [RFC2616] and 68 XML [W3C.REC-xml-20040204] to publish and edit Web resources. 70 2. Notational Conventions 72 The APP namespace is "http://purl.org/atom/app#". This specification 73 refers to it by using the prefix "pub", but that prefix is arbitrary. 75 The terms 'URI' and 'IRI' are shorthand for the identifiers specified 76 in [RFC3986] and [RFC3987]. 78 3. The Atom Publishing Protocol Model 80 The APP uses HTTP to operate on collections of Web resources 81 represented by Atom feeds [AtomFormat]. This section illustrates the 82 editing cycle for Atom entries. 84 o GET is used to retrieve a representation of a resource or perform 85 a read-only query. 86 o POST is used to create a new, dynamically-named resource. 87 o PUT is used to update a known resource. 88 o DELETE is used to remove a resource. 90 3.1 Discovery 92 To discover the location of the feeds exposed by an APP service, the 93 client must locate and request an APP Outline (Section 6). APP 94 Outlines describe the layout of an APP service. 96 Client Server 97 | | 98 | 1.) GET Outline URI | 99 |------------------------------->| 100 | | 101 | 2.) Service Outline Doc | 102 |<-------------------------------| 103 | | 105 1. The client sends a GET request to the Service Outline Resource. 106 2. The server responds with a APP Outline Document containing the 107 locations of feeds provided by the service. The content of this 108 document can vary based on aspects of the client request, 109 including, but not limited to, authentication credentials. 111 3.2 Listing 113 Once the client has discovered the location of a feed in the outline, 114 it can request a listing of the feed's entries. However, a feed 115 might contain an extremely large number of entries, so servers are 116 likely to list a small subset of them by default. 118 Client Server 119 | | 120 | 1.) GET to Atom Feed URI | 121 |------------------------------->| 122 | | 123 | 2.) 200 OK, Atom Feed Doc | 124 |<-------------------------------| 125 | | 127 1. The client sends a GET request to the Atom Feed's URI. 128 2. The server responds with an Atom Feed Document containing a full 129 or partial listing of the feed's membership. 131 3.3 Authoring 133 After locating a feed, a client can add entries by sending a POST 134 request to the feed; other changes are accomplished by sending HTTP 135 requests to each entry. 137 3.3.1 Create 139 Client Server 140 | | 141 | 1.) POST Entry to Feed URI | 142 |------------------------------->| 143 | | 144 | 2.) 201 Created @ Location | 145 |<-------------------------------| 146 | | 148 1. The client sends an Atom Entry to the server via HTTP POST. The 149 Request URI is that of the Atom Feed. 150 2. The server responds with a response of "201 Created" and a 151 "Location" header containing the URI of the newly-created Atom 152 Entry. 154 3.3.2 Read 156 Client Server 157 | | 158 | 1.) GET or HEAD to Entry URI | 159 |------------------------------->| 160 | | 161 | 2.) 200 OK Atom Entry | 162 |<-------------------------------| 163 | | 165 1. The client sends a GET (or HEAD) request to the entry's URI. 166 2. The server responds with an Atom Entry document. 168 3.3.3 Update 170 Client Server 171 | | 172 | 1.) PUT to Entry URI | 173 |------------------------------->| 174 | | 175 | 2.) 200 OK | 176 |<-------------------------------| 177 | | 179 1. The client PUTs an updated Atom Entry Document to the entry's 180 URI. 181 2. The server responds with a successful status code. 183 3.3.4 Delete 185 Client Server 186 | | 187 | 1.) DELETE to Entry URI | 188 |------------------------------->| 189 | | 190 | 2.) 204 No Content | 191 |<-------------------------------| 192 | | 194 1. The client sends a DELETE request to the entry's URI. 195 2. The server responds with successful status code. 197 3.4 Success and Failure 199 HTTP defines classes of response. HTTP status codes of the form 2xx 200 signal that a request was successful. HTTP status codes of the form 201 4xx or 5xx signal that an error has occurred, and the request has 202 failed. Consult the HTTP specification for more detailed definitions 203 of each status code. 205 4. APP Feeds 207 4.1 GET 209 Feeds can contain extremely large numbers of resources. A naive 210 client such as a web spider or web browser would be overwhelmed if 211 the response to a GET contained every entry in the feed, and the 212 server would waste large amounts of bandwidth and processing time on 213 clients unable to handle the response. As a result, responses to a 214 simple GET request represent a server-determined subset of the 215 entries in the feed. 217 An example APP feed: 219 221 My Posts1 222 urn:uuid:ce61592c-14e2-4557-978e-dfbd444aefa6 223 2005-12-21T04:11:00-08:00 224 225 226 title 25 227 2005-12-21T04:11:00-08:00 228 229 Foo 230 231 It started out looking simple enough... 232 urn:uuid:941e12b4-6eeb-4753-959d-0cbc51875387 233 234 235 236 ... 237 239 Each member entry is represented by an atom:entry element, but those 240 entries are not an editable representation of the entry. To retrieve 241 the source representation of the entry, clients send a GET request to 242 the URI found in each entry's pub:edit element (see Section 4.3.1). 243 Derived resources are located by examining an entry's atom:link 244 elements. 246 4.2 POST 248 An APP feed also accepts POST requests. The client POSTs a 249 representation of the desired resource to the APP feed. Some feeds 250 only accept POST requests with certain media-types, so a POST MAY 251 generate a response with a status code of 415 ("Unsupported Media 252 Type"). In the case of a successful creation, the status code is 201 253 ("Created"). 255 Example request creating a new entry in a feed: 257 POST /collection HTTP/1.1 258 Host: example.org 259 User-Agent: Cosimo/1.0 260 Content-Type: application/atom+xml 261 Content-Length: nnnn 263 ...data... 265 Example response. 267 HTTP/1.1 201 Created 268 Date: Mon, 21 Mar 2005 19:20:19 GMT 269 Server: CountBasic/2.0 270 ETag: "4c083-268-423f1dc6" 271 Location: http://example.org/stuff/foo13241234.atom 273 APP feeds contain primarily textual content. Examples include 274 weblogs, online journals, and wikis. Clients add entries by sending 275 POST requests containing Atom Entry Documents. Existing entries are 276 edited by sending HTTP requests to the URI found in an individual 277 entry's pub:edit element. Servers can determine the processing 278 necessary to interpret a request by examining the request's HTTP 279 method. It is probably unwise to change an existing entry's atom:id 280 value when issuing a PUT request. 282 4.3 Entry Extensions 284 4.3.1 The 'pub:edit' Element 286 The pub:edit element is a child of atom:entry and has one attribute, 287 'href'. The value of this attribute is an IRI reference interpreted 288 relative to xml:base. 290 4.3.2 The 'pub:control' Element 292 The pub:control element is a child of atom:entry and is used to 293 persist editing information and contains arbitrary markup. 295 5. Media Feeds 297 The entries within Media Feeds are feeds do not represent uniform 298 types of content. For example, they might contain JPEG images, text 299 documents, MPEG movies, and any other type of resource the server 300 allows. 302 5.1 GET 304 Media Feeds return an Atom feed much like Text Feeds, but with a few 305 additions. The entries also contain an atom:content element with a 306 'src' attribute pointing to the media resource. This URI can be used 307 to edit the uploaded media resource, using PUT and DELETE. Such 308 entries may contain pub:edit elements used to edit the entry 309 metadata. As with other entries, derived resources can be located by 310 inspecting an entry's atom:link elements. 312 An example Media Feed: 314 316 My Posts1 317 318 Foo 319 320 urn:uuid:ce61592c-14e2-4557-978e-dfbd444aefa6 321 2005-12-21T04:11:00-08:00 322 323 324 Title25 325 2005-12-21T04:11:00-08:00 326 urn:uuid:941e12b4-6eeb-4753-959d-0cbc51875387 327 328 330 This was awesome. 331 332 333 ... 334 336 The Atom Syndication Format requires that each such entry contain an 337 atom:title and atom:summary element. This requirement can be 338 challenging to meet without requiring users to enter tedious 339 metadata, but servers should attempt to provide textual data about 340 the resource in the interests of accessibility. The atom:title 341 element will likely be provided by the client, as a way for users to 342 associate their local resources with those they have uploaded to the 343 server (see POST below). 345 5.2 POST 347 To add an entry to a Media Feed, clients POST the resource to the 348 Media Feed's URI. Clients should provide a 'Title' request header to 349 provide the server with a short string identifying the resource to 350 users. Clients may include a 'Content-Description' header [RFC2045] 351 providing a more complete description of the content. In addition, 352 servers may inspect the POSTed entity for additional metadata to be 353 exposed in an atom:entry element when listed in a Media Feed. For 354 example, the server might inspect a JPEG file for EXIF headers 355 containing creator data. 357 An example request: 359 POST /collection HTTP/1.1 360 Host: example.org 361 User-Agent: Cosimo/1.0 362 Content-Type: image/jpg 363 Content-Length: nnnn 364 Title: A Trip to the beach 365 Content-Description: It was so fun. 367 ...binary data... 369 An example response: 371 HTTP/1.1 201 Created 372 Date: Mon, 21 Mar 2005 19:20:19 GMT 373 Server: CountBasic/2.0 374 ETag: "4c083-268-423f1dc6" 375 Location: http://example.org/stuff/beach.jpg 377 6. APP Outlines 379 In order for authoring to commence, a client must first discover the 380 Atom Feeds offered by the server. 382 The outline is an APP Outline Document [APPO]. The top level outline 383 elements describe distinct groups of resources available on the 384 server. For example, a user with an account containing three blogs 385 would have 3 elements under the root element. There 386 is no requirement that servers support multiple top-level outlines, 387 and a feed may appear in more than one location in the document. 389 Clients read APP feeds by visiting the URI located in the 'href' 390 attribute of an element. This URI also serves as the 391 location a client POSTs new entries to. The 'class' attribute of the 392 element indicates the type of feed. This specification 393 defines two values for the 'class' attribute: 395 o feed 396 o media feed 398 These values correspond to standard feeds and media feeds, 399 respectively. 401 An example APP Outline: 403 404 405 406 407 408 409 410 411 412 414 7. Security Considerations 416 APP relies on HTTP Authentication. See [RFC2617] for a more detailed 417 description of the security properties of HTTP Authentication. 419 8. References 421 [APPO] Sayre, R., "APP Outline Format", work-in-progress, 422 draft-sayre-atompub-protocol-outline-00, October 2005. 424 [AtomFormat] 425 Nottingham, M. and R. Sayre, "The Atom Syndication 426 Format", work-in-progress, August 2005. 428 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 429 Extensions (MIME) Part One: Format of Internet Message 430 Bodies", RFC 2045, November 1996. 432 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 433 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 434 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 436 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 437 Leach, P., Luotonen, A., and L. Stewart, "HTTP 438 Authentication: Basic and Digest Access Authentication", 439 RFC 2617, June 1999. 441 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 442 Resource Identifier (URI): Generic Syntax", STD 66, 443 RFC 3986, January 2005. 445 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 446 Identifiers (IRIs)", RFC 3987, January 2005. 448 [W3C.REC-xml-20040204] 449 Yergeau, F., Paoli, J., Sperberg-McQueen, C., Bray, T., 450 and E. Maler, "Extensible Markup Language (XML) 1.0 (Third 451 Edition)", W3C REC REC-xml-20040204, February 2004. 453 Author's Address 455 Robert Sayre 457 Email: rfsayre@boswijck.com 458 URI: http://boswijck.com 460 Appendix A. Contributors 462 This draft is a variant of the in-progress Atom Publishing Protocol 463 specification from the IETF Atompub WG, and owes a debt to the WG's 464 members. 466 Appendix B. Change History 468 -05: Death to collections! 469 Switch APPO instead of XOXO. 470 State the obvious about the extension elements. 471 Remove RFC2119 reference. 472 Change "Normative References" to "References". 473 -04: Add pub:control element. 474 Reword collection POST. 475 Prophesize about atom:id. 476 -03: Remove search/query capabilities added in -02 477 Drop round-tripping. Most of them were writable, some folks 478 wanted to edit atom:updated, that leaves atom:id, and that seems 479 foolish to try and edit, so go ahead and try it if you think you 480 can. 482 Drop ordering... let the server pop things up if it wants to. 483 -02: Add search/query capabilities. 484 -01: Split from WG draft, cut SOAP, and much other cruft. 485 -interlude: Becomes WG draft. 486 -00: Split from WG draft 488 Intellectual Property Statement 490 The IETF takes no position regarding the validity or scope of any 491 Intellectual Property Rights or other rights that might be claimed to 492 pertain to the implementation or use of the technology described in 493 this document or the extent to which any license under such rights 494 might or might not be available; nor does it represent that it has 495 made any independent effort to identify any such rights. Information 496 on the procedures with respect to rights in RFC documents can be 497 found in BCP 78 and BCP 79. 499 Copies of IPR disclosures made to the IETF Secretariat and any 500 assurances of licenses to be made available, or the result of an 501 attempt made to obtain a general license or permission for the use of 502 such proprietary rights by implementers or users of this 503 specification can be obtained from the IETF on-line IPR repository at 504 http://www.ietf.org/ipr. 506 The IETF invites any interested party to bring to its attention any 507 copyrights, patents or patent applications, or other proprietary 508 rights that may cover technology that may be required to implement 509 this standard. Please address the information to the IETF at 510 ietf-ipr@ietf.org. 512 The IETF has been notified of intellectual property rights claimed in 513 regard to some or all of the specification contained in this 514 document. For more information consult the online list of claimed 515 rights. 517 Disclaimer of Validity 519 This document and the information contained herein are provided on an 520 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 521 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 522 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 523 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 524 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 525 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 527 Copyright Statement 529 Copyright (C) The Internet Society (2005). This document is subject 530 to the rights, licenses and restrictions contained in BCP 78, and 531 except as set forth therein, the authors retain all their rights. 533 Acknowledgment 535 Funding for the RFC Editor function is currently provided by the 536 Internet Society.