idnits 2.17.1 draft-ietf-atompub-protocol-13.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, updated by RFC 4748 on line 2296. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2307. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2314. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2320. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC4287], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust 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 (February 5, 2007) is 6289 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 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 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 4346 (Obsoleted by RFC 5246) Summary: 7 errors (**), 0 flaws (~~), 1 warning (==), 8 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 IBM 4 Intended status: Standards Track B. de hOra, Ed. 5 Expires: August 9, 2007 Propylon Ltd. 6 February 5, 2007 8 The Atom Publishing Protocol 9 draft-ietf-atompub-protocol-13.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 August 9, 2007. 36 Copyright Notice 38 Copyright (C) The IETF Trust (2007). 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 49 To provide feedback on this Internet-Draft, join the atom-protocol 50 mailing list (http://www.imc.org/atom-protocol/index.html) [1]. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 6 56 2.1. XML-related Conventions . . . . . . . . . . . . . . . . . 6 57 2.1.1. Referring to Information Items . . . . . . . . . . . . 6 58 2.1.2. RELAX NG Schema . . . . . . . . . . . . . . . . . . . 6 59 2.1.3. Use of xml:base and xml:lang . . . . . . . . . . . . . 6 60 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 4. Protocol Model . . . . . . . . . . . . . . . . . . . . . . . . 8 62 4.1. Client Implementation Considerations . . . . . . . . . . . 9 63 5. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 11 64 5.1. Retrieving a Service Document . . . . . . . . . . . . . . 11 65 5.2. Listing Collection Members . . . . . . . . . . . . . . . . 11 66 5.3. Creating a Resource . . . . . . . . . . . . . . . . . . . 12 67 5.4. Editing a Resource . . . . . . . . . . . . . . . . . . . . 12 68 5.4.1. Retrieving a Resource . . . . . . . . . . . . . . . . 12 69 5.4.2. Updating a Resource . . . . . . . . . . . . . . . . . 13 70 5.4.3. Deleting a Resource . . . . . . . . . . . . . . . . . 13 71 5.5. Use of HTTP Response codes . . . . . . . . . . . . . . . . 13 72 6. Atom Publishing Protocol Documents . . . . . . . . . . . . . . 14 73 6.1. Document Types . . . . . . . . . . . . . . . . . . . . . . 14 74 6.2. Document Extensibility . . . . . . . . . . . . . . . . . . 14 75 7. Category Documents . . . . . . . . . . . . . . . . . . . . . . 16 76 7.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 16 77 7.2. Element Definitions . . . . . . . . . . . . . . . . . . . 16 78 7.2.1. The "app:categories" element . . . . . . . . . . . . . 16 79 8. Service Documents . . . . . . . . . . . . . . . . . . . . . . 18 80 8.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 19 81 8.2. Element Definitions . . . . . . . . . . . . . . . . . . . 20 82 8.2.1. The "app:service" Element . . . . . . . . . . . . . . 20 83 8.2.2. The "app:workspace" Element . . . . . . . . . . . . . 20 84 8.2.3. The "app:collection" Element . . . . . . . . . . . . . 21 85 8.2.4. The "app:accept" Element . . . . . . . . . . . . . . . 21 86 8.2.5. The "app:categories" Element . . . . . . . . . . . . . 22 87 9. Creating and Editing Resources . . . . . . . . . . . . . . . . 24 88 9.1. Member URIs . . . . . . . . . . . . . . . . . . . . . . . 24 89 9.2. Creating resources with POST . . . . . . . . . . . . . . . 24 90 9.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 25 91 9.3. Updating Resources with PUT . . . . . . . . . . . . . . . 26 92 9.4. Deleting Resources with DELETE . . . . . . . . . . . . . . 26 93 9.5. Media Resources and Media Link Entries . . . . . . . . . . 26 94 9.5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 27 95 9.6. The Slug: Header . . . . . . . . . . . . . . . . . . . . . 32 96 9.6.1. Slug: Header syntax . . . . . . . . . . . . . . . . . 33 97 9.6.2. Example . . . . . . . . . . . . . . . . . . . . . . . 33 98 10. Listing Collections . . . . . . . . . . . . . . . . . . . . . 34 99 10.1. Collection Paging . . . . . . . . . . . . . . . . . . . . 34 100 10.2. The "app:edited" Element . . . . . . . . . . . . . . . . . 35 101 11. Atom Format Link Relation Extensions . . . . . . . . . . . . . 36 102 11.1. The "edit" Link Relation . . . . . . . . . . . . . . . . . 36 103 11.2. The "edit-media" Link Relation . . . . . . . . . . . . . . 36 104 12. The Atom Format Type Parameter . . . . . . . . . . . . . . . . 37 105 12.1. The 'type' parameter . . . . . . . . . . . . . . . . . . . 37 106 12.1.1. Conformance . . . . . . . . . . . . . . . . . . . . . 37 107 13. Atom Publishing Controls . . . . . . . . . . . . . . . . . . . 38 108 13.1. The "app:control" Element . . . . . . . . . . . . . . . . 38 109 13.1.1. The "app:draft" Element . . . . . . . . . . . . . . . 38 110 14. Securing the Atom Publishing Protocol . . . . . . . . . . . . 39 111 15. Security Considerations . . . . . . . . . . . . . . . . . . . 40 112 15.1. Denial of Service . . . . . . . . . . . . . . . . . . . . 40 113 15.2. Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 40 114 15.3. Spoofing Attacks . . . . . . . . . . . . . . . . . . . . . 40 115 15.4. Linked Resources . . . . . . . . . . . . . . . . . . . . . 40 116 15.5. Digital Signatures and Encryption . . . . . . . . . . . . 40 117 15.6. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 40 118 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 119 16.1. Content-type registration for 120 'application/atomserv+xml' . . . . . . . . . . . . . . . . 41 121 16.2. Content-type registration for 'application/atomcat+xml' . 42 122 16.3. Header field registration for 'SLUG' . . . . . . . . . . . 43 123 16.4. The Link Relation registration "edit" . . . . . . . . . . 44 124 16.5. The Link Relation registration "edit-media" . . . . . . . 44 125 16.6. The Atom Format Media Type Parameter . . . . . . . . . . . 44 126 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 45 127 17.1. Normative References . . . . . . . . . . . . . . . . . . . 45 128 17.2. Informative References . . . . . . . . . . . . . . . . . . 46 129 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 48 130 Appendix B. RELAX NG Compact Schema . . . . . . . . . . . . . . . 49 131 Appendix C. Revision History . . . . . . . . . . . . . . . . . . 55 132 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 58 133 Intellectual Property and Copyright Statements . . . . . . . . . . 59 135 1. Introduction 137 The Atom Publishing Protocol is an application-level protocol for 138 publishing and editing Web resources using HTTP [RFC2616] and XML 1.0 139 [W3C.REC-xml]. The protocol supports the creation of Web resources 140 and provides facilities for: 142 o Collections: Sets of resources, which can be retrieved in whole or 143 in part. 145 o Service: Discovering and describing Collections. 147 o Editing: Creating, updating and deleting resources. 149 The Atom Publishing Protocol is different from many contemporary 150 protocols in that the server is given wide latitude in processing 151 requests from clients. See Section 4 for more details. 153 2. Notational Conventions 155 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 156 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 157 document are to be interpreted as described in [RFC2119]. 159 2.1. XML-related Conventions 161 2.1.1. Referring to Information Items 163 Atom Protocol Document formats are specified in terms of the XML 164 Information Set [W3C.REC-xml-infoset], serialized as XML 1.0 165 [W3C.REC-xml]. 167 The Infoset terms "Element Information Item" and "Attribute 168 Information Item" are shortened to "element" and "attribute" 169 respectively. Therefore, when this specification uses the term 170 "element", it is referring to an Element Information Item, and when 171 it uses the term "attribute", it is referring to an Attribute 172 Information Item. 174 2.1.2. RELAX NG Schema 176 Some sections of this specification are illustrated with fragments of 177 a non-normative RELAX NG Compact schema [RNC]. However, the text of 178 this specification provides the definition of conformance. Complete 179 schemas appear in Appendix B. 181 2.1.3. Use of xml:base and xml:lang 183 XML elements defined by this specification MAY have an xml:base 184 attribute [W3C.REC-xmlbase-20010627]. When xml:base is used, it 185 serves the function described in Section 5.1.1 of URI Generic Syntax 186 [RFC3986], by establishing the base URI (or IRI) for resolving 187 relative references found within the scope of the xml:base attribute. 189 Any element defined by this specification MAY have an xml:lang 190 attribute, whose content indicates the natural language for the 191 element and its descendents. The language context is only 192 significant for elements and attributes declared to be "Language- 193 Sensitive" by this specification. Requirements regarding the content 194 and interpretation of xml:lang are specified in Section 2.12 of XML 195 1.0 [W3C.REC-xml]. 197 3. Terminology 199 For convenience, this protocol can be referred to as the "Atom 200 Protocol" or "APP". 202 URI/IRI - A Uniform Resource Identifier and Internationalized 203 Resource Identifier. These terms and the distinction between them 204 are defined in [RFC3986] and [RFC3987]. Before an IRI found in a 205 document is used by HTTP, the IRI is first converted to a URI (see 206 Section 4). 208 The phrase "the URI of a document" in this specification is shorthand 209 for "a URI which, when dereferenced, is expected to produce that 210 document as a representation". 212 Resource - A network-accessible data object or service identified by 213 an IRI, as defined in [RFC2616]. See [W3C.REC-webarch-20041215] for 214 further discussion on resources. 216 Representation - An entity included with a request or response as 217 defined in [RFC2616]. 219 Collection - A resource that contains a set of Member Entries. See 220 Section 9. 222 Member - A resource whose IRI is listed in a Collection by a link 223 element with a relation of "edit" or "edit-media". See Section 9.1. 225 Workspace - A named group of Collections. See Section 8. 227 Service Document - A document that describes the location and 228 capabilities of one or more Collections. See Section 8. 230 Category Document - A document that describes the categories allowed 231 in a Collection. See Section 7. 233 4. Protocol Model 235 The Atom Publishing Protocol uses HTTP methods to author Member 236 Resources as follows: 238 o GET is used to retrieve a representation of a known resource. 240 o POST is used to create a new, dynamically-named, resource. When 241 the client submits non-Atom-Entry representations to a Collection 242 for creation, two resources are always created - a Media Entry for 243 the requested resource, and a Media Link Entry for metadata (in 244 Atom Entry format) about the resource. 246 o PUT is used to update a known resource. 248 o DELETE is used to remove a known resource. 250 This document does not specify the form of the URIs that are used. 251 HTTP ([RFC2616]) specifies that the URI space of each server is 252 controlled by that server and the Atom Protocol imposes no 253 constraints on that control. What this RFC does specify are the 254 formats of the representations that are exchanged and the actions 255 that can be performed on the IRIs embedded in those documents. 257 This document only covers the creation, update and deletion of Entry 258 and Media resources. Other resources can be created, updated, and 259 deleted as the result of manipulating a Collection, but the number of 260 those resources, their media-types, and effects of Atom Protocol 261 operations on them are outside the scope of this specification. 263 Since all aspects of client-server interaction are defined in terms 264 of HTTP, [RFC2616] should be consulted for any areas not covered in 265 this specification. 267 Along with operations on Member Resources, the Atom Protocol defines 268 Collection Resources for managing and organizing Member Resources. 269 Collections are represented by Atom Feed documents and contain the 270 IRIs of, and metadata about, their Member Resources. The Atom 271 Protocol does not make a structural distinction between Feeds used 272 for Collections and other Atom Feeds. The only mechanism that this 273 specification supplies for distinguishing a Collection Feed is its 274 appearance in a Service Document. 276 Atom Protocol documents allow the use of IRIs [RFC3987], as well as 277 URIs [RFC3986]. Before an IRI found in a document is used by HTTP, 278 the IRI is first converted to a URI according the procedure defined 279 in Section 3.1 of [RFC3987]. In accordance with that specification, 280 this conversion SHOULD be applied as late as possible. The IRI, and 281 the URI into which it is converted, identify the same resource. 283 There are two kinds of Member Resources - Member Entry Resources and 284 Media Resources. Member Entry Resources are represented as Atom 285 Entries [RFC4287]. Media Resources can have representations in any 286 media type. A Media Link Entry is a Member Entry that contains 287 metadata about a Media Resource. This diagram shows the 288 classification of the resources: 290 Member Resource 291 -> Member Entry Resource 292 -> Media Link Entry Resource 293 -> Media Resource 295 A Collection's Atom Entries contain the Member Entry and Media 296 Resources IRIs of the Collection. A Collection can contain any 297 number of Entries for either kind. In the diagram of a Collection 298 below, there are two Entries. The first contains the IRI of a Member 299 Entry Resource. The second contains the IRIs of both a Media 300 Resource and a Media Link Entry Resource, which contains the metadata 301 for that Media Resource: 303 Collection 304 Entry 305 Member Entry IRI -> Member Entry Resource 307 Entry 308 Member Entry IRI -> Media Link Entry Resource 309 Media IRI -> Media Resource 311 Service Documents represent server-defined groups of Collections, and 312 are used to initialize the process of creating and editing resources. 314 4.1. Client Implementation Considerations 316 The Atom Protocol imposes few restrictions on the actions of servers. 317 Unless a constraint is specified here, servers can be expected to 318 vary in behavior, in particular around the manipulation of Atom 319 Entries sent by clients. For example, although this specification 320 only defines the expected behavior of Collections with respect to GET 321 and POST, this does not imply that PUT, DELETE, PROPPATCH and others 322 are forbidden on Collection resources - only that this specification 323 does not define what the servers response would be to those methods. 324 Similarly while some HTTP status codes are mentioned explicitly, 325 clients should be prepared to handle any status code from a server. 326 Servers can choose to accept, reject, delay, moderate, censor, 327 reformat, translate, relocate or recategorize the content submitted 328 to them. Only some of these choices are immediately relayed back to 329 the client in responses to client requests; other choices may only 330 become apparent later, in the feed or published entries. The same 331 series of requests to two different publishing sites can result in a 332 different series of HTTP responses, different resulting feeds or 333 different entry contents. 335 As a result, client software has to be written flexibly to accept 336 what the server decides are the results of its submissions. Any 337 server response or server content modification not explicitly 338 forbidden by this specification or HTTP ([RFC2616]) is therefore 339 allowed. 341 5. Protocol Operations 343 5.1. Retrieving a Service Document 345 Client Server 346 | | 347 | 1.) GET to Service Document | 348 |------------------------------------------>| 349 | | 350 | 2.) Service Document | 351 |<------------------------------------------| 352 | | 354 1. The client sends a GET request using the URI of the Service 355 Document. 357 2. The server responds with the document enumerating the IRIs of a 358 group of Collections and the capabilities of those Collections 359 supported by the server. The content of this document can vary 360 based on aspects of the client request, including, but not 361 limited to, authentication credentials. 363 5.2. Listing Collection Members 365 To list the members of a Collection, the client sends a GET request 366 to the URI of a Collection. An Atom Feed Document is returned whose 367 Entries contain the IRIs of Member Resources. The returned Feed may 368 describe all, or only a subset, of the Members in a Collection (see 369 Section 10). Section 11 describes extensions to the Atom Syndication 370 Format used in the Atom Protocol. 372 Client Server 373 | | 374 | 1.) GET to Collection URI | 375 |------------------------------->| 376 | | 377 | 2.) Atom Feed Doc | 378 |<-------------------------------| 379 | | 381 1. The client sends a GET request to the URI of the Collection. 383 2. The server responds with an Atom Feed Document containing the 384 IRIs of the Collection members. 386 5.3. Creating a Resource 388 Client Server 389 | | 390 | 1.) POST to URI of Collection | 391 |------------------------------------------>| 392 | | 393 | 2.) 201 Created | 394 | Location: Member Entry URI | 395 |<------------------------------------------| 396 | | 398 1. The client POSTs a representation of the Member to the URI of the 399 Collection. 401 2. If the Member Resource was created successfully, the server 402 responds with a status code of 201 and a Location: header that 403 contains the IRI of the newly created Member Entry Resource. 404 Media Resources could have also been created and their IRIs can 405 be found through the Member Entry Resource. See Section 9.5 for 406 more details. 408 5.4. Editing a Resource 410 Once a resource has been created and its Member URI is known, that 411 URI can be used to retrieve, update, and delete the resource. 413 5.4.1. Retrieving a Resource 415 Client Server 416 | | 417 | 1.) GET to Member URI | 418 |------------------------------------------>| 419 | | 420 | 2.) Member Representation | 421 |<------------------------------------------| 422 | | 424 1. The client sends a GET request to the URI of a Member Resource to 425 retrieve its representation. 427 2. The server responds with the representation of the resource. 429 5.4.2. Updating a Resource 431 Client Server 432 | | 433 | 1.) PUT to Member URI | 434 |------------------------------------------>| 435 | | 436 | 2.) 200 OK | 437 |<------------------------------------------| 439 1. The client PUTs an updated representation to the URI of a Member 440 Resource. 442 2. If the update is successful the server responds with a status 443 code of 200. 445 5.4.3. Deleting a Resource 447 Client Server 448 | | 449 | 1.) DELETE to Member URI | 450 |------------------------------------------>| 451 | | 452 | 2.) 200 Ok | 453 |<------------------------------------------| 454 | | 456 1. The client sends a DELETE request to the URI of a Member 457 Resource. 459 2. If the deletion is successful the server responds with a status 460 code of 200. 462 A different approach is taken for deleting Media Resources, see 463 Section 9.5 for details. 465 5.5. Use of HTTP Response codes 467 The Atom Protocol uses the response status codes defined in HTTP to 468 indicate the success or failure of an operation. Consult the HTTP 469 specification [RFC2616] for detailed definitions of each status code. 470 Implementers are asked to note that according to the HTTP 471 specification, HTTP 4xx and 5xx response entities SHOULD include a 472 human-readable explanation of the error. 474 6. Atom Publishing Protocol Documents 476 6.1. Document Types 478 This specification describes two kinds of Documents - Category 479 Documents and Service Documents. 481 A Category Document (Section 7) contains lists of categories 482 specified using the "atom:category" element from the Atom Syndication 483 Format. A Service Document (Section 8) describes Workspaces, which 484 are server-defined groups of Collections. This specification assigns 485 no meaning to Workspaces; that is, a Workspace does not imply any 486 specific processing assumptions. Operations on Workspaces 487 themselves, such as creation or deletion, are not defined by this 488 specification. 490 The namespace name [W3C.REC-xml-names] for either kind of document 491 is: 492 http://purl.org/atom/app# 494 [[anchor8: The namespace name needs to be updated with the final URI 495 upon publication]] 497 This specification uses the prefix "app:" for the namespace name. 498 The prefix "atom:" is used for "http://www.w3.org/2005/Atom", the 499 namespace name of the Atom Syndication Format [RFC4287]. The 500 namespace prefixes are not semantically significant. 502 Atom Publishing Protocol Documents MUST be well-formed XML. This 503 specification does not define any DTDs for Atom Protocol formats, and 504 hence does not require them to be "valid" in the sense used by XML. 506 6.2. Document Extensibility 508 Unrecognized markup in an Atom Publishing Protocol document is 509 considered "foreign markup" as defined in [RFC4287]. Such foreign 510 markup can be used anywhere within a Category or Service Document 511 unless it is explicitly forbidden. Processors that encounter foreign 512 markup MUST NOT stop processing and MUST NOT signal an error. 513 Clients SHOULD preserve foreign markup when transmitting such 514 documents. 516 The namespace name "http://purl.org/atom/app#" is reserved for 517 forward compatible revisions of the Category and Service Document 518 types - this does not exclude the addition of elements and attributes 519 that might not be recognized by processors conformant to this 520 specification. Such unrecognized markup from the 521 "http://purl.org/atom/app#" namespace MUST be treated as foreign 522 markup. 524 [[anchor9: The namespace name needs to be updated with the final URI 525 upon publication]] 527 7. Category Documents 529 Category Documents contain lists of categories described using the 530 "atom:category" element from the Atom Syndication Format [RFC4287]. 531 Categories can also appear in Service Documents, where they describe 532 the categories allowed in a Collection (see Section 8.2.5). 534 Category Documents are identified with the "application/atomcat+xml" 535 media type (see Section 16). 537 7.1. Example 539 540 544 545 546 547 549 This Category Document contains three categories, with the terms 550 "animal", "vegetable", and "mineral". None of the categories use the 551 'label' attribute defined in [RFC4287]. They all inherit the 552 "http://example.com/cats/big3" 'scheme' attribute declared on the 553 app:categories element. Therefore if the "mineral" category were to 554 appear in an Atom Entry or Feed Document, it would appear as: 556 558 7.2. Element Definitions 560 7.2.1. The "app:categories" element 562 The root of a Category Document is the "app:categories" element. An 563 app:categories element can contain zero or more "atom:category" 564 elements from the Atom namespace ("http://www.w3.org/2005/Atom"). 566 An app:category child element that has no "scheme" attribute inherits 567 the attribute from its app:categories parent. An app:category child 568 element with an existing "scheme" attribute does not inherit the 569 "scheme" value of its "app:categories" parent element. 571 7.2.1.1. Attributes of "app:categories" 573 The app:categories element can contain a "fixed" attribute, with a 574 value of either "yes" or "no", indicating whether the list of 575 categories is a fixed or an open set. Attempts to create or update 576 members whose categories are not listed in the Collection Document 577 MAY be rejected by the server. Collections that indicate the 578 category set is open SHOULD NOT reject otherwise acceptable members 579 whose categories are not listed by the Collection. 581 Alternatively, the app:categories element MAY contain an "href" 582 attribute, whose value MUST be an IRI reference identifying a 583 Category Document. If the "href" attribute is provided, the app: 584 categories element MUST be empty and MUST NOT have the "fixed" or 585 "scheme" attributes. 587 atomCategory = 588 element atom:category { 589 atomCommonAttributes, 590 attribute term { text }, 591 attribute scheme { atomURI }?, 592 attribute label { text }?, 593 undefinedContent 594 } 596 appInlineCategories = 597 element app:categories { 598 attribute fixed { "yes" | "no" }?, 599 attribute scheme { atomURI }?, 600 (atomCategory*) 601 } 603 appOutOfLineCategories = 604 element app:categories { 605 attribute href { atomURI }, 606 undefinedContent 607 } 609 appCategories = appInlineCategories | appOutOfLineCategories 611 8. Service Documents 613 For authoring to commence, a client needs to discover the 614 capabilities and locations of the available Collections. Service 615 Documents are designed to support this discovery process. How 616 Service Documents are discovered is not defined in this 617 specification. 619 A Service Document describes Workspaces, which are server-defined 620 groups of Collections. Service Documents are identified with the 621 "application/atomserv+xml" media type (see Section 16). 623 There is no requirement that a server support multiple Workspaces. 624 In addition, a Collection MAY appear in more than one Workspace. 626 8.1. Example 628 629 631 632 Main Site 633 635 My Blog Entries 636 638 639 641 Pictures 642 image/* 643 644 645 646 Side Bar Blog 647 649 Remaindered Links 650 entry 651 652 655 658 659 660 661 663 This Service Document describes two Workspaces. The first Workspace 664 is called "Main Site", has two Collections called "My Blog Entries" 665 and "Pictures" whose IRIs are "http://example.org/reilly/main" and 666 "http://example.org/reilly/pic" respectively. The "Pictures" 667 Workspace includes an "accept" element indicating that a client can 668 post image files to the Collection to create new Media Resources. 669 Entries with associated Media Resources are discussed in Section 9.5. 671 The second Workspace is called "Side Bar Blog" and has a single 672 Collection called "Remaindered Links" whose IRI is 673 "http://example.org/reilly/list". 675 Within each of the two Entry collections, the categories element 676 provides a list of available categories for Member Entries. In the 677 "My Blog Entries" Collection, the list of available categories is 678 obtainable through the "href" attribute. The "Side Bar Blog" 679 Collection provides a category list within the Service Document, but 680 states the list is fixed, signaling a request from the server that 681 Entries be POSTed using only those two categories. 683 8.2. Element Definitions 685 8.2.1. The "app:service" Element 687 The root of a Service Document is the "app:service" element. 689 The "app:service" element is the container for service information 690 associated with one or more Workspaces. An app:service element MUST 691 contain one or more app:workspace elements. 693 namespace app = "http://purl.org/atom/app#" 694 start = appService 696 appService = 697 element app:service { 698 appCommonAttributes, 699 ( appWorkspace+ 700 & extensionElement* ) 701 } 703 8.2.2. The "app:workspace" Element 705 The "app:workspace" element contains information elements about the 706 Collections of resources available for editing. The app:workspace 707 element contains zero or more app:collection elements. 709 appWorkspace = 710 element app:workspace { 711 appCommonAttributes, 712 ( atomTitle 713 & appCollection* 714 & extensionSansTitleElement* ) 715 } 717 atomTitle = element atom:title { atomTextConstruct } 719 8.2.2.1. The "atom:title" Element 721 The app:workspace element MUST contain one "atom:title" element (as 722 defined in [RFC4287]), giving a human-readable title for the 723 Workspace. 725 8.2.3. The "app:collection" Element 727 The "app:collection" element describes a Collection. The app: 728 collection element MAY contain one app:accept element and MAY contain 729 any number of app:categories elements. The app:collection element 730 MUST NOT contain more than one app:accept element. 732 appCollection = 733 element app:collection { 734 appCommonAttributes, 735 attribute href { atomURI }, 736 ( atomTitle 737 & appAccept? 738 & appCategories* 739 & extensionSansTitleElement* ) 740 } 742 8.2.3.1. Usage in Atom Feed Documents 744 The app:collection element MAY appear as a child of an atom:feed or 745 atom:source element in an Atom Feed Document. Its value identifies a 746 Collection by which new Entries can be added to appear in the feed. 747 The app:collection element is considered foreign markup as defined in 748 Section 6 of [RFC4287]. 750 8.2.3.2. The "href" Attribute 752 The app:collection element MUST contain an "href" attribute, whose 753 value gives the IRI of the Collection. 755 8.2.3.3. The "atom:title" Element 757 The app:collection Element MUST contain one "atom:title" element (as 758 defined in [RFC4287]), giving a human-readable title for the 759 Collection. 761 8.2.4. The "app:accept" Element 763 The "app:accept" element value specifies a comma-separated list of 764 media-ranges (see [RFC2616]) identifying the types of representations 765 that can be POSTed to the URI of a Collection. Whitespace around and 766 between media-range values is considered insignificant and MUST be 767 ignored. 769 The app:accept element is similar to the HTTP Accept request-header 770 [RFC2616] with the exception that app:accept has no notion of 771 preference. As a result, the value syntax of app:accept does not use 772 "accept-params" or "q" arguments as specified in [RFC2616], section 773 14.1. 775 The order of media-ranges is not significant. The following lists 776 are all equivalent: 778 image/png,image/* 779 image/*, image/png 780 image/* 782 A value of "entry" may appear in any list of media-ranges in an 783 accept element and indicates that Atom Entry Documents can be POSTed 784 to the Collection. If the accept element exists but is empty, 785 clients SHOULD assume that the Collection does not support the 786 creation of new Entries. If the accept element is not present, 787 clients SHOULD treat this as equivalent to entry. 790 appAccept = 791 element app:accept { 792 appCommonAttributes, 793 ( appTypeValue? ) 794 } 796 appTypeValue = ( "entry" | media-type |entry-or-media-type ) 797 media-type = xsd:string { pattern = "entry,(.+/.+,?)*" } 798 entry-or-media-type = xsd:string { pattern = "(.+/.+,?)*" } 800 8.2.5. The "app:categories" Element 802 The "app:categories" element provides a listing of the categories 803 that can be applied to the members of a Collection. The absence of 804 an "app:categories" element means that the category handling of a 805 server is unspecified. 807 atomCategory = 808 element atom:category { 809 atomCommonAttributes, 810 attribute term { text }, 811 attribute scheme { atomURI }?, 812 attribute label { text }?, 813 undefinedContent 814 } 816 appInlineCategories = 817 element app:categories { 818 attribute fixed { "yes" | "no" }?, 819 attribute scheme { atomURI }?, 820 (atomCategory*) 821 } 823 appOutOfLineCategories = 824 element app:categories { 825 attribute href { atomURI }, 826 undefinedContent 827 } 829 appCategories = appInlineCategories | appOutOfLineCategories 831 The app:categories element MAY contain a "fixed" attribute, with a 832 value of either "yes" or "no", indicating whether or not the listing 833 of categories is considered to be a fixed, or closed set. The 834 absence of the "fixed" attribute is equivalent to the presence of a 835 "fixed" attribute with a value of "no". Collections that indicate a 836 fixed set MAY reject members that include categories not specified in 837 the provided listing. Collections that indicate an open set SHOULD 838 NOT reject otherwise acceptable members whose categories are not 839 present in the provided list. 841 The app:categories element MAY contain an "href" attribute, whose 842 value MUST be an IRI reference identifying a Category Document. If 843 the "href" attribute is provided, the app:categories element MUST be 844 empty and the "fixed" and "scheme" attributes MUST NOT be present. 846 9. Creating and Editing Resources 848 9.1. Member URIs 850 The Member URI supports retrieving, updating and deleting the 851 resource using HTTP GET, PUT and DELETE. Retrieval and updating of 852 Member Entry Resources are done by exchanging Atom Entry 853 representations. 855 Member Entry URIs appear in two places. First, they are returned in 856 a Location header after successful resource creation using POST, as 857 described below. Second, they appear in the Entries of a Collection 858 document as atom:link elements with a link relation of "edit". 860 Each Member Entry SHOULD contain such an atom:link element providing 861 its Member Entry URI. 863 9.2. Creating resources with POST 865 To add members to a Collection, clients send POST requests to the URI 866 of a Collection. Successful member creation is normally indicated 867 with a 201 ("Created") response code. Collections MAY generate a 868 response with a status code of 415 ("Unsupported Media Type") to 869 indicate that the media-type of the POSTed entity is not allowed or 870 supported by the Collection. 872 When a Member Resource is created in the Collection which received 873 the POST, its Member Entry URI MUST be returned in an HTTP Location 874 header. 876 When the server generates a response with a status code of 201 877 ("Created"), it SHOULD also return a response body, which if 878 provided, MUST be an Atom Entry Document representing the newly- 879 created resource. 881 Since the server is free to alter the POSTed Entry, for example by 882 changing the content of the "id" element, returning the Entry as 883 described in the previous paragraph can be useful to the client, 884 enabling it to correlate the client and server views of the new 885 Entry. 887 If the POST request contained an Atom Entry Document, and the 888 subsequent response from the server contains a Content-Location 889 header that matches the Location header character-for-character, then 890 the client is authorized to interpret the response entity as being 891 the representation of the newly created Entry. Without a matching 892 Content-Location header the client MUST NOT assume the returned 893 entity is a complete representation of the created resource. 895 The request body sent with the POST need not be an Atom Entry. For 896 example, it might be a picture, or a movie. For a discussion of the 897 issues in POSTing such content, see Section 9.5. 899 9.2.1. Example 901 Below, the client sends a POST request containing an Atom Entry 902 representation to the URI of the Collection: 904 POST /myblog/entries HTTP/1.1 905 Host: example.org 906 User-Agent: Thingio/1.0 907 Authorization: Basic ZGFmZnk6c2VjZXJldA== 908 Content-Type: application/atom+xml 909 Content-Length: nnn 910 Slug: First Post 912 913 914 Atom-Powered Robots Run Amok 915 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 916 2003-12-13T18:30:02Z 917 John Doe 918 Some text. 919 921 The server signals a successful creation with a status code of 201. 922 The response includes a Location: header indicating the Member Entry 923 URI of the Atom Entry and a representation of that Entry in the body 924 of the response. 926 HTTP/1.1 201 Created 927 Date: Fri, 7 Oct 2005 17:17:11 GMT 928 Content-Length: nnn 929 Content-Type: application/atom+xml; charset="utf-8" 930 Location: http://example.org/edit/first-post.atom 932 933 934 Atom-Powered Robots Run Amok 935 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 936 2003-12-13T18:30:02Z 937 John Doe 938 Some text. 939 941 943 The created Entry returned by the server might not match the Entry 944 POSTed by the client. A server MAY change the values of various 945 elements in the Entry such as the atom:id, atom:updated and atom: 946 author values and MAY choose to remove or add other elements and 947 attributes, or change element and attribute values. 949 9.3. Updating Resources with PUT 951 To update a resource, clients send PUT requests to its Member URI, as 952 specified in [RFC2616]. 954 To avoid unintentional loss of data when editing Member Entries or 955 Media Link Entries, Atom Protocol clients SHOULD preserve all 956 metadata that has not been intentionally modified, including unknown 957 foreign markup as defined in Section 6 of [RFC4287]. 959 9.4. Deleting Resources with DELETE 961 To delete a resource, clients send DELETE requests to its Member URI, 962 as specified in [RFC2616]. For Media Resources, deletion of a Media 963 Link Entry SHOULD result in the deletion of the associated Media 964 Resource. 966 9.5. Media Resources and Media Link Entries 968 A client can POST a media type other than application/atom+xml to a 969 Collection. Such a request always creates two new resources - one 970 that corresponds to the entity sent in the request, called the Media 971 Resource, and an associated Member Entry, called the Media Link 972 Entry. Media Link Entries are represented as Atom Entries. The 973 server can signal the media types it will accept via the "accept" 974 element in the Service Document (Section 8.2.4). 976 The Media Link Entry contains the IRI of, and metadata about, the 977 (perhaps non-textual) Media Resource. The Media Link Entry makes the 978 metadata about the Media Resource separately available for retrieval 979 and update. 981 Successful responses to creation requests MUST include the URI of the 982 Media Link Entry in the Location header. The Media Link Entry SHOULD 983 contain an atom:link element with a link relation of "edit-media" 984 that contains the Media Resource IRI. The Media Link Entry MUST have 985 an "atom:content" element with a "src" attribute. The value of the 986 "src" attribute is an IRI of the newly created Media Resource. It is 987 OPTIONAL that the IRI of the "src" attribute on the atom:content 988 element be the same as the Media Resource IRI. For example, the 989 "src" attribute value might instead be a link into a static cache or 990 content distribution network and not the Media Resource IRI. 992 Implementers are asked to note that according to the requirements of 993 [RFC4287], Entries, and thus Media Link Entries, MUST contain an 994 atom:summary element. Upon successful creation of a Media Link 995 Entry, a server MAY choose to populate the atom:summary element (as 996 well as any other required elements such as atom:id, atom:author and 997 atom:title) with content derived from the POSTed entity or from any 998 other source. A server might not allow a client to modify the server 999 selected values for these elements. 1001 For resource creation this specification only defines cases where the 1002 POST body has an Atom Entry entity declared as an Atom media type 1003 ("application/atom+xml"), or a non-Atom entity declared as a non-Atom 1004 media type. It does not specify any request semantics or server 1005 behavior in the case where the POSTed media-type is "application/ 1006 atom+xml" but the body is something other than an Atom Entry. In 1007 particular, what happens on POSTing an Atom Feed Document to a 1008 Collection using the "application/atom+xml" media type is undefined. 1010 The Atom Protocol does not specify a means to create multiple 1011 representations of the same resource (for example a PNG and a JPG of 1012 the same image) on creation or update. 1014 9.5.1. Examples 1016 Below, the client sends a POST request containing a PNG image to the 1017 URI of a Collection that accepts PNG images: 1019 POST /media/ HTTP/1.1 1020 Host: example.org 1021 Content-Type: image/png 1022 Slug: The Beach 1023 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1024 Content-Length: nnn 1026 ...binary data... 1028 The server signals a successful creation with a status code of 201. 1029 The response includes a Location header indicating the Member URI of 1030 the Media Link Entry and a representation of that entry in the body 1031 of the response. The Media Link Entry includes a content element 1032 with a src attribute. It also contains a link using the link 1033 relation "edit-media" specifying the IRI to be used for modifying the 1034 Media Resource. 1036 HTTP/1.1 201 Created 1037 Date: Fri, 7 Oct 2005 17:17:11 GMT 1038 Content-Length: nnn 1039 Content-Type: application/atom+xml; charset="utf-8" 1040 Location: http://example.org/media/edit/the_beach.atom 1042 1043 1044 The Beach 1045 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 1046 2005-10-07T17:17:08Z 1047 Daffy 1048 1049 1051 1053 1055 1057 Later, the client PUTS a new PNG to the URI indicated in the Media 1058 Link Entry's "edit-media" link: 1060 PUT /edit/the_beach.png HTTP/1.1 1061 Host: media.example.org 1062 Content-Type: image/png 1063 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1064 Content-Length: nnn 1066 ...binary data... 1068 The server signals a successful update with a status code of 200. 1070 HTTP/1.1 200 Ok 1071 Date: Fri, 8 Oct 2006 17:17:11 GMT 1072 Content-Length: nnn 1074 The client can update the metadata for the picture. First GET the 1075 Media Link Entry: 1077 GET /media/edit/the_beach.atom HTTP/1.1 1078 Host: example.org 1079 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1081 The Media Link Entry is returned. 1083 HTTP/1.1 200 Ok 1084 Date: Fri, 7 Oct 2005 17:18:11 GMT 1085 Content-Length: nnn 1086 Content-Type: application/atom+xml; charset="utf-8" 1088 1089 1090 The Beach 1091 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 1092 2005-10-07T17:17:08Z 1093 Daffy 1094 1095 1097 1099 1101 1103 The metadata can be updated, in this case to add a summary, and then 1104 PUT back to the server. 1106 PUT /media/edit/the_beach.atom HTTP/1.1 1107 Host: example.org 1108 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1109 Content-Type: application/atom+xml 1110 Content-Length: nnn 1112 1113 1114 The Beach 1115 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 1116 2005-10-07T17:17:08Z 1117 Daffy 1118 1119 A nice sunset picture over the water. 1120 1121 1123 1125 1127 1129 The update was successful. 1131 HTTP/1.1 200 Ok 1132 Date: Fri, 7 Oct 2005 17:19:11 GMT 1133 Content-Length: 0 1135 Multiple media resources can be added to the Collection. 1137 POST /media/ HTTP/1.1 1138 Host: example.org 1139 Content-Type: image/png 1140 Slug: The Pier 1141 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1142 Content-Length: nnn 1144 ...binary data... 1146 The resource is created successfully. 1148 HTTP/1.1 201 Created 1149 Date: Fri, 7 Oct 2005 17:17:11 GMT 1150 Content-Length: nnn 1151 Content-Type: application/atom+xml; charset="utf-8" 1152 Location: http://example.org/media/edit/the_pier.atom 1154 1155 1156 The Pier 1157 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efe6b 1158 2005-10-07T17:26:43Z 1159 Daffy 1160 1161 1163 1165 1167 1169 The client can now create a new Atom Entry in the blog Entry 1170 Collection that references the two newly created Media Resources. 1172 POST /blog/ HTTP/1.1 1173 Host: example.org 1174 Content-Type: application/atom+xml 1175 Slug: A day at the beach 1176 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1177 Content-Length: nnn 1179 1180 1181 A fun day at the beach 1182 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6b 1183 2005-10-07T17:40:02Z 1184 Daffy 1185 1186 1187 We had a good day at the beach. 1188 1190 1191 Later we walked down to the pier. 1192 1194 1195 1196 1197 1199 The resource is created successfully. 1201 HTTP/1.1 200 Ok 1202 Date: Fri, 7 Oct 2005 17:20:11 GMT 1203 Content-Length: nnn 1204 Content-Type: application/atom+xml; charset="utf-8" 1205 Location: http://example.org/blog/atom/a-day-at-the-beach.atom 1207 1208 1209 A fun day at the beach 1210 http://example.org/blog/a-day-at-the-beach.xhtml 1211 2005-10-07T17:43:07Z 1212 Daffy 1213 1214 1215 We had a good day at the beach. 1216 1218 1219 Later we walked down to the pier. 1220 1222 1223 1224 1225 1227 1229 1231 Note that the returned Entry contains a link with a relation of 1232 "alternate" that points to the associated XHTML page that was 1233 created. This is not required by this specification, but is included 1234 to show the kinds of changes a server may make to an Entry. 1236 9.6. The Slug: Header 1238 Slug is a HTTP entity-header whose value is a short name that, when 1239 accompanying a POST to a Collection, constitutes a request by the 1240 client that its value be used as part of the URI for the to-be- 1241 created Member Resource. 1243 When POSTing an entity to a Collection to add a new Member, the 1244 server MAY use this information when creating the Member URI of the 1245 newly-created resource, for instance by using some or all of the 1246 words in the last URI segment. It MAY also use it when creating the 1247 atom:id or as the title of a Media Link Entry (see Section 9.5.). 1249 Servers MAY ignore the Slug entity-header and MAY alter its value 1250 before using it. For example, the server MAY filter out some 1251 characters or replace accented letters with non-accented ones, spaces 1252 with underscores, etc. 1254 9.6.1. Slug: Header syntax 1256 The syntax of this header MUST conform to the augmented BNF grammar 1257 in section 2.1 of the HTTP/1.1 specification [RFC2616]. The TEXT 1258 rule is described in section 2.2 of the same document. 1260 Slug = "Slug" ":" *TEXT 1262 Clients MAY send non-ASCII characters in the Slug entity-header, 1263 which they MUST encode using "encoded-words", as defined in 1264 [RFC2047]. Servers SHOULD treat the slug as [RFC2047] encoded if it 1265 matches the "encoded-words" production. 1267 9.6.2. Example 1269 Here is an example of the Slug: header that uses the encoding rules 1270 of [RFC2047]. 1272 POST /myblog/entries HTTP/1.1 1273 Host: example.org 1274 Content-Type: image/png 1275 Slug: =?iso-8859-1?q?The_Beach?= 1276 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1277 Content-Length: nnn 1279 ...binary data... 1281 See Section 9.2.1 for an example of the Slug: header applied to the 1282 creation of a Member Entry Resource. 1284 10. Listing Collections 1286 Collection Resources MUST provide representations in the form of Atom 1287 Feed documents whose Entries contain the IRIs of the Members in the 1288 Collection. No structural distinction is made between Collection 1289 Feeds and other kinds of Feeds - a Feed might act both as a 'public' 1290 feed for subscription purposes and as a Collection Feed. 1292 Each Entry in the Feed Document SHOULD have an atom:link element with 1293 a relation of "edit" (See Section 11.1). 1295 The Entries in the returned Atom Feed SHOULD be ordered by their 1296 "atom:updated" property, with the most recently updated Entries 1297 coming first in the document order. Clients SHOULD be constructed in 1298 consideration of the fact that changes which do not alter the atom: 1299 updated value of an Entry will not affect the position of the Entry 1300 in a Collection. That is, the Atom Syndication Format states that 1301 the value of atom:updated is altered when the changes to an Entry are 1302 something that "the publisher considers significant." The atom: 1303 updated value is not equivalent to the HTTP Last-Modified: header and 1304 can not be used to determine the freshness of cached responses. 1306 Clients MUST NOT assume that an Atom Entry returned in the Feed is a 1307 full representation of a Member Entry Resource and SHOULD perform a 1308 GET on the URI of the Member Entry before editing. 1310 10.1. Collection Paging 1312 Collections can contain large numbers of resources. A naive client 1313 such as a web spider or web browser could be overwhelmed if the 1314 response to a GET contained every Entry in the Collection, and the 1315 server would waste large amounts of bandwidth and processing time on 1316 clients unable to handle the response. For this reason, servers MAY 1317 return a partial listing of the most recently updated Member 1318 Resources. Such partial feed documents MUST have an atom:link with a 1319 "next" relation whose "href" value is the URI of the next partial 1320 listing of the Collection (the next most recently updated Member 1321 Resources) where it exists. This is called "Collection paging". 1323 The returned Atom Feed MAY contain a subset the Member Entries for a 1324 Collection. In addition, the Atom Feed document MAY contain link 1325 elements with "rel" attribute values of "next", "previous", "first" 1326 and "last" that can be used to navigate through the complete set of 1327 matching Entries. 1329 For instance, suppose a client is supplied the URI 1330 "http://example.org/entries/go" of a Collection of Member entries, 1331 where the server as a matter of policy avoids generating feed 1332 documents containing more than 10 Entries. The Atom Feed document 1333 for the Collection will then represent the first 'page' in a set of 1334 10 linked feed documents. The "first" relation will reference the 1335 initial feed document in the set and the "last" relation references 1336 the final Atom Feed Document in the set. Within each document, the 1337 "next" and "previous" link relations reference the preceding and 1338 subsequent documents. 1340 1341 1343 1345 1347 ... 1348 1350 The "next" and "previous" link elements for the feed 'page' located 1351 at "http://example.org/entries/2" would look like this: 1353 1354 1356 1358 1360 1362 ... 1363 1365 10.2. The "app:edited" Element 1367 The "app:edited" element is a Date construct as defined by [RFC4287] 1368 whose value indicates the most recent instant in time when an Entry 1369 was edited, including when created. Atom Entry elements in 1370 Collection documents SHOULD contain one "app:edited" element, and 1371 MUST NOT contain more than one. 1373 appEdited = element app:edited ( atomDateConstruct ) 1375 The server SHOULD change the value of this element every time a 1376 Collection Member Resource or an associated Media Resource has been 1377 edited. 1379 11. Atom Format Link Relation Extensions 1381 11.1. The "edit" Link Relation 1383 This specification adds the value "edit" to the Atom Registry of Link 1384 Relations (see section 7.1 of [RFC4287]). The value of "edit" 1385 specifies that the value of the href attribute is the IRI of an 1386 editable Member Entry. When appearing within an atom:entry, the href 1387 IRI can be used to retrieve, update and delete the resource 1388 represented by that Entry. An atom:entry MUST contain no more than 1389 one "edit" link relation. 1391 11.2. The "edit-media" Link Relation 1393 This specification adds the value "edit-media" to the Atom Registry 1394 of Link Relations (see section 7.1 of [RFC4287]). When appearing 1395 within an atom:entry, the value of the href attribute is an IRI that 1396 can be used to modify a Media Resource associated with that Entry. 1398 An atom:entry element MAY contain zero or more "edit-media" link 1399 relations. An atom:entry MUST NOT contain more than one atom:link 1400 element with a rel attribute value of "edit-media" that has the same 1401 "type" and "hreflang" attribute values. All "edit-media" link 1402 relations in the same Entry reference the same resource. If a client 1403 encounters multiple "edit-media" link relations in an Entry then it 1404 SHOULD choose a link based on the client preferences for "type" and 1405 "hreflang". If a client encounters multiple "edit-media" link 1406 relations in an Entry and has no preference based on the "type" and 1407 "hreflang" attributes then the client SHOULD pick the first "edit- 1408 media" link relation in document order. 1410 12. The Atom Format Type Parameter 1412 The Atom Syndication Format (RFC 4287) defines the 'application/ 1413 atom+xml' media type to identify both Atom Feed and Atom Entry 1414 Documents. Implementation experience has demonstrated that Atom Feed 1415 and Entry Documents can have different processing models and that 1416 there are situations where they need to be differentiated. This 1417 document defines an optional 'type' parameter used to differentiate 1418 the two types of Atom documents. 1420 12.1. The 'type' parameter 1422 This document defines a new "type" parameter for use with the 1423 'application/atom+xml' media type. 1424 type = "entry" / "feed" 1426 Neither the parameter name nor its value are case sensitive. 1428 The value 'entry' indicates that the media type identifies an Atom 1429 Entry Document. The root element of the document MUST be atom:entry. 1431 The value 'feed' indicates that the media type identifies an Atom 1432 Feed Document. The root element of the document MUST be atom:feed. 1434 If not specified, the type is assumed to be unspecified, requiring 1435 Atom processors to examine the root element to determine the type of 1436 Atom document. 1438 12.1.1. Conformance 1440 New specifications MAY require that the type parameter be used to 1441 identify the Atom Document type. Producers of Atom Entry Documents 1442 SHOULD use the type parameter regardless of whether or not it is 1443 required. Producers of Atom Feed Documents MAY use the parameter. 1445 Atom processors that do not recognize the 'type' parameter MUST 1446 ignore its value and examine the root element to determine the 1447 document type. 1449 Atom processors that do recognize the parameter SHOULD detect and 1450 report inconsistencies between the parameter's value and the actual 1451 type of the document's root element. 1453 13. Atom Publishing Controls 1455 This specification defines an Atom Format Structured Extension, as 1456 defined in Section 6 of [RFC4287], for publishing control within the 1457 "http://purl.org/atom/app#" namespace. 1459 13.1. The "app:control" Element 1461 namespace app = "http://purl.org/atom/app#" 1463 pubControl = 1464 element app:control { 1465 atomCommonAttributes, 1466 pubDraft? 1467 & extensionElement 1468 } 1470 pubDraft = 1471 element app:draft { "yes" | "no" } 1473 The "app:control" element MAY appear as a child of an atom:entry 1474 which is being created or updated via the Atom Publishing Protocol. 1475 The app:control element MUST appear only once in an Entry. The app: 1476 control element is considered foreign markup as defined in Section 6 1477 of [RFC4287]. 1479 The app:control element and its child elements MAY be included in 1480 Atom Feed or Entry Documents. 1482 The app:control element can contain an optional "app:draft" element 1483 as defined below, and can contain extension elements as defined in 1484 Section 6 of [RFC4287]. 1486 13.1.1. The "app:draft" Element 1488 The number of app:draft elements in app:control MUST be zero or one. 1489 Its value MUST be one of "yes" or "no". A value of "no" indicates a 1490 client request that the Member Resource be made publicly visible. If 1491 the app:draft element is missing then the value MUST be understood to 1492 be "no". The inclusion of the app:draft element represents a request 1493 by the client to control the visibility of a Member Resource and the 1494 app:draft element MAY be ignored by the server. 1496 14. Securing the Atom Publishing Protocol 1498 The Atom Publishing Protocol is based on HTTP. Authentication 1499 requirements for HTTP are covered in Section 11 of [RFC2616]. 1501 The use of authentication mechanisms to prevent POSTing or editing by 1502 unknown or unauthorized clients is RECOMMENDED but not required. 1503 When authentication is not used, clients and servers are vulnerable 1504 to trivial spoofing, denial of service and defacement attacks, 1505 however, in some contexts, this is an acceptable risk. 1507 The type of authentication deployed is a local decision made by the 1508 server operator. Clients are likely to face authentication schemes 1509 that vary across server deployments. At a minimum, client and server 1510 implementations MUST be capable of being configured to use HTTP Basic 1511 Authentication [RFC2617] in conjunction with a TLS connection as 1512 specified by [RFC2818]. See [RFC4346] for more information on TLS. 1514 The choice of authentication mechanism will impact interoperability. 1515 The minimum level of security referenced above (Basic Authentication 1516 with TLS) is considered good practice for Internet applications at 1517 the time of publication of this specification and sufficient for 1518 establishing a baseline for interoperability. Implementers can 1519 investigate and use alternative mechanisms regarded as equivalently 1520 good or better at the time of deployment. It is RECOMMENDED that 1521 clients be implemented in such a way that allows new authentication 1522 schemes to be deployed. 1524 Because this protocol uses HTTP response status codes as the primary 1525 means of reporting the result of a request, servers are advised to 1526 respond to unauthorized or unauthenticated requests using an 1527 appropriate 4xx HTTP response code (e.g. 401 "Unauthorized" or 403 1528 "Forbidden") in accordance with [RFC2617]. 1530 15. Security Considerations 1532 As an HTTP-based protocol, APP is subject to the security 1533 considerations found in Section 15 of [RFC2616]. 1535 15.1. Denial of Service 1537 Atom Publishing server implementations need to take adequate 1538 precautions to ensure malicious clients cannot consume excessive 1539 server resources (CPU, memory, disk, etc). 1541 15.2. Replay Attacks 1543 Atom Publishing server implementations are susceptible to replay 1544 attacks. Specifically, this specification does not define a means of 1545 detecting duplicate requests. Accidentally sent duplicate requests 1546 are indistinguishable from intentional and malicious replay attacks. 1548 15.3. Spoofing Attacks 1550 Atom Publishing implementations are susceptible to a variety of 1551 spoofing attacks. Malicious clients may send Atom Entries containing 1552 inaccurate information anywhere in the document. 1554 15.4. Linked Resources 1556 Atom Feed and Entry documents can contain XML External Entities as 1557 defined in Section 4.2.2 of [W3C.REC-xml]. Atom implementations are 1558 not required to load external entities. External entities are 1559 subject to the same security concerns as any network operation and 1560 can alter the semantics of an Atom document. The same issues exist 1561 for resources linked to by Atom elements such as atom:link and atom: 1562 content. 1564 15.5. Digital Signatures and Encryption 1566 Atom Entry Documents sent to a server might contain XML Digital 1567 Signatures [W3C.REC-xmldsig-core] and might be encrypted using XML 1568 Encryption [W3C.REC-xmlenc-core] as specified in Section 5 of 1569 [RFC4287]. 1571 Servers are allowed to modify received resource representations in 1572 ways that can invalidate signatures covering those representations. 1574 15.6. URIs and IRIs 1576 Atom Publishing Protocol implementations handle URIs and IRIs. See 1577 Section 7 of [RFC3986] and Section 8 of [RFC3987]. 1579 16. IANA Considerations 1581 16.1. Content-type registration for 'application/atomserv+xml' 1583 An Atom Publishing Protocol Service Document, when serialized as XML 1584 1.0, can be identified with the following media type: 1586 MIME media type name: application 1588 MIME subtype name: atomserv+xml 1590 Mandatory parameters: None. 1592 Optional parameters: 1594 "charset": This parameter has identical semantics to the charset 1595 parameter of the "application/xml" media type as specified in 1596 [RFC3023]. 1598 Encoding considerations: Identical to those of "application/xml" as 1599 described in [RFC3023], section 3.2. 1601 Security considerations: As defined in this specification. 1602 [[anchor32: update upon publication]] 1604 In addition, as this media type uses the "+xml" convention, it 1605 shares the same security considerations as described in [RFC3023], 1606 section 10. 1608 Interoperability considerations: There are no known interoperability 1609 issues. 1611 Published specification: This specification. [[anchor33: update upon 1612 publication]] 1614 Applications that use this media type: No known applications 1615 currently use this media type. 1617 Additional information: 1619 Magic number(s): As specified for "application/xml" in [RFC3023], 1620 section 3.2. 1622 File extension: .atomsrv 1623 Fragment identifiers: As specified for "application/xml" in 1624 [RFC3023], section 5. 1626 Base URI: As specified in [RFC3023], section 6. 1628 Macintosh File Type code: TEXT 1630 Person and email address to contact for further information: Joe 1631 Gregorio 1633 Intended usage: COMMON 1635 Author/Change controller: This specification's author(s). 1636 [[anchor34: update upon publication]] 1638 16.2. Content-type registration for 'application/atomcat+xml' 1640 An Atom Publishing Protocol Category Document, when serialized as XML 1641 1.0, can be identified with the following media type: 1643 MIME media type name: application 1645 MIME subtype name: atomcat+xml 1647 Mandatory parameters: None. 1649 Optional parameters: 1651 "charset": This parameter has identical semantics to the charset 1652 parameter of the "application/xml" media type as specified in 1653 [RFC3023]. 1655 Encoding considerations: Identical to those of "application/xml" as 1656 described in [RFC3023], section 3.2. 1658 Security considerations: As defined in this specification. 1659 [[anchor35: update upon publication]] 1661 In addition, as this media type uses the "+xml" convention, it 1662 shares the same security considerations as described in [RFC3023], 1663 section 10. 1665 Interoperability considerations: There are no known interoperability 1666 issues. 1668 Published specification: This specification. [[anchor36: update upon 1669 publication]] 1671 Applications that use this media type: No known applications 1672 currently use this media type. 1674 Additional information: 1676 Magic number(s): As specified for "application/xml" in [RFC3023], 1677 section 3.2. 1679 File extension: .atomcat 1681 Fragment identifiers: As specified for "application/xml" in 1682 [RFC3023], section 5. 1684 Base URI: As specified in [RFC3023], section 6. 1686 Macintosh File Type code: TEXT 1688 Person and email address to contact for further information: Joe 1689 Gregorio 1691 Intended usage: COMMON 1693 Author/Change controller: This specification's author(s). 1694 [[anchor37: update upon publication]] 1696 16.3. Header field registration for 'SLUG' 1698 Header field: SLUG 1700 Applicable protocol: http [RFC2616] 1702 Status: standard. 1704 Author/Change controller: IETF (iesg@ietf.org) Internet Engineering 1705 Task Force 1707 Specification document(s): draft-ietf-atompub-protocol-13.txt 1708 ([[anchor38: update on rfc number assignment]]) 1710 Related information: 1712 16.4. The Link Relation registration "edit" 1714 Attribute Value: edit 1716 Description: An IRI of an editable Member Entry. When appearing 1717 within an atom:entry, the href IRI can be used to retrieve, update 1718 and delete the resource represented by that Entry. 1720 Expected display characteristics: Undefined; this relation can be 1721 used for background processing or to provide extended 1722 functionality without displaying its value. 1724 Security considerations: Automated agents should take care when this 1725 relation crosses administrative domains (e.g., the URI has a 1726 different authority than the current document). 1728 16.5. The Link Relation registration "edit-media" 1730 Attribute Value: edit-media 1732 Description: An IRI of an editable Media Resource. When appearing 1733 within an atom:entry, the href IRI can be used to retrieve, update 1734 and delete the Media Resource associated with that Entry. 1736 Expected display characteristics: Undefined; this relation can be 1737 used for background processing or to provide extended 1738 functionality without displaying its value. 1740 Security considerations: Automated agents should take care when this 1741 relation crosses administrative domains (e.g., the URI has a 1742 different authority than the current document). 1744 16.6. The Atom Format Media Type Parameter 1746 IANA is requested to add a reference to this specification in the 1747 'application/atom+xml' media type registration. 1749 17. References 1751 17.1. Normative References 1753 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 1754 Part Three: Message Header Extensions for Non-ASCII Text", 1755 RFC 2047, November 1996. 1757 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1758 Requirement Levels", BCP 14, RFC 2119, March 1997. 1760 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1761 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1762 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1764 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1765 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1766 Authentication: Basic and Digest Access Authentication", 1767 RFC 2617, June 1999. 1769 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1771 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 1772 Types", RFC 3023, January 2001. 1774 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1775 Resource Identifier (URI): Generic Syntax", STD 66, 1776 RFC 3986, January 2005. 1778 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1779 Identifiers (IRIs)", RFC 3987, January 2005. 1781 [RFC4287] Nottingham, M. and R. Sayre, "The Atom Syndication 1782 Format", RFC 4287, December 2005. 1784 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 1785 (TLS) Protocol Version 1.1", RFC 4346, April 2006. 1787 [W3C.REC-xml] 1788 Yergeau, F., Paoli, J., Bray, T., Sperberg-McQueen, C., 1789 and E. Maler, "Extensible Markup Language (XML) 1.0 1790 (Fourth Edition)", World Wide Web Consortium 1791 Recommendation REC-xml-20060816, August 2006, 1792 . 1794 [W3C.REC-xml-infoset] 1795 Cowan, J. and R. Tobin, "XML Information Set (Second 1796 Edition)", World Wide Web Consortium Recommendation REC- 1797 xml-infoset-20040204, February 2004, 1798 . 1800 [W3C.REC-xml-names] 1801 Hollander, D., Bray, T., Tobin, R., and A. Layman, 1802 "Namespaces in XML 1.0 (Second Edition)", World Wide Web 1803 Consortium Recommendation REC-xml-names-20060816, 1804 August 2006, 1805 . 1807 [W3C.REC-xmlbase-20010627] 1808 Marsh, J., "XML Base", W3C REC W3C.REC-xmlbase-20010627, 1809 June 2001. 1811 [W3C.REC-xmldsig-core] 1812 Solo, D., Reagle, J., and D. Eastlake, "XML-Signature 1813 Syntax and Processing", World Wide Web Consortium 1814 Recommendation REC-xmldsig-core-20020212, February 2002, 1815 . 1817 [W3C.REC-xmlenc-core] 1818 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 1819 Processing", World Wide Web Consortium Recommendation REC- 1820 xmlenc-core-20021210, December 2002, 1821 . 1823 17.2. Informative References 1825 [RNC] Clark, J., "RELAX NG Compact Syntax", December 2001, . 1829 [W3C.REC-webarch-20041215] 1830 Walsh, N. and I. Jacobs, "Architecture of the World Wide 1831 Web, Volume One", W3C REC REC-webarch-20041215, 1832 December 2004. 1834 URIs 1836 [1] 1838 Appendix A. Contributors 1840 The content and concepts within are a product of the Atom community 1841 and the Atompub Working Group. 1843 [[anchor42: chairs to compile a contribution list for 1.0 --dehora]] 1845 Appendix B. RELAX NG Compact Schema 1847 This appendix is informative. 1849 The Relax NG schema explicitly excludes elements in the Atom Protocol 1850 namespace which are not defined in this revision of the 1851 specification. Requirements for Atom Protocol processors 1852 encountering such markup are given in Section 6.2 and Section 6.3 of 1853 [RFC4287]. 1855 The Schema for Service Documents: 1857 # -*- rnc -*- 1858 # RELAX NG Compact Syntax Grammar for the Atom Protocol 1860 namespace app = "http://purl.org/atom/app#" 1861 namespace atom = "http://www.w3.org/2005/Atom" 1862 namespace xsd = "http://www.w3.org/2001/XMLSchema" 1863 namespace xhtml = "http://www.w3.org/1999/xhtml" 1864 namespace local = "" 1866 start = appService 1868 # common:attrs 1870 atomURI = text 1872 appCommonAttributes = 1873 attribute xml:base { atomURI }?, 1874 attribute xml:lang { atomLanguageTag }?, 1875 undefinedAttribute* 1877 atomCommonAttributes = appCommonAttributes 1879 undefinedAttribute = 1880 attribute * - (xml:base | xml:lang | local:*) { text } 1882 atomLanguageTag = xsd:string { 1883 pattern = "[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*" 1884 } 1886 atomDateConstruct = 1887 appCommonAttributes, 1888 xsd:dateTime 1890 # app:service 1892 appService = 1893 element app:service { 1894 appCommonAttributes, 1895 ( appWorkspace+ 1896 & extensionElement* ) 1897 } 1899 # app:workspace 1901 appWorkspace = 1902 element app:workspace { 1903 appCommonAttributes, 1904 ( atomTitle 1905 & appCollection* 1906 & extensionSansTitleElement* ) 1907 } 1909 atomTitle = element atom:title { atomTextConstruct } 1911 # app:collection 1913 appCollection = 1914 element app:collection { 1915 appCommonAttributes, 1916 attribute href { atomURI }, 1917 ( atomTitle 1918 & appAccept? 1919 & appCategories* 1920 & extensionSansTitleElement* ) 1921 } 1923 # app:categories 1925 atomCategory = 1926 element atom:category { 1927 atomCommonAttributes, 1928 attribute term { text }, 1929 attribute scheme { atomURI }?, 1930 attribute label { text }?, 1931 undefinedContent 1932 } 1934 appInlineCategories = 1935 element app:categories { 1936 attribute fixed { "yes" | "no" }?, 1937 attribute scheme { atomURI }?, 1938 (atomCategory*) 1939 } 1941 appOutOfLineCategories = 1942 element app:categories { 1943 attribute href { atomURI }, 1944 undefinedContent 1945 } 1947 appCategories = appInlineCategories | appOutOfLineCategories 1949 # app:accept 1951 appAccept = 1952 element app:accept { 1953 appCommonAttributes, 1954 ( appTypeValue? ) 1955 } 1957 appTypeValue = ( "entry" | media-type |entry-or-media-type ) 1958 media-type = xsd:string { pattern = "entry,(.+/.+,?)*" } 1959 entry-or-media-type = xsd:string { pattern = "(.+/.+,?)*" } 1960 # above is an approximation, rnc doesn't support interleaved text 1962 # Simple Extension 1964 simpleSansTitleExtensionElement = 1965 element * - (app:*|atom:title) { 1966 text 1967 } 1969 simpleExtensionElement = 1970 element * - (app:*) { 1971 text 1972 } 1974 # Structured Extension 1976 structuredSansTitleExtensionElement = 1977 element * - (app:*|atom:title) { 1978 (attribute * { text }+, 1979 (text|anyElement)*) 1980 | (attribute * { text }*, 1981 (text?, anyElement+, (text|anyElement)*)) 1983 } 1985 structuredExtensionElement = 1986 element * - (app:*) { 1987 (attribute * { text }+, 1988 (text|anyElement)*) 1989 | (attribute * { text }*, 1990 (text?, anyElement+, (text|anyElement)*)) 1991 } 1993 # Other Extensibility 1995 extensionSansTitleElement = 1996 simpleSansTitleExtensionElement|structuredSansTitleExtensionElement 1998 extensionElement = 1999 simpleExtensionElement | structuredExtensionElement 2001 undefinedContent = (text|anyForeignElement)* 2003 # Extensions 2005 anyElement = 2006 element * { 2007 (attribute * { text } 2008 | text 2009 | anyElement)* 2010 } 2012 anyForeignElement = 2013 element * - app:* { 2014 (attribute * { text } 2015 | text 2016 | anyElement)* 2017 } 2019 atomPlainTextConstruct = 2020 atomCommonAttributes, 2021 attribute type { "text" | "html" }?, 2022 text 2024 atomXHTMLTextConstruct = 2025 atomCommonAttributes, 2026 attribute type { "xhtml" }, 2027 xhtmlDiv 2029 atomTextConstruct = atomPlainTextConstruct | atomXHTMLTextConstruct 2030 anyXHTML = element xhtml:* { 2031 (attribute * { text } 2032 | text 2033 | anyXHTML)* 2034 } 2036 xhtmlDiv = element xhtml:div { 2037 (attribute * { text } 2038 | text 2039 | anyXHTML)* 2040 } 2042 # EOF 2044 The Schema for Category Documents: 2046 # -*- rnc -*- 2047 # RELAX NG Compact Syntax Grammar for the Atom Protocol 2049 namespace app = "http://purl.org/atom/app#" 2050 namespace atom = "http://www.w3.org/2005/Atom" 2051 namespace xsd = "http://www.w3.org/2001/XMLSchema" 2052 namespace local = "" 2054 start = appCategories 2056 atomCommonAttributes = 2057 attribute xml:base { atomURI }?, 2058 attribute xml:lang { atomLanguageTag }?, 2059 undefinedAttribute* 2061 undefinedAttribute = 2062 attribute * - (xml:base | xml:lang | local:*) { text } 2064 atomURI = text 2066 atomLanguageTag = xsd:string { 2067 pattern = "[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*" 2068 } 2070 atomCategory = 2071 element atom:category { 2072 atomCommonAttributes, 2073 attribute term { text }, 2074 attribute scheme { atomURI }?, 2075 attribute label { text }?, 2076 undefinedContent 2078 } 2080 appInlineCategories = 2081 element app:categories { 2082 attribute fixed { "yes" | "no" }?, 2083 attribute scheme { atomURI }?, 2084 (atomCategory*) 2085 } 2087 appOutOfLineCategories = 2088 element app:categories { 2089 attribute href { atomURI }, 2090 (empty) 2091 } 2093 appCategories = appInlineCategories | appOutOfLineCategories 2095 # Extensibility 2097 undefinedContent = (text|anyForeignElement)* 2099 anyElement = 2100 element * { 2101 (attribute * { text } 2102 | text 2103 | anyElement)* 2104 } 2106 anyForeignElement = 2107 element * - atom:* { 2108 (attribute * { text } 2109 | text 2110 | anyElement)* 2111 } 2113 # EOF 2115 Appendix C. Revision History 2117 [[anchor44: This section to be removed upon publication.]] 2119 draft-ietf-atompub-protocol-13: Added Lisa's verbiage. Folded in 2120 James' Atom Format media type 'type' parameter spec. Updated 2121 document references to be more consistent, added URLs to some, and 2122 shortened up their anchors. Debugged rnc. 2124 draft-ietf-atompub-protocol-11: Parts of PaceAppEdited. 2125 PaceSecurityConsiderationsRevised. 2127 draft-ietf-atompub-protocol-10: PaceRemoveTitleHeader2, 2128 PaceSlugHeader4, PaceOnlyMemberURI,PaceOneAppNamespaceOnly, 2129 PaceAppCategories, PaceExtendIntrospection, 2130 UseElementsForAppCollectionTitles3, renamed Introspection to Service, 2131 lots of good editorials suggestions, updated media example with slug, 2132 moved xml conventions to convention sections, renamed XMl related 2133 Conventions to Atom Publishing Protocol Documents, added auth header 2134 to examples, consolidated definition of all resource types into the 2135 model section, added IANA reg info for application/atomcat+xml. 2137 draft-ietf-atompub-protocol-09: PaceWorkspaceMayHaveCollections, 2138 PaceMediaEntries5, 2139 http://www.imc.org/atom-protocol/mail-archive/msg05322.html, and 2140 http://www.imc.org/atom-protocol/mail-archive/msg05272.html 2142 draft-ietf-atompub-protocol-08: added infoset ref; added wording re 2143 IRI/URI; fixed URI/IRI ; next/previous fixed as per Atom 2144 LinkRelations Attribute 2145 (http://www.imc.org/atom-protocol/mail-archive/msg04095.html); 2146 incorporated: PaceEditLinkMustToMay; PaceMissingDraftHasNoMeaning, 2147 PaceRemoveMemberTypeMust, PaceRemoveMemberTypePostMust, 2148 PaceTitleHeaderOnlyInMediaCollections, PacePreserveForeignMarkup, 2149 PaceClarifyTitleHeader, PaceClarifyMediaResourceLinks, 2150 PaceTwoPrimaryCollections; 2152 draft-ietf-atompub-protocol-07: updated Atom refs to RFC4287; 2153 incorporated PaceBetterHttpResponseCode; 2154 PaceClarifyCollectionAndDeleteMethodByWritingLessInsteadOfMore; 2155 PaceRemoveAcceptPostText; PaceRemoveListTemplate2; 2156 PaceRemoveRegistry; PaceRemoveWhoWritesWhat; 2157 PaceSimplifyClarifyBetterfyRemoveBogusValidityText; 2158 PaceCollectionOrderSignificance; PaceFixLostIntrospectionText; 2159 PaceListPaging; PaceCollectionControl; element typo in Listing 2160 collections para3 (was app:member-type, not app:list-template); 2161 changed post atom entry example to be valid. Dropped inline use of 2162 'APP'. Removed nested diagram from section 4. Added ed notes in the 2163 security section. 2165 draft-ietf-atompub-protocol-06 - Removed: Robert Sayre from the 2166 contributors section per his request. Added in 2167 PaceCollectionControl. Fixed all the {daterange} verbage and 2168 examples so they all use a dash. Added full rnc schema. Collapsed 2169 Introspection and Collection documents into a single document. 2170 Removed {dateRange} queries. Renamed search to list. Moved 2171 discussion of media and entry collection until later in the document 2172 and tied the discussion to the Introspection element app:member-type. 2174 draft-ietf-atompub-protocol-05 - Added: Contributors section. Added: 2175 de hOra to editors. Fixed: typos. Added diagrams and description to 2176 model section. Incorporates PaceAppDocuments, PaceAppDocuments2, 2177 PaceSimplifyCollections2 (large-sized chunks of it anyhow: the 2178 notions of Entry and Generic resources, the section 4 language on the 2179 Protocol Model, 4.1 through 4.5.2, the notion of a Collection 2180 document, as in Section 5 through 5.3, Section 7 "Collection 2181 resources", Selection resources (modified from pace which talked 2182 about search); results in major mods to Collection Documents, Section 2183 9.2 "Title: Header" and brokeout para to section 9.1 Editing Generic 2184 Resources). Added XML namespace and language section. Some cleanup 2185 of front matter. Added Language Sensitivity to some attributes. 2186 Removed resource descriptions from terminology. Some juggling of 2187 sections. See: 2188 http://www.imc.org/atom-protocol/mail-archive/msg01812.html. 2190 draft-ietf-atompub-protocol-04 - Add ladder diagrams, reorganize, add 2191 SOAP interactions 2193 draft-ietf-atompub-protocol-03 - Incorporates PaceSliceAndDice3 and 2194 PaceIntrospection. 2196 draft-ietf-atompub-protocol-02 - Incorporates Pace409Response, 2197 PacePostLocationMust, and PaceSimpleResourcePosting. 2199 draft-ietf-atompub-protocol-01 - Added in sections on Responses for 2200 the EditURI. Allow 2xx for response to EditURI PUTs. Elided all 2201 mentions of WSSE. Started adding in some normative references. 2202 Added the section "Securing the Atom Protocol". Clarified that it is 2203 possible that the PostURI and FeedURI could be the same URI. Cleaned 2204 up descriptions for Response codes 400 and 500. 2206 Rev draft-ietf-atompub-protocol-00 - 5Jul2004 - Renamed the file and 2207 re-titled the document to conform to IETF submission guidelines. 2208 Changed MIME type to match the one selected for the Atom format. 2209 Numerous typographical fixes. We used to have two 'Introduction' 2210 sections. One of them was moved into the Abstract the other absorbed 2211 the Scope section. IPR and copyright notifications were added. 2213 Rev 09 - 10Dec2003 - Added the section on SOAP enabled clients and 2214 servers. 2216 Rev 08 - 01Dec2003 - Refactored the specification, merging the 2217 Introspection file into the feed format. Also dropped the 2218 distinction between the type of URI used to create new entries and 2219 the kind used to create comments. Dropped user preferences. 2221 Rev 07 - 06Aug2003 - Removed the use of the RSD file for auto- 2222 discovery. Changed copyright until a final standards body is chosen. 2223 Changed query parameters for the search facet to all begin with atom- 2224 to avoid name collisions. Updated all the Entries to follow the 0.2 2225 version. Changed the format of the search results and template file 2226 to a pure element based syntax. 2228 Rev 06 - 24Jul2003 - Moved to PUT for updating Entries. Changed all 2229 the mime-types to application/x.atom+xml. Added template editing. 2230 Changed 'edit-entry' to 'create-entry' in the Introspection file to 2231 more accurately reflect its purpose. 2233 Rev 05 - 17Jul2003 - Renamed everything Echo into Atom. Added 2234 version numbers in the Revision history. Changed all the mime-types 2235 to application/atom+xml. 2237 Rev 04 - 15Jul2003 - Updated the RSD version used from 0.7 to 1.0. 2238 Change the method of deleting an Entry from POSTing to 2239 using the HTTP DELETE verb. Also changed the query interface to GET 2240 instead of POST. Moved Introspection Discovery to be up under 2241 Introspection. Introduced the term 'facet' for the services listed 2242 in the Introspection file. 2244 Rev 03 - 10Jul2003 - Added a link to the Wiki near the front of the 2245 document. Added a section on finding an Entry. Retrieving an Entry 2246 now broken out into its own section. Changed the HTTP status code 2247 for a successful editing of an Entry to 205. 2249 Rev 02 - 7Jul2003 - Entries are no longer returned from POSTs, 2250 instead they are retrieved via GET. Cleaned up figure titles, as 2251 they are rendered poorly in HTML. All content-types have been 2252 changed to application/atom+xml. 2254 Rev 01 - 5Jul2003 - Renamed from EchoAPI.html to follow the more 2255 commonly used format: draft-gregorio-NN.html. Renamed all references 2256 to URL to URI. Broke out introspection into its own section. Added 2257 the Revision History section. Added more to the warning that the 2258 example URIs are not normative. 2260 Authors' Addresses 2262 Joe Gregorio (editor) 2263 IBM 2264 4205 South Miama Blvd. 2265 Research Triangle Park, NC 27709 2266 US 2268 Phone: +1 919 272 3764 2269 Email: joe@bitworking.org 2270 URI: http://ibm.com/ 2272 Bill de hOra (editor) 2273 Propylon Ltd. 2274 45 Blackbourne Square, Rathfarnham Gate 2275 Dublin, Dublin D14 2276 IE 2278 Phone: +353-1-4927444 2279 Email: bill.dehora@propylon.com 2280 URI: http://www.propylon.com/ 2282 Full Copyright Statement 2284 Copyright (C) The IETF Trust (2007). 2286 This document is subject to the rights, licenses and restrictions 2287 contained in BCP 78, and except as set forth therein, the authors 2288 retain all their rights. 2290 This document and the information contained herein are provided on an 2291 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2292 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 2293 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 2294 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 2295 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2296 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2298 Intellectual Property 2300 The IETF takes no position regarding the validity or scope of any 2301 Intellectual Property Rights or other rights that might be claimed to 2302 pertain to the implementation or use of the technology described in 2303 this document or the extent to which any license under such rights 2304 might or might not be available; nor does it represent that it has 2305 made any independent effort to identify any such rights. Information 2306 on the procedures with respect to rights in RFC documents can be 2307 found in BCP 78 and BCP 79. 2309 Copies of IPR disclosures made to the IETF Secretariat and any 2310 assurances of licenses to be made available, or the result of an 2311 attempt made to obtain a general license or permission for the use of 2312 such proprietary rights by implementers or users of this 2313 specification can be obtained from the IETF on-line IPR repository at 2314 http://www.ietf.org/ipr. 2316 The IETF invites any interested party to bring to its attention any 2317 copyrights, patents or patent applications, or other proprietary 2318 rights that may cover technology that may be required to implement 2319 this standard. Please address the information to the IETF at 2320 ietf-ipr@ietf.org. 2322 Acknowledgment 2324 Funding for the RFC Editor function is provided by the IETF 2325 Administrative Support Activity (IASA).