idnits 2.17.1 draft-sayre-atompub-protocol-basic-06.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 14. -- Found old boilerplate from RFC 3978, Section 5.5 on line 621. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 598. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 605. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 611. ** 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 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 430: '...iption documents MUST be well-formed X...' 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 (January 24, 2006) is 6666 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) -- Missing reference section? 'RFC2616' on line 64 looks like a reference -- Missing reference section? 'RFC3986' on line 459 looks like a reference -- Missing reference section? 'RFC3987' on line 458 looks like a reference -- Missing reference section? 'AtomFormat' on line 79 looks like a reference -- Missing reference section? 'RFC2045' on line 328 looks like a reference Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 12 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Atompub Working Group R. Sayre 3 Internet-Draft January 24, 2006 4 Expires: July 28, 2006 6 The Atom Publishing Protocol (Basic) 7 draft-sayre-atompub-protocol-basic-06 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. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on July 28, 2006. 34 Copyright Notice 36 Copyright (C) The Internet Society (2006). 38 Abstract 40 This memo presents a protocol that uses XML and HTTP to publish and 41 edit Web resources. 43 Table of Contents 45 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 46 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3 47 3. The Atom Publishing Protocol Model . . . . . . . . . . . . . . 3 48 4. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 3 49 5. Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 50 6. Authoring . . . . . . . . . . . . . . . . . . . . . . . . . . 4 51 7. Atom Protocol Feeds . . . . . . . . . . . . . . . . . . . . . 6 52 8. Media Feeds . . . . . . . . . . . . . . . . . . . . . . . . . 8 53 9. Service Description . . . . . . . . . . . . . . . . . . . . . 10 54 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 55 11. Security Considerations . . . . . . . . . . . . . . . . . . . 14 56 12. Informative References . . . . . . . . . . . . . . . . . . . . 15 57 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15 58 Appendix B. Change History . . . . . . . . . . . . . . . . . . . 15 59 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16 60 Intellectual Property and Copyright Statements . . . . . . . . . . 17 62 1. Introduction 64 The Atom Publishing Protocol uses HTTP [RFC2616] and XML [W3C.REC- 65 xml-20040204] to publish and edit Web resources. 67 2. Notational Conventions 69 The Atom Protocol namespace is "http://purl.org/atom/app#". This 70 specification refers to it by using the prefix "pub", but that prefix 71 is arbitrary. 73 The terms 'URI' and 'IRI' are shorthand for the identifiers specified 74 in [RFC3986] and [RFC3987]. 76 3. The Atom Publishing Protocol Model 78 The Atom Protocol uses HTTP to operate on collections of Web 79 resources represented by Atom feeds [AtomFormat]. This section 80 illustrates the editing cycle for Atom entries. 81 o GET is used to retrieve a representation of a resource or perform 82 a read-only query. 83 o POST is used to create a new, dynamically-named resource. 84 o PUT is used to update a known resource. 85 o DELETE is used to remove a resource. 87 4. Discovery 89 To discover the location of the feeds exposed by an Atom Protocol 90 service, the client must locate and request a Service Description 91 Document (Section 6). 93 Client Server 94 | | 95 | 1.) GET Service URI | 96 |------------------------------->| 97 | | 98 | 2.) Service Description Doc | 99 |<-------------------------------| 100 | | 102 1. The client sends a GET request to the Service Description URI. 104 2. The server responds with a Service Description Document 105 containing the locations of feeds provided by the service. The 106 content of this document can vary based on aspects of the client 107 request, including, but not limited to, authentication 108 credentials. 110 5. Listing 112 Once the client has discovered the location of a feed in the outline, 113 it can request a listing of the feed's entries. However, a feed 114 might contain an extremely large number of entries, so servers are 115 likely to list a small subset of them by default. 117 Client Server 118 | | 119 | 1.) GET to Atom Feed URI | 120 |------------------------------->| 121 | | 122 | 2.) 200 OK, Atom Feed Doc | 123 |<-------------------------------| 124 | | 126 1. The client sends a GET request to the Atom Feed's URI. 127 2. The server responds with an Atom Feed Document containing a full 128 or partial listing of the feed's membership. 130 6. Authoring 132 After locating a feed, a client can add entries by sending a POST 133 request to the feed; other changes are accomplished by sending HTTP 134 requests to each entry. 136 6.1. Create 138 Client Server 139 | | 140 | 1.) POST Entry to Feed URI | 141 |------------------------------->| 142 | | 143 | 2.) 201 Created @ Location | 144 |<-------------------------------| 145 | | 147 1. The client sends an Atom Entry to the server via HTTP POST. The 148 Request URI is that of the Atom Feed. 149 2. The server responds with a response of "201 Created" and a 150 "Location" header containing the URI of the newly-created Atom 151 Entry. 153 6.2. Read 155 Client Server 156 | | 157 | 1.) GET or HEAD to Entry URI | 158 |------------------------------->| 159 | | 160 | 2.) 200 OK Atom Entry | 161 |<-------------------------------| 162 | | 164 1. The client sends a GET (or HEAD) request to the entry's URI. 165 2. The server responds with an Atom Entry document. 167 6.3. Update 169 Client Server 170 | | 171 | 1.) PUT to Entry URI | 172 |------------------------------->| 173 | | 174 | 2.) 200 OK | 175 |<-------------------------------| 176 | | 178 1. The client PUTs an updated Atom Entry Document to the entry's 179 URI. 180 2. The server responds with a successful status code. 182 6.4. Delete 184 Client Server 185 | | 186 | 1.) DELETE to Entry URI | 187 |------------------------------->| 188 | | 189 | 2.) 204 No Content | 190 |<-------------------------------| 191 | | 193 1. The client sends a DELETE request to the entry's URI. 194 2. The server responds with successful status code. 196 6.5. Success and Failure 198 HTTP defines classes of response. HTTP status codes of the form 2xx 199 signal that a request was successful. HTTP status codes of the form 200 4xx or 5xx signal that an error has occurred, and the request has 201 failed. Consult the HTTP specification for more detailed definitions 202 of each status code. 204 7. Atom Protocol Feeds 206 7.1. GET 208 Feeds can contain extremely large numbers of resources. A naive 209 client such as a web spider or web browser would be overwhelmed if 210 the response to a GET contained every entry in the feed, and the 211 server would waste large amounts of bandwidth and processing time on 212 clients unable to handle the response. As a result, responses to a 213 simple GET request represent a server-determined subset of the 214 entries in the feed. 216 An example Atom Protocol feed: 218 220 My Posts1 221 urn:uuid:ce61592c-14e2-4557-978e-dfbd444aefa6 222 2005-12-21T04:11:00-08:00 223 224 225 title 25 226 2005-12-21T04:11:00-08:00 227 228 Foo 229 230 It started out looking simple enough... 231 urn:uuid:941e12b4-6eeb-4753-959d-0cbc51875387 232 233 234 235 ... 236 238 Each member entry is represented by an atom:entry element, but those 239 entries are not an editable representation of the entry. To retrieve 240 the source representation of the entry, clients send a GET request to 241 the URI found in each entry's pub:edit element (see Section 4.3.1). 242 Derived resources are located by examining an entry's atom:link 243 elements. 245 7.2. POST 247 An Atom Protocol feed also accepts POST requests. The client POSTs a 248 representation of the desired resource to the APP feed. Some feeds 249 only accept POST requests with certain media-types, so a POST request 250 could result in a response with a status code of 415 ("Unsupported 251 Media Type"). In the case of a successful creation, the status code 252 is 201 ("Created"). 254 Example request creating a new entry in a feed: 256 POST /collection HTTP/1.1 257 Host: example.org 258 User-Agent: Cosimo/1.0 259 Content-Type: application/atom+xml 260 Content-Length: nnnn 262 ...data... 264 Example response. 266 HTTP/1.1 201 Created 267 Date: Mon, 21 Mar 2005 19:20:19 GMT 268 Server: CountBasic/2.0 269 ETag: "4c083-268-423f1dc6" 270 Location: http://example.org/stuff/foo13241234.atom 272 8. Media Feeds 274 The entries within Media Feeds do not represent uniform types of 275 content. For example, they might contain JPEG images, text 276 documents, MPEG movies, or any other type of resource the server 277 allows. 279 8.1. GET 281 Media Feeds return an Atom feed much like the textual Atom Protcol 282 feeds described above, but with a few additions. The entries also 283 contain an atom:content element with a 'src' attribute pointing to 284 the media resource. This URI can be used to edit the uploaded media 285 resource, using PUT and DELETE. Such entries may contain edit links 286 used to edit the entry metadata. As with any Atom entry, related and 287 derived resources can be located by inspecting an entry's atom:link 288 elements. 290 An example Media Feed: 292 294 My Posts1 295 296 Foo 297 298 urn:uuid:ce61592c-14e2-4557-978e-dfbd444aefa6 299 2005-12-21T04:11:00-08:00 300 301 302 Title25 303 2005-12-21T04:11:00-08:00 304 urn:uuid:941e12b4-6eeb-4753-959d-0cbc51875387 305 306 308 This was awesome. 309 310 311 ... 312 314 The Atom Syndication Format requires that each such entry contain an 315 atom:title and atom:summary element. This requirement can be 316 challenging to meet without requiring users to enter tedious 317 metadata, but servers should attempt to provide textual data about 318 the resource in the interests of accessibility. The atom:title 319 element will likely be provided by the client, as a way for users to 320 associate their local resources with those they have uploaded to the 321 server (see POST below). 323 8.2. POST 325 To add an entry to a Media Feed, clients POST the resource to the 326 Media Feed's URI. Clients should provide a 'Title' request header to 327 provide the server with a short string identifying the resource to 328 users. Clients may include a 'Content-Description' header [RFC2045] 329 providing a more complete description of the content. In addition, 330 servers may inspect the POSTed entity for additional metadata to be 331 exposed in an atom:entry element when listed in a Media Feed. For 332 example, the server might inspect a JPEG file for EXIF headers 333 containing creator data. 335 An example request: 337 POST /collection HTTP/1.1 338 Host: example.org 339 User-Agent: Cosimo/1.0 340 Content-Type: image/tiff 341 Content-Length: nnnn 342 Title: A Trip to the beach 343 Content-Description: It was so fun. 345 ...binary data... 347 An example response: 349 HTTP/1.1 201 Created 350 Date: Mon, 21 Mar 2005 19:20:19 GMT 351 Server: CountBasic/2.0 352 ETag: "4c083-268-423f1dc6" 353 Location: http://example.org/stuff/beach.tiff 355 [@@ deal with response ambiguity noted in WG] 357 9. Service Description 359 Many Atom Protocol applications require a basic resource layout in 360 order to ease configuration requirements. Servers use Service 361 Description documents to convey information about related groups of 362 Atom Protocol feeds. On a blogging service, for example, each group 363 might represent a distinct blog and associated resources. 365 Example Service Description document: 367 368 370 372 374 375 378 380 Servers are not required to expose a Service Description document, 381 but experimental deployment experience has shown that a single 382 document which signals some basic information about the server's 383 configuration can greatly simplify client implementations. The 384 simplest useful Service Description document shows the location of a 385 single resource: 387 388 390 392 If another service is added, the document can be upgraded to reflect 393 new resources. 395 396 398 400 402 Finally, more extensive services could require some amount of 403 hierarchical grouping. 405 406 408 410 411 412 414 416 417 419 This example shows that links to APP feeds can appear in 420 elements used to group other resources. The element named 421 "Other Things" does not contain an 'href' attribute, so it functions 422 as a simple named group of the services it contains. 424 9.1. Categories 426 [@@ tbd] 428 9.2. Document Format 430 Service Description documents MUST be well-formed XML [W3C.REC-xml- 431 20040204]. 433 The root element of an APP Service Description Document is "". 434 This specification does not define any attributes of the 435 element, but the element can have any number of attributes. 437 Zero or more elements appear as child elements of . 438 Also, elements may contain zero or more elements. 439 This specification defines three attributes of the element. 440 elements contain at least a 'name' or 'href' attribute. 441 Additional service properties too large or structured to include in 442 attribute values could appear as child elements of the service 443 element. 445 elements can contain any number of elements that are not 446 elements, and elements can contain any number of 447 elements that are not elements. 449 9.2.1. The 'name' Attribute 451 The 'name' attribute contains a short string describing the service 452 element. Entities such as "&" and "<" represent their 453 corresponding characters ("&" and "<" respectively), not markup. 455 9.2.2. The 'href' Attribute 457 The 'href' attribute contains an IRI reference interpreted relative 458 to the in-scope base IRI [RFC3987]. Most protocols require URIs 459 [RFC3986], so IRIs usually need to be converted to URIs before being 460 dereferenced. 462 9.2.3. The 'class' Attribute 464 The 'class' attribute contains a space-separated list of strings used 465 to classify the service element. This specification defines two 466 values for the 'class' attribute: 468 o feed 469 o media feed 471 These values correspond to standard feeds and media feeds, 472 respectively. If the 'class' attribute is not present, the 473 element can be processed as if the attribute were present with a 474 value of 'feed'. 476 9.2.4. Relax NG Schema 478 Service Description documents conform to the schema below. 480 default namespace = "http://purl.org/atom/app#" 481 start = app 483 app = element app { 484 anyAttribute*, 485 (service* & anyElement*) 486 } 488 service = element service { 489 (nameAtt | hrefAtt), anyAttribute*, 490 (service* & anyElement*) 491 } 493 nameAtt = attribute name { text } 494 hrefAtt = attribute href { text } 495 classAtt = attribute class { text } 497 anyElement = element * { (anyAttribute | text | anyElement)* } 498 anyAttribute = attribute * { text } 500 9.2.5. Extending Service Description 502 The Service Description document format can be freely extended by 503 adding attributes and elements not defined by this specification. 505 Valid Service Description document with extensions: 507 508 42 509 510 hmm 511 512 514 Additional service properties too large or structured to include in 515 attribute values could appear as child elements of the or 516 elements. elements may contain any number of elements 517 that are not elements, and elements may contain 518 any number of elements that are not elements. 520 9.2.6. User Agent Conformance 522 Foreign markup is markup not defined by this specification. 524 Software consuming Service Description documents must not halt 525 processing when any foreign markup is encountered. Software may 526 ignore the markup and process any content of foreign elements as 527 though the surrounding markup were not present. For example, 528 software may process 530 531 532 534 536 537 538 ... 539 540 541 542 544 as though the and elements were not present. 546 Software conforming to this specification may halt processing when 547 documents that do not conform to the schema are encountered. 549 10. IANA Considerations 551 [@@ fill out in for application/sd+xml (service description)] 553 11. Security Considerations 554 12. Informative References 556 Appendix A. Acknowledgements 558 This draft is a variant of the in-progress Atom Publishing Protocol 559 specification from the IETF Atompub WG, and owes a debt to the WG's 560 members. 562 Appendix B. Change History 563 -06: Change service description format. 564 Change IPR terms to full3978 565 -interlude: More unproductive WG thrashing. 566 -05: Death to collections! 567 Switch APPO instead of XOXO. 568 State the obvious about the extension elements. 569 Remove RFC2119 reference. 570 Change "Normative References" to "References". 571 -04: Add pub:control element. 572 Reword collection POST. 573 Prophesize about atom:id. 574 -03: Remove search/query capabilities added in -02 Drop round- 575 tripping. Most of them were writable, some folks wanted to edit 576 atom:updated, that leaves atom:id, and that seems foolish to try 577 and edit, so go ahead and try it if you think you can. 578 -02: Add search/query capabilities. 579 -01: Split from WG draft, cut SOAP, and much other cruft. 580 -interlude: Becomes WG draft. 581 -00: Split from WG draft. 583 Author's Address 585 Robert Sayre 587 Email: rfsayre@boswijck.com 589 Intellectual Property Statement 591 The IETF takes no position regarding the validity or scope of any 592 Intellectual Property Rights or other rights that might be claimed to 593 pertain to the implementation or use of the technology described in 594 this document or the extent to which any license under such rights 595 might or might not be available; nor does it represent that it has 596 made any independent effort to identify any such rights. Information 597 on the procedures with respect to rights in RFC documents can be 598 found in BCP 78 and BCP 79. 600 Copies of IPR disclosures made to the IETF Secretariat and any 601 assurances of licenses to be made available, or the result of an 602 attempt made to obtain a general license or permission for the use of 603 such proprietary rights by implementers or users of this 604 specification can be obtained from the IETF on-line IPR repository at 605 http://www.ietf.org/ipr. 607 The IETF invites any interested party to bring to its attention any 608 copyrights, patents or patent applications, or other proprietary 609 rights that may cover technology that may be required to implement 610 this standard. Please address the information to the IETF at 611 ietf-ipr@ietf.org. 613 Disclaimer of Validity 615 This document and the information contained herein are provided on an 616 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 617 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 618 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 619 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 620 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 621 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 623 Copyright Statement 625 Copyright (C) The Internet Society (2006). This document is subject 626 to the rights, licenses and restrictions contained in BCP 78, and 627 except as set forth therein, the authors retain all their rights. 629 Acknowledgment 631 Funding for the RFC Editor function is currently provided by the 632 Internet Society.