idnits 2.17.1 draft-ietf-atompub-protocol-07.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.5 on line 1276. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1248. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1255. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1261. ** 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 abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: Atom Protocol servers MUST provide representations of collections as Atom feed documents whose entries represent the collection's members. The returned Atom feed MAY NOT contain entries for all the collection's members. Instead, the Atom feed document MAY contain link elements with "rel" attribute values of "next", "previous", "start" and "end" that can be used to navigate through the complete set of matching entries. -- 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 01, 2006) is 6682 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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 2246 (Obsoleted by RFC 4346) ** 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) ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) Summary: 8 errors (**), 0 flaws (~~), 3 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Gregorio, Ed. 3 Internet-Draft BitWorking, Inc 4 Expires: July 5, 2006 B. de hOra, Ed. 5 Propylon Ltd. 6 January 01, 2006 8 The Atom Publishing Protocol 9 draft-ietf-atompub-protocol-07.txt 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 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 July 5, 2006. 36 Copyright Notice 38 Copyright (C) The Internet Society (2006). 40 Abstract 42 The Atom Publishing Protocol (APP) is an application-level protocol 43 for publishing and editing Web resources. The protocol is based on 44 HTTP transport of Atom-formatted representations. The Atom format is 45 documented in the Atom Syndication Format (RFC4287). 47 Editorial Note 48 To provide feedback on this Internet-Draft, join the atom-protocol 49 mailing list (http://www.imc.org/atom-protocol/index.html) [1]. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 54 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 5 55 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 6 56 4. Protocol Model . . . . . . . . . . . . . . . . . . . . . . . 7 57 5. Protocol Operations . . . . . . . . . . . . . . . . . . . . 8 58 5.1 Retrieving an Introspection Document . . . . . . . . . . . 8 59 5.2 Creating a Resource . . . . . . . . . . . . . . . . . . . 8 60 5.3 Editing a Resource . . . . . . . . . . . . . . . . . . . . 8 61 5.3.1 Retrieving a Resource . . . . . . . . . . . . . . . . 9 62 5.3.2 Updating a Resource . . . . . . . . . . . . . . . . . 9 63 5.3.3 Deleting a Resource . . . . . . . . . . . . . . . . . 9 64 5.4 Listing Collection Members . . . . . . . . . . . . . . . . 10 65 5.5 Use of HTTP Response codes . . . . . . . . . . . . . . . . 10 66 6. XML-related Conventions . . . . . . . . . . . . . . . . . . 11 67 6.1 Referring to Information Items . . . . . . . . . . . . . . 11 68 6.2 XML Namespace Usage . . . . . . . . . . . . . . . . . . . 11 69 6.3 Use of xml:base and xml:lang . . . . . . . . . . . . . . . 11 70 6.4 RELAX NG Schema . . . . . . . . . . . . . . . . . . . . . 12 71 7. Introspection Documents . . . . . . . . . . . . . . . . . . 13 72 7.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . 13 73 7.2 Element Definitions . . . . . . . . . . . . . . . . . . . 14 74 7.2.1 The "app:service" Element . . . . . . . . . . . . . . 14 75 7.2.2 The "app:workspace" Element . . . . . . . . . . . . . 14 76 7.2.3 The "app:collection" Element . . . . . . . . . . . . . 15 77 7.2.4 The "app:member-type" Element . . . . . . . . . . . . 15 78 8. Collections . . . . . . . . . . . . . . . . . . . . . . . . 17 79 8.1 Creating resources with POST . . . . . . . . . . . . . . . 17 80 8.1.1 Example . . . . . . . . . . . . . . . . . . . . . . . 17 81 8.1.2 Title: Header . . . . . . . . . . . . . . . . . . . . 17 82 8.2 Entry Collections . . . . . . . . . . . . . . . . . . . . 18 83 8.3 Media Collections . . . . . . . . . . . . . . . . . . . . 18 84 8.3.1 Editing Media Resources . . . . . . . . . . . . . . . 18 85 9. Listing Collections . . . . . . . . . . . . . . . . . . . . 19 86 9.1 Collection Paging . . . . . . . . . . . . . . . . . . . . 19 87 10. Atom Format Link Relation Extensions . . . . . . . . . . . . 21 88 10.1 The "edit" Link Relation . . . . . . . . . . . . . . . . 21 89 11. Atom Publishing Control Extensions . . . . . . . . . . . . . 22 90 11.1 The Atom Publishing Control Namespace . . . . . . . . . 22 91 11.2 The "pub:control" Element . . . . . . . . . . . . . . . 22 92 11.2.1 The "pub:draft" Element . . . . . . . . . . . . . . 22 93 12. Atom Publishing Protocol Example . . . . . . . . . . . . . . 23 94 13. Securing the Atom Protocol . . . . . . . . . . . . . . . . . 25 95 14. Security Considerations . . . . . . . . . . . . . . . . . . 26 96 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . 27 97 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 98 16.1 Normative References . . . . . . . . . . . . . . . . . . 29 99 16.2 Informative References . . . . . . . . . . . . . . . . . 30 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 31 101 A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 32 102 B. RELAX NG Compact Schema . . . . . . . . . . . . . . . . . . 33 103 C. Revision History . . . . . . . . . . . . . . . . . . . . . . 36 104 Intellectual Property and Copyright Statements . . . . . . . 39 106 1. Introduction 108 The Atom Publishing Protocol is an application-level protocol for 109 publishing and editing Web resources using HTTP [RFC2616] and XML 1.0 110 [W3C.REC-xml-20040204]. The protocol supports the creation of 111 arbitrary web resources and provides facilities for: 113 o Collections: Sets of resources, which may be retrieved in whole or 114 in part. 116 o Introspection: Discovering and describing collections. 118 o Editing: Creating, updating and deleting resources. 120 2. Notational Conventions 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 124 document are to be interpreted as described in [RFC2119]. 126 Note: The Introspection Document allows the use of IRIs [RFC3987], as 127 well as URIs [RFC3986]. Every URI is an IRI, so any URI can be used 128 where an IRI is needed. How to map an IRI to a URI is specified in 129 Section 3.1 of Internationalized Resource Identifiers (IRIs) 130 [RFC3987]. 132 3. Terminology 134 For convenience, this protocol may be referred to as the "Atom 135 Protocol" or "APP". 137 URI/IRI - A Uniform Resource Identifier and Internationalized 138 Resource Identifier. These terms and the distinction between them 139 are defined in [RFC3986] and [RFC3987]. 141 Resource - A network-accessible data object or service identified by 142 an IRI, as defined in [RFC2616]. See [W3C.REC-webarch-20041215] for 143 further discussion on resources. 145 The phrase "the IRI of a document" in this specification is shorthand 146 for "an IRI which, when dereferenced, is expected to produce that 147 document as a representation". 149 Representation - An entity included with a request or response as 150 defined in [RFC2616]. 152 Collection - A resource that contains a set of member IRIs. See 153 Section 8. 155 Member - A resource whose IRI is listed in a Collection. 157 Introspection Document - A document that describes the location and 158 capabilities of one or more Collections. See Section 7. 160 4. Protocol Model 162 The Atom Publishing Protocol uses HTTP to edit and author web 163 resources. The Atom Protocol uses the following HTTP methods: 165 o GET is used to retrieve a representation of a resource or perform 166 a query. 168 o POST is used to create a new, dynamically-named resource. 170 o PUT is used to update a known resource. 172 o DELETE is used to remove a resource. 174 Along with operations on resources, the Atom Protocol provides list- 175 based structures, called Collections, for managing and organising 176 resources, called Members. Collections contain the IRIs of, and 177 metadata about, their Member resources. For authoring and editing of 178 resources to commence, an Atom Protocol client can examine server- 179 defined groups of Collections, called Introspection Documents. 181 5. Protocol Operations 183 5.1 Retrieving an Introspection Document 185 Client Server 186 | | 187 | 1.) GET to IRI of Introspection Document | 188 |------------------------------------------>| 189 | | 190 | 2.) Introspection Document | 191 |<------------------------------------------| 192 | | 194 1. The client sends a GET request to the IRI of the Introspection 195 Document. 197 2. The server responds with the document which enumerates the IRIs 198 of all the Collections and the capabilities of those Collections 199 supported by the server. The content of this document can vary 200 based on aspects of the client request, including, but not 201 limited to, authentication credentials. 203 5.2 Creating a Resource 205 Client Server 206 | | 207 | 1.) POST to IRI of Collection | 208 |------------------------------------------>| 209 | | 210 | 2.) 201 Created | 211 |<------------------------------------------| 212 | | 214 1. The client POSTs a representation of the Member to the IRI of the 215 collection. 217 2. If the Member resource was created successfully, the server 218 responds with a status code of 201 and a Location: header that 219 contains the IRI of the newly created resource. 221 5.3 Editing a Resource 223 Once a resource has been created and its IRI is known, that IRI may 224 be used to retrieve, update, and delete the resource. 226 5.3.1 Retrieving a Resource 228 Client Server 229 | | 230 | 1.) GET to Member IRI | 231 |------------------------------------------>| 232 | | 233 | 2.) Member Representation | 234 |<------------------------------------------| 235 | | 237 1. The client sends a GET request to the Member's IRI to retrieve 238 its representation. 240 2. The server responds with the representation of the resource. 242 5.3.2 Updating a Resource 244 Client Server 245 | | 246 | 1.) PUT to Member IRI | 247 |------------------------------------------>| 248 | | 249 | 2.) 200 OK | 250 |<------------------------------------------| 252 1. The client PUTs an updated representation to the Member's IRI. 254 2. Upon a successful update of the resource the server responds with 255 a status code of 200. 257 5.3.3 Deleting a Resource 259 Client Server 260 | | 261 | 1.) DELETE to Member Resource IRI | 262 |------------------------------------------>| 263 | | 264 | 2.) 200 Ok | 265 |<------------------------------------------| 266 | | 268 1. The client sends a DELETE request to the Member's IRI. 270 2. Upon the successful deletion of the resource the server responds 271 with a status code of 200. 273 5.4 Listing Collection Members 275 To list the members of a Collection the client sends a GET request to 276 the Collection's IRI. An Atom Feed Document is returned containing 277 one Atom Entry for each member resource. See Section 9 and 278 Section 10 for a description of the feed contents. 280 Client Server 281 | | 282 | 1.) GET to List IRI | 283 |------------------------------->| 284 | | 285 | 2.) 200 OK, Atom Feed Doc | 286 |<-------------------------------| 287 | | 289 1. The client sends a GET request to the Collection's IRI. 291 2. The server responds with an Atom Feed Document containing the 292 IRIs of all the collection members that match the selection 293 criteria. 295 5.5 Use of HTTP Response codes 297 The Atom Protocol uses the response status codes defined in HTTP to 298 indicate the success or failure of an operation. Consult the HTTP 299 specification [RFC2616] for detailed definitions of each status code. 300 It is strongly recommended that entities contained within HTTP 4xx 301 and 5xx responses include a human readable, natural language 302 explanation of the error. 304 6. XML-related Conventions 306 The data format in this specification is specified in terms of the 307 XML Information Set, serialised as XML 1.0 [W3C.REC-xml-20040204]. 308 Atom Publishing Protocol Documents MUST be well-formed XML. This 309 specification does not define any DTDs for Atom Protocol, and hence 310 does not require them to be "valid" in the sense used by XML. 312 6.1 Referring to Information Items 314 This specification uses a shorthand for two common terms: the phrase 315 "Information Item" is omitted when discussing Element Information 316 Items and Attribute Information Items. Therefore, when this 317 specification uses the term "element," it is referring to an Element 318 Information Item in Infoset terms. Likewise, when it uses the term 319 "attribute," it is referring to an Attribute Information Item. 321 6.2 XML Namespace Usage 323 The namespace name [W3C.REC-xml-names-19990114] for the XML format 324 described in this specification is: 326 http://purl.org/atom/app# 328 This specification uses the prefix "app:" for the namespace name. 329 The choice of namespace prefix is not semantically significant. 331 This specification also uses the prefix "atom:" for 332 "http://www.w3.org/2005/Atom", the namespace name of the Atom 333 Publishing Format [RFC4287]. 335 6.3 Use of xml:base and xml:lang 337 XML elements defined by this specification MAY have an xml:base 338 attribute [W3C.REC-xmlbase-20010627]. When xml:base is used, it 339 serves the function described in section 5.1.1 of [RFC3986], 340 establishing the base URI (or IRI) for resolving any relative 341 references found within the effective scope of the xml:base 342 attribute. 344 Any element defined by this specification MAY have an xml:lang 345 attribute, whose content indicates the natural language for the 346 element and its descendents. The language context is only 347 significant for elements and attributes declared to be "Language- 348 Sensitive" by this specification. Requirements regarding the content 349 and interpretation of xml:lang are specified in Section 2.12 of XML 350 1.0 [W3C.REC-xml-20040204]. 352 appCommonAttributes = 353 attribute xml:base { atomUri }?, 354 attribute xml:lang { atomLanguageTag }?, 355 undefinedAttribute* 357 6.4 RELAX NG Schema 359 Some sections of this specification are illustrated with fragments of 360 a non-normative RELAX NG Compact schema [RNC]. A complete schema 361 appears in Appendix B. However, the text of this specification 362 provides the definition of conformance. 364 7. Introspection Documents 366 For authoring to commence, a client needs to first discover the 367 capabilities and locations of collections offered. This is done 368 using Introspection Documents. An Introspection Document describes 369 workspaces, which are server-defined groupings of collections. 371 Introspection documents are identified with the "application/ 372 atomserv+xml" media type (see Section 15). 374 While an introspection document allows multiple workspaces, there is 375 no requirement that a service support multiple workspaces. In 376 addition, a collection MAY appear in more than one workspace. 378 7.1 Example 380 381 382 383 386 entry 387 http://example.org/{index} 388 389 392 media 393 http://example.org/p/{index} 394 395 396 397 399 entry 400 http://example.org/l/{index} 401 402 403 405 This Introspection Document describes two workspaces. The first, 406 called "Main Site", has two collections called "My Blog Entries" and 407 "Pictures" whose IRIs are "http://example.org/reilly/main" and 408 "http://example.org/reilly/pic" respectively. "My Blog Entries" is 409 an Entry collection and "Pictures" is a Media collection. Entry and 410 Media collections are discussed in Section 7.2.4. 412 The second workspace is called "Side Bar Blog" and has a single 413 collection called "Remaindered Links" whose collection IRI is 414 "http://example.org/reilly/list". "Remaindered Links" is an Entry 415 collection. 417 7.2 Element Definitions 419 7.2.1 The "app:service" Element 421 The root of an introspection document is the "app:service" element. 422 namespace app = "http://purl.org/atom/app#" 423 start = appService 425 The "app:service" element is the container for introspection 426 information associated with one or more workspaces. An app:service 427 element MUST contain one or more app:workspace elements. 429 appService = 430 element app:service { 431 appCommonAttributes, 432 ( appWorkspace+ 433 & extensionElement* ) 434 } 436 7.2.2 The "app:workspace" Element 438 The "app:workspace" element contains information elements about the 439 collections of resources available for editing. The app:workspace 440 element MUST contain one or more app:collection elements. 442 appWorkspace = 443 element app:workspace { 444 appCommonAttributes, 445 attribute title { text }, 446 ( appCollection+ 447 & extensionElement* ) 448 } 450 In an app:workspace element, the first app:collection element SHOULD 451 refer to the preferred or primary collection. In the following 452 example, the "Entries" collection would be considered the "preferred" 453 or "primary" collection of the workspace: 455 456 457 458 459 460 462 7.2.2.1 The "title" Attribute 464 The app:workspace element MUST contain a "title" attribute, which 465 gives a human-readable name for the workspace. This attribute is 466 Language-Sensitive. 468 7.2.3 The "app:collection" Element 470 The "app:collection" describes a collection. This specification 471 defines one child element: app:member-type. 473 appCollection = 474 element app:collection { 475 appCommonAttributes, 476 attribute title { text }, 477 attribute href { text }, 478 ( appMemberType 479 & appListTemplate 480 & extensionElement* ) 481 } 483 7.2.3.1 The "title" Attribute 485 The app:collection element MUST contain a "title" attribute, whose 486 value gives a human-readable name for the collection. This attribute 487 is Language-Sensitive. 489 7.2.3.2 The "href" Attribute 491 The app:collection element MUST contain a "href" attribute, whose 492 value gives the IRI of the collection. 494 7.2.4 The "app:member-type" Element 496 The app:collection element MUST contain one "app:member-type" 497 element. The app:member-type element value specifies the types of 498 members that can appear in the collection. 500 appMemberType = 501 element app:member-type { 502 appCommonAttributes, 503 ( appTypeValue ) 504 } 506 appTypeValue = "entry" | "media" 508 An Entry POSTed to a collection MUST meet the constraints of the app: 509 member-type element. 511 This specification defines two values for the app:member-type 512 element: 514 o "entry" - The collection contains only member resources whose 515 representation MUST be an Atom Entry. Further constraints on the 516 representations of members in a collection of type "entry" are 517 listed in Section 8.2. 519 o "media" - The collection contains member resources whose 520 representation can be of any media type. Additional constraints 521 are listed in Section 8.3. 523 8. Collections 525 8.1 Creating resources with POST 527 To add members to a collection, clients send POST requests to the 528 collection's URI. Collections MAY impose constraints on the media- 529 types that are created in a collection and MAY generate a response 530 with a status code of 415 ("Unsupported Media Type"). On successful 531 creation, the response to the POST request MUST return a Location: 532 header with the URI of the newly created resource. 534 8.1.1 Example 536 Below, the client requests to create a resource with an Atom Entry 537 representation in a collection: 539 POST /edit HTTP/1.1 540 Host: example.org 541 User-Agent: Thingio/1.0 542 Content-Type: application/atom+xml 543 Content-Length: nnn 545 546 Atom-Powered Robots Run Amok 547 548 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 549 2003-12-13T18:30:02Z 550 Some text. 551 552 The resource is created by sending an Atom Entry as the entity body. 554 Successful creation is indicated by a 201 created response and 555 includes a Location: header: 557 HTTP/1.1 201 Created 558 Date: Fri, 7 Oct 2005 17:17:11 GMT 559 Content-Length: 0 560 Location: http://example.org/edit/first-post.atom 562 8.1.2 Title: Header 564 A POST to a collection creating a resource MAY contain a Title: 565 header that indicates the client's suggested title for the resource. 566 The Title header is primarily for use with Media collections and is 567 RECOMMENDED for use with such collections. The server MAY ignore the 568 content of the Title: header or modify the suggested title. 570 Title = "Title" ":" [text] 572 The syntax of this header MUST conform to the augmented BNF grammar 573 in section 2.1 of the HTTP/1.1 specification [RFC2616]. 575 8.2 Entry Collections 577 Entry Collections are collections that restrict their membership to 578 Atom Entries. They are identified by having an app:member-type of 579 "entry". Every member representation MUST contain an atom:link 580 element with a link relation of "edit" that contains the IRI of the 581 member resource. Member representations MAY contain an app:control 582 element (Section 11). 584 8.3 Media Collections 586 Media Collections are collections whose member representations are 587 not constrained. They are identified by having an app:member-type of 588 "media". 590 8.3.1 Editing Media Resources 592 When a membership list resource returns an Atom Feed enumerating the 593 contents of a Media Collection, all the Entries MUST have an atom: 594 content element with a "src" attribute. When creating a public, 595 read-only reference to the member resource, a client SHOULD use the 596 "atom:content/@src" attribute value. 598 9. Listing Collections 600 Collections, as identified in an Introspection Document, are 601 resources that MUST provide representations in the form of Atom Feed 602 documents when dereferencing the collection IRI. The entries in the 603 returned Feed MUST be ordered by their 'atom:updated' property, with 604 the most recently updated entries coming first in the document order. 605 Every entry in the Feed Document MUST have an atom:link element with 606 a relation of "edit" (See Section 10.1). Clients MUST NOT assume 607 that an Atom Entry returned in the Feed is a full representation of a 608 member resource. The value of atom:updated is only changed when the 609 change to a member resource is considered significant. Insignificant 610 changes do not result in changes to the atom:updated value and thus 611 do not change the position of the corresponding entry in a membership 612 list. Clients SHOULD be constructed with this in mind and SHOULD 613 perform a GET on the member resource before editing. 615 Collections can contain large numbers of resources. A naive client 616 such as a web spider or web browser could be overwhelmed if the 617 response to a GET contained every entry in the collection, and the 618 server would waste large amounts of bandwidth and processing time on 619 clients unable to handle the response. For this reason, servers MAY 620 return a partial listing containing the most recently updated member 621 resources. Such partial feed documents MUST have an atom:link with a 622 "next" relation whose "href" value is the IRI of the next partial 623 listing of the collection (the least recently updated member 624 resources) where it exists. This is called "collection paging". 626 9.1 Collection Paging 628 Atom Protocol servers MUST provide representations of collections as 629 Atom feed documents whose entries represent the collection's members. 630 The returned Atom feed MAY NOT contain entries for all the 631 collection's members. Instead, the Atom feed document MAY contain 632 link elements with "rel" attribute values of "next", "previous", 633 "start" and "end" that can be used to navigate through the complete 634 set of matching entries. 636 For instance, suppose the client is supplied this IRI 637 http://example.org/entries/go 639 Supposing the collection contains member entries and the server as a 640 matter of policy wishes to avoid generating feed documents with more 641 than 10 entries, then the resulting Atom feed document represents the 642 first page in a linked set of 10 feed documents. Within each feed 643 document served, "next" and "prev" link elements reference the 644 preceding and subsequent feed documents in the set. The "start" link 645 element references the first feed document in the set. The "end" 646 link element references the final feed document in the set. 648 649 ... 650 652 654 656 658 The 'next' and 'prev' link elements for the feed located at 659 http://example.org/entries/2 would look like this: 661 662 ... 663 665 667 669 671 673 10. Atom Format Link Relation Extensions 675 10.1 The "edit" Link Relation 677 The Atom Protocol adds the value "edit" to the Atom Registry of Link 678 Relations (see section 7.1 of [RFC4287]). The value of "edit" 679 specifies that the IRI in the value of the href attribute is the IRI 680 of the member resource, and is intended to be used to update and 681 delete resources as described in this specification. This link 682 relation MAY appear in both membership lists and in member 683 representations. 685 11. Atom Publishing Control Extensions 687 11.1 The Atom Publishing Control Namespace 689 This specification defines an Atom Format extension for publishing 690 control called Atom Publishing Control. The namespace name for the 691 Atom Publishing Control's XML vocabulary is 692 "http://example.net/appns/". This specification uses "pub:" for the 693 namespace prefix. The choice of namespace prefix is not semantically 694 significant. 696 11.2 The "pub:control" Element 698 namespace pub = "http://example.net/appns/" 700 pubControl = 701 element pub:control { 702 atomCommonAttributes, 703 pubDraft? 704 & extensionElement 705 } 707 pubDraft = 708 element pub:draft { "yes" | "no" } 710 The "pub:control" element MAY appear as a child of an "atom:entry" 711 which is being created or updated via the Atom Publishing Protocol. 712 The "pub:control" element, if it does appear in an entry, MUST only 713 appear at most one time. The "pub:control" element is considered 714 foreign markup as defined in Section 6 of [RFC4287]. 716 The "pub:control" element and its child elements MAY be included in 717 Atom Feed or Entry Documents. 719 The "pub:control" element MAY contain exactly one "pub:draft" element 720 as defined here, and MAY contain zero or more extension elements as 721 outlined in Section 6 of [RFC4287]. Both clients and servers MUST 722 ignore foreign markup present in the pub:control element. 724 11.2.1 The "pub:draft" Element 726 The number of "pub:draft" elements in "pub:control" MUST be zero or 727 one. Its value MUST be one of "yes" or "no". A value of "no" means 728 that the entry may be made publicly visible. If the "pub:draft" 729 element is missing then the value is understood to be "no". If "pub: 730 control" and/or the "pub:draft" elements are missing from an entry 731 then the entry is not considered a draft and can be made publicly 732 visible. 734 12. Atom Publishing Protocol Example 736 This is an example of a client creating a new entry with an image. 737 The client has an image to publish and an entry that includes an HTML 738 "img" element that uses that image. In this scenario we consider a 739 client that has IRIs of two collections, an entry collection and a 740 media collection, both of which were discovered through an 741 introspection document. The IRI of the entry collection is: 743 http://example.net/blog/edit/ 745 The IRI of the media collection is: 747 http://example.net/binary/edit 749 First the client creates a new image resource by POSTing the image to 750 the IRI of the media collection. 752 POST /binary/edit/ HTTP/1.1 753 Host: example.net 754 User-Agent: Thingio/1.0 755 Content-Type: image/png 756 Content-Length: nnnn 757 Title: A picture of the beach 759 ...binary data... 761 The member resource is created and an HTTP status code of 201 is 762 returned. 764 HTTP/1.1 201 Created 765 Date: Fri, 25 Mar 2005 17:17:11 GMT 766 Content-Length: nnnn 767 Content-Type: application/atom+xml 768 Location: http://example.net/binary/edit/b/129.png 770 771 772 A picture of the beach. 773 775 urn:uuid:1225c695-cfb8-4ebb-aaaa-568596895695 776 2005-09-02T10:30:00Z 777 Waves 778 780 781 The client then POSTs the Atom Entry that refers to the newly created 782 image resource. Note that the client takes the IRI 783 http://example.net/binary/readonly/129.png and uses it in the 'img' 784 element in the Entry content: 786 POST /blog/edit/ HTTP/1.1 787 Host: example.net 788 User-Agent: Thingio/1.0 789 Content-Type: application/atom+xml 790 Content-Length: nnnn 792 793 794 What I did on my summer vacation 795 796 urn:uuid:1225c695-ffb8-4ebb-aaaa-80da354efa6a 797 2005-09-02T10:30:00Z 798 Beach! 799 800
801

We went to the beach for summer vacation. 802 Here is a picture of the waves rolling in: 803 A picture of the beach. 807

808
809 810 812 13. Securing the Atom Protocol 814 All instances of publishing Atom Format entries SHOULD be protected 815 by authentication to prevent posting or editing by unknown sources. 816 Atom Protocol servers and clients MUST support one of the following 817 authentication mechanisms, and SHOULD support both. 819 o HTTP Digest Authentication [RFC2617] 821 o CGI Authentication 823 Atom Protocol servers and clients MAY support encryption of the 824 session using TLS (see [RFC2246]). 826 There are cases where an authentication mechanism is not be required, 827 such as a publicly editable Wiki, or when using POST to send comments 828 to a site that does not require authentication from a commenter. 830 13.1 CGI Authentication 832 [[anchor26: This section is incomplete; cgi-authentication is 833 described but is unspecified.]] This authentication method is 834 included as part of the protocol to allow Atom Protocol servers and 835 clients that cannot use HTTP Digest Authentication but where the user 836 can both insert its own HTTP headers and create a CGI program to 837 authenticate entries to the server. This scenario is common in 838 environments where the user cannot control what services the server 839 employs, but the user can write their own HTTP services. 841 14. Security Considerations 843 The security of the Atom Protocol is based on HTTP Digest 844 Authentication and/or CGI Authentication [[anchor28: refers to 845 incomplete section]]. Any weaknesses in either of these 846 authentication schemes will affect the security of the Atom 847 Publishing Protocol. 849 Both HTTP Digest Authentication and CGI Authentication [[anchor29: 850 refers to incomplete section]] are susceptible to dictionary-based 851 attacks on the shared secret. If the shared secret is a password 852 (instead of a random string with sufficient entropy), an attacker can 853 determine the secret by exhaustively comparing the authenticating 854 string with hashed results of the public string and dictionary 855 entries. 857 See [RFC2617] for the description of the security properties of HTTP 858 Digest Authentication. 860 [[anchor30: expand on HTTP basic and digest authentication, or 861 refer.]] 863 [[anchor31: talk here about denial of service attacks using large XML 864 files, or the billion laughs DTD attack.]] 866 15. IANA Considerations 868 An Atom Publishing Protocol Introspection Document, when serialized 869 as XML 1.0, can be identified with the following media type: 871 MIME media type name: application 873 MIME subtype name: atomserv+xml 875 Mandatory parameters: None. 877 Optional parameters: 879 "charset": This parameter has identical semantics to the charset 880 parameter of the "application/xml" media type as specified in 881 [RFC3023]. 883 Encoding considerations: Identical to those of "application/xml" as 884 described in [RFC3023], section 3.2. 886 Security considerations: As defined in this specification. 887 [[anchor32: update upon publication]] 889 In addition, as this media type uses the "+xml" convention, it 890 shares the same security considerations as described in [RFC3023], 891 section 10. 893 Interoperability considerations: There are no known interoperability 894 issues. 896 Published specification: This specification. [[anchor33: update upon 897 publication]] 899 Applications that use this media type: No known applications 900 currently use this media type. 902 Additional information: 904 Magic number(s): As specified for "application/xml" in [RFC3023], 905 section 3.2. 907 File extension: .atomsrv 909 Fragment identifiers: As specified for "application/xml" in 910 [RFC3023], section 5. 912 Base URI: As specified in [RFC3023], section 6. 914 Macintosh File Type code: TEXT 916 Person and email address to contact for further information: Joe 917 Gregorio 919 Intended usage: COMMON 921 Author/Change controller: This specification's author(s). [[anchor34: 922 update upon publication]] 924 16. References 926 16.1 Normative References 928 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 929 Requirement Levels", BCP 14, RFC 2119, March 1997. 931 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 932 RFC 2246, January 1999. 934 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 935 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 936 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 938 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 939 Leach, P., Luotonen, A., and L. Stewart, "HTTP 940 Authentication: Basic and Digest Access Authentication", 941 RFC 2617, June 1999. 943 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 944 Types", RFC 3023, January 2001. 946 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 947 Resource Identifier (URI): Generic Syntax", STD 66, 948 RFC 3986, January 2005. 950 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 951 Identifiers (IRIs)", RFC 3987, January 2005. 953 [RFC4287] Nottingham, M. and R. Sayre, "The Atom Syndication 954 Format", RFC 4287, December 2005. 956 [W3C.REC-xml-20040204] 957 Yergeau, F., Paoli, J., Sperberg-McQueen, C., Bray, T., 958 and E. Maler, "Extensible Markup Language (XML) 1.0 (Third 959 Edition)", W3C REC REC-xml-20040204, February 2004. 961 [W3C.REC-xml-names-19990114] 962 Hollander, D., Bray, T., and A. Layman, "Namespaces in 963 XML", W3C REC REC-xml-names-19990114, January 1999. 965 [W3C.REC-xmlbase-20010627] 966 Marsh, J., "XML Base", W3C REC W3C.REC-xmlbase-20010627, 967 June 2001. 969 16.2 Informative References 971 [RNC] Clark, J., "RELAX NG Compact Syntax", December 2001. 973 [W3C.REC-webarch-20041215] 974 Walsh, N. and I. Jacobs, "Architecture of the World Wide 975 Web, Volume One", W3C REC REC-webarch-20041215, 976 December 2004. 978 URIs 980 [1] 982 Authors' Addresses 984 Joe Gregorio (editor) 985 BitWorking, Inc 986 1002 Heathwood Dairy Rd. 987 Apex, NC 27502 988 US 990 Phone: +1 919 272 3764 991 Email: joe@bitworking.com 992 URI: http://bitworking.com/ 994 Bill de hOra (editor) 995 Propylon Ltd. 996 45 Blackbourne Square, Rathfarnham Gate 997 Dublin, Dublin D14 998 IE 1000 Phone: +353-1-4927444 1001 Email: bill.dehora@propylon.com 1002 URI: http://www.propylon.com/ 1004 Appendix A. Contributors 1006 The content and concepts within are a product of the Atom community 1007 and the Atompub Working Group. 1009 Appendix B. RELAX NG Compact Schema 1011 This appendix is informative. 1013 The Relax NG schema explicitly excludes elements in the Atom Protocol 1014 namespace which are not defined in this revision of the 1015 specification. Requirements for Atom Protocol processors 1016 encountering such markup are given in Section 6.2 and Section 6.3 of 1017 [RFC4287]. 1019 # -*- rnc -*- 1020 # RELAX NG Compact Syntax Grammar for the Atom Protocol 1022 namespace app = "http://purl.org/atom/app#" 1023 namespace local = "" 1025 start = appService 1027 # common:attrs 1029 appCommonAttributes = 1030 attribute xml:base { atomUri }?, 1031 attribute xml:lang { atomLanguageTag }?, 1032 undefinedAttribute* 1034 undefinedAttribute = 1035 attribute * - (xml:base | xml:lang | local:*) { text } 1037 atomUri = text 1039 atomLanguageTag = xsd:string { 1040 pattern = "[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*" 1041 } 1043 # app:service 1045 appService = 1046 element app:service { 1047 appCommonAttributes, 1048 ( appWorkspace+ 1049 & extensionElement* ) 1050 } 1052 # app:workspace 1054 appWorkspace = 1055 element app:workspace { 1056 appCommonAttributes, 1057 attribute title { text }, 1058 ( appCollection+ 1059 & extensionElement* ) 1060 } 1062 # app:collection 1064 appCollection = 1065 element app:collection { 1066 appCommonAttributes, 1067 attribute title { text }, 1068 attribute href { text }, 1069 ( appMemberType 1070 & appListTemplate 1071 & extensionElement* ) 1072 } 1074 # app:member 1076 appMemberType = 1077 element app:member-type { 1078 appCommonAttributes, 1079 ( appTypeValue ) 1080 } 1082 appTypeValue = "entry" | "media" 1084 # app:list-template 1086 appListTemplate = 1087 element app:list-template { 1088 appCommonAttributes, 1089 ( appUriTemplate ) 1090 } 1092 # Whatever an IRI template is, it contains at least {index} 1094 appUriTemplate = xsd:string { pattern = ".+\{index\}.*" } 1096 # Simple Extension 1098 simpleExtensionElement = 1099 element * - app:* { 1100 text 1101 } 1103 # Structured Extension 1105 structuredExtensionElement = 1106 element * - app:* { 1107 (attribute * { text }+, 1108 (text|anyElement)*) 1109 | (attribute * { text }*, 1110 (text?, anyElement+, (text|anyElement)*)) 1111 } 1113 # Other Extensibility 1115 extensionElement = 1116 simpleExtensionElement | structuredExtensionElement 1118 # Extensions 1120 anyElement = 1121 element * { 1122 (attribute * { text } 1123 | text 1124 | anyElement)* 1125 } 1127 # EOF 1129 Appendix C. Revision History 1131 draft-ietf-atompub-protocol-07: updated Atom refs to RFC4287; 1132 incorporated PaceBetterHttpResponseCode; 1133 PaceClarifyCollectionAndDeleteMethodByWritingLessInsteadOfMore; 1134 PaceRemoveAcceptPostText; PaceRemoveListTemplate2; 1135 PaceRemoveRegistry; PaceRemoveWhoWritesWhat; 1136 PaceSimplifyClarifyBetterfyRemoveBogusValidityText; 1137 PaceCollectionOrderSignificance; PaceFixLostIntrospectionText; 1138 PaceListPaging; PaceCollectionControl; element typo in Listing 1139 collections para3 (was app:member-type, not app:list-template); 1140 changed post atom entry example to be valid. Dropped inline use of 1141 'APP'. Removed nested diagram from section 4. Added ed notes in the 1142 security section. 1144 draft-ietf-atompub-protocol-06 - Removed: Robert Sayre from the 1145 contributors section per his request. Added in 1146 PaceCollectionControl. Fixed all the {daterange} verbage and 1147 examples so they all use a dash. Added full rnc schema. Collapsed 1148 Introspection and Collection documents into a single document. 1149 Removed {dateRange} queries. Renamed search to list. Moved 1150 discussion of media and entry collection until later in the document 1151 and tied the discussion to the Introspection element app:member-type. 1153 draft-ietf-atompub-protocol-05 - Added: Contributors section. Added: 1154 de hOra to editors. Fixed: typos. Added diagrams and description to 1155 model section. Incorporates PaceAppDocuments, PaceAppDocuments2, 1156 PaceSimplifyCollections2 (large-sized chunks of it anyhow: the 1157 notions of Entry and Generic resources, the section 4 language on the 1158 Protocol Model, 4.1 through 4.5.2, the notion of a Collection 1159 document, as in Section 5 through 5.3, Section 7 "Collection 1160 resources", Selection resources (modified from pace which talked 1161 about search); results in major mods to Collection Documents, Section 1162 9.2 "Title: Header" and brokeout para to section 9.1 Editing Generic 1163 Resources). Added XML namespace and language section. Some cleanup 1164 of front matter. Added Language Sensitivity to some attributes. 1165 Removed resource descriptions from terminology. Some juggling of 1166 sections. See: 1167 http://www.imc.org/atom-protocol/mail-archive/msg01812.html. 1169 draft-ietf-atompub-protocol-04 - Add ladder diagrams, reorganize, add 1170 SOAP interactions 1172 draft-ietf-atompub-protocol-03 - Incorporates PaceSliceAndDice3 and 1173 PaceIntrospection. 1175 draft-ietf-atompub-protocol-02 - Incorporates Pace409Response, 1176 PacePostLocationMust, and PaceSimpleResourcePosting. 1178 draft-ietf-atompub-protocol-01 - Added in sections on Responses for 1179 the EditURI. Allow 2xx for response to EditURI PUTs. Elided all 1180 mentions of WSSE. Started adding in some normative references. 1181 Added the section "Securing the Atom Protocol". Clarified that it is 1182 possible that the PostURI and FeedURI could be the same URI. Cleaned 1183 up descriptions for Response codes 400 and 500. 1185 Rev draft-ietf-atompub-protocol-00 - 5Jul2004 - Renamed the file and 1186 re-titled the document to conform to IETF submission guidelines. 1187 Changed MIME type to match the one selected for the Atom format. 1188 Numerous typographical fixes. We used to have two 'Introduction' 1189 sections. One of them was moved into the Abstract the other absorbed 1190 the Scope section. IPR and copyright notifications were added. 1192 Rev 09 - 10Dec2003 - Added the section on SOAP enabled clients and 1193 servers. 1195 Rev 08 - 01Dec2003 - Refactored the specification, merging the 1196 Introspection file into the feed format. Also dropped the 1197 distinction between the type of URI used to create new entries and 1198 the kind used to create comments. Dropped user preferences. 1200 Rev 07 - 06Aug2003 - Removed the use of the RSD file for auto- 1201 discovery. Changed copyright until a final standards body is chosen. 1202 Changed query parameters for the search facet to all begin with atom- 1203 to avoid name collisions. Updated all the Entries to follow the 0.2 1204 version. Changed the format of the search results and template file 1205 to a pure element based syntax. 1207 Rev 06 - 24Jul2003 - Moved to PUT for updating Entries. Changed all 1208 the mime-types to application/x.atom+xml. Added template editing. 1209 Changed 'edit-entry' to 'create-entry' in the Introspection file to 1210 more accurately reflect its purpose. 1212 Rev 05 - 17Jul2003 - Renamed everything Echo into Atom. Added 1213 version numbers in the Revision history. Changed all the mime-types 1214 to application/atom+xml. 1216 Rev 04 - 15Jul2003 - Updated the RSD version used from 0.7 to 1.0. 1217 Change the method of deleting an Entry from POSTing to 1218 using the HTTP DELETE verb. Also changed the query interface to GET 1219 instead of POST. Moved Introspection Discovery to be up under 1220 Introspection. Introduced the term 'facet' for the services listed 1221 in the Introspection file. 1223 Rev 03 - 10Jul2003 - Added a link to the Wiki near the front of the 1224 document. Added a section on finding an Entry. Retrieving an Entry 1225 now broken out into its own section. Changed the HTTP status code 1226 for a successful editing of an Entry to 205. 1228 Rev 02 - 7Jul2003 - Entries are no longer returned from POSTs, 1229 instead they are retrieved via GET. Cleaned up figure titles, as 1230 they are rendered poorly in HTML. All content-types have been 1231 changed to application/atom+xml. 1233 Rev 01 - 5Jul2003 - Renamed from EchoAPI.html to follow the more 1234 commonly used format: draft-gregorio-NN.html. Renamed all references 1235 to URL to URI. Broke out introspection into its own section. Added 1236 the Revision History section. Added more to the warning that the 1237 example URIs are not normative. 1239 Intellectual Property Statement 1241 The IETF takes no position regarding the validity or scope of any 1242 Intellectual Property Rights or other rights that might be claimed to 1243 pertain to the implementation or use of the technology described in 1244 this document or the extent to which any license under such rights 1245 might or might not be available; nor does it represent that it has 1246 made any independent effort to identify any such rights. Information 1247 on the procedures with respect to rights in RFC documents can be 1248 found in BCP 78 and BCP 79. 1250 Copies of IPR disclosures made to the IETF Secretariat and any 1251 assurances of licenses to be made available, or the result of an 1252 attempt made to obtain a general license or permission for the use of 1253 such proprietary rights by implementers or users of this 1254 specification can be obtained from the IETF on-line IPR repository at 1255 http://www.ietf.org/ipr. 1257 The IETF invites any interested party to bring to its attention any 1258 copyrights, patents or patent applications, or other proprietary 1259 rights that may cover technology that may be required to implement 1260 this standard. Please address the information to the IETF at 1261 ietf-ipr@ietf.org. 1263 The IETF has been notified of intellectual property rights claimed in 1264 regard to some or all of the specification contained in this 1265 document. For more information consult the online list of claimed 1266 rights. 1268 Disclaimer of Validity 1270 This document and the information contained herein are provided on an 1271 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1272 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1273 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1274 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1275 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1276 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1278 Copyright Statement 1280 Copyright (C) The Internet Society (2006). This document is subject 1281 to the rights, licenses and restrictions contained in BCP 78, and 1282 except as set forth therein, the authors retain all their rights. 1284 Acknowledgment 1286 Funding for the RFC Editor function is currently provided by the 1287 Internet Society.