idnits 2.17.1 draft-ietf-atompub-protocol-14.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 2423. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2434. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2441. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2447. 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 (March 4, 2007) is 6261 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 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 4346 (Obsoleted by RFC 5246) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 6 errors (**), 0 flaws (~~), 1 warning (==), 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 IBM 4 Intended status: Standards Track B. de hOra, Ed. 5 Expires: September 5, 2007 Propylon Ltd. 6 March 4, 2007 8 The Atom Publishing Protocol 9 draft-ietf-atompub-protocol-14.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 September 5, 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 transfer 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. Workspaces . . . . . . . . . . . . . . . . . . . . . . . . 18 81 8.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 19 82 8.3. Element Definitions . . . . . . . . . . . . . . . . . . . 20 83 8.3.1. The "app:service" Element . . . . . . . . . . . . . . 20 84 8.3.2. The "app:workspace" Element . . . . . . . . . . . . . 20 85 8.3.3. The "app:collection" Element . . . . . . . . . . . . . 21 86 8.3.4. The "app:accept" Element . . . . . . . . . . . . . . . 21 87 8.3.5. The "app:categories" Element . . . . . . . . . . . . . 22 88 9. Creating and Editing Resources . . . . . . . . . . . . . . . . 24 89 9.1. Member URIs . . . . . . . . . . . . . . . . . . . . . . . 24 90 9.2. Creating resources with POST . . . . . . . . . . . . . . . 24 91 9.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 25 92 9.3. Updating Resources with PUT . . . . . . . . . . . . . . . 26 93 9.4. Deleting Resources with DELETE . . . . . . . . . . . . . . 26 94 9.5. Caching and entity tags . . . . . . . . . . . . . . . . . 26 95 9.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 26 96 9.6. Media Resources and Media Link Entries . . . . . . . . . . 28 97 9.6.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 29 98 9.7. The Slug: Header . . . . . . . . . . . . . . . . . . . . . 35 99 9.7.1. Slug: Header syntax . . . . . . . . . . . . . . . . . 36 100 9.7.2. Example . . . . . . . . . . . . . . . . . . . . . . . 36 101 10. Listing Collections . . . . . . . . . . . . . . . . . . . . . 37 102 10.1. Collection partial lists . . . . . . . . . . . . . . . . . 37 103 10.2. The "app:edited" Element . . . . . . . . . . . . . . . . . 38 104 11. Atom Format Link Relation Extensions . . . . . . . . . . . . . 40 105 11.1. The "edit" Link Relation . . . . . . . . . . . . . . . . . 40 106 11.2. The "edit-media" Link Relation . . . . . . . . . . . . . . 40 107 12. The Atom Format Type Parameter . . . . . . . . . . . . . . . . 41 108 12.1. The 'type' parameter . . . . . . . . . . . . . . . . . . . 41 109 12.1.1. Conformance . . . . . . . . . . . . . . . . . . . . . 41 110 13. Atom Publishing Controls . . . . . . . . . . . . . . . . . . . 42 111 13.1. The "app:control" Element . . . . . . . . . . . . . . . . 42 112 13.1.1. The "app:draft" Element . . . . . . . . . . . . . . . 42 113 14. Securing the Atom Publishing Protocol . . . . . . . . . . . . 43 114 15. Security Considerations . . . . . . . . . . . . . . . . . . . 44 115 15.1. Denial of Service . . . . . . . . . . . . . . . . . . . . 44 116 15.2. Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 44 117 15.3. Spoofing Attacks . . . . . . . . . . . . . . . . . . . . . 44 118 15.4. Linked Resources . . . . . . . . . . . . . . . . . . . . . 44 119 15.5. Digital Signatures and Encryption . . . . . . . . . . . . 44 120 15.6. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 44 121 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 122 16.1. Content-type registration for 123 'application/atomserv+xml' . . . . . . . . . . . . . . . . 45 124 16.2. Content-type registration for 'application/atomcat+xml' . 46 125 16.3. Header field registration for 'SLUG' . . . . . . . . . . . 47 126 16.4. The Link Relation registration "edit" . . . . . . . . . . 48 127 16.5. The Link Relation registration "edit-media" . . . . . . . 48 128 16.6. The Atom Format Media Type Parameter . . . . . . . . . . . 48 129 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49 130 17.1. Normative References . . . . . . . . . . . . . . . . . . . 49 131 17.2. Informative References . . . . . . . . . . . . . . . . . . 50 132 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 52 133 Appendix B. RELAX NG Compact Schema . . . . . . . . . . . . . . . 53 134 Appendix C. Revision History . . . . . . . . . . . . . . . . . . 59 135 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 63 136 Intellectual Property and Copyright Statements . . . . . . . . . . 64 138 1. Introduction 140 The Atom Publishing Protocol is an application-level protocol for 141 publishing and editing Web resources using HTTP [RFC2616] and XML 1.0 142 [W3C.REC-xml]. The protocol supports the creation of Web resources 143 and provides facilities for: 145 o Collections: Sets of resources, which can be retrieved in whole or 146 in part. 148 o Services: Discovery and description of Collections. 150 o Editing: Creating, updating and deleting resources. 152 The Atom Publishing Protocol is different from many contemporary 153 protocols in that the server is given wide latitude in processing 154 requests from clients. See Section 4 for more details. 156 2. Notational Conventions 158 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 159 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 160 document are to be interpreted as described in [RFC2119]. 162 2.1. XML-related Conventions 164 2.1.1. Referring to Information Items 166 Atom Protocol Document formats are specified in terms of the XML 167 Information Set [W3C.REC-xml-infoset], serialized as XML 1.0 168 [W3C.REC-xml]. 170 The Infoset terms "Element Information Item" and "Attribute 171 Information Item" are shortened to "element" and "attribute" 172 respectively. Therefore, when this specification uses the term 173 "element", it is referring to an Element Information Item, and when 174 it uses the term "attribute", it is referring to an Attribute 175 Information Item. 177 2.1.2. RELAX NG Schema 179 Some sections of this specification are illustrated with fragments of 180 a non-normative RELAX NG Compact schema [RNC]. However, the text of 181 this specification provides the definition of conformance. Complete 182 schemas appear in Appendix B. 184 2.1.3. Use of xml:base and xml:lang 186 XML elements defined by this specification MAY have an xml:base 187 attribute [W3C.REC-xmlbase-20010627]. When xml:base is used, it 188 serves the function described in Section 5.1.1 of URI Generic Syntax 189 [RFC3986], by establishing the base URI (or IRI) for resolving 190 relative references found within the scope of the xml:base attribute. 192 Any element defined by this specification MAY have an xml:lang 193 attribute, whose content indicates the natural language for the 194 element and its descendents. Requirements regarding the content and 195 interpretation of xml:lang are specified in Section 2.12 of XML 1.0 196 [W3C.REC-xml]. 198 3. Terminology 200 For convenience, this protocol can be referred to as the "Atom 201 Protocol" or "APP". 203 URI/IRI - A Uniform Resource Identifier and Internationalized 204 Resource Identifier. These terms and the distinction between them 205 are defined in [RFC3986] and [RFC3987]. Before an IRI found in a 206 document is used by HTTP, the IRI is first converted to a URI (see 207 Section 4). 209 In this specification the phrase "the URI of a document" is shorthand 210 for "a URI which, when dereferenced, is expected to produce that 211 document as a representation". 213 Resource - A network-accessible data object or service identified by 214 an IRI, as defined in [RFC2616]. See [W3C.REC-webarch-20041215] for 215 further discussion on resources. 217 Representation - An entity included with a request or response as 218 defined in [RFC2616]. 220 Collection - A resource that contains a set of Member Entries. See 221 Section 9. 223 Member - A resource whose IRI is listed in a Collection by a link 224 element with a relation of "edit" or "edit-media". See Section 9.1. 225 The protocol defines two kinds of Members - Entry and Media 226 resources. 228 Entry Resource - Member Resources of a Collection that are 229 represented using the "application/atom+xml" media type. 231 Media Resource -Member Resources of a Collection that are represented 232 with a media type other than "application/atom+xml". 234 Media Link Entry - an Entry Resource that contains metadata about a 235 Media Resource. 237 Workspace - A named group of Collections. See Section 8.1. 239 Service Document - A document that describes the location and 240 capabilities of one or more Collections. See Section 8. 242 Category Document - A document that describes the categories allowed 243 in a Collection. See Section 7. 245 4. Protocol Model 247 The Atom Publishing Protocol uses HTTP methods to author Member 248 Resources as follows: 250 o GET is used to retrieve a representation of a known resource. 252 o POST is used to create a new, dynamically-named, resource. When 253 the client submits non-Atom-Entry representations to a Collection 254 for creation, two resources are always created - a Media Entry for 255 the requested resource, and a Media Link Entry for metadata (in 256 Atom Entry format) about the resource. 258 o PUT is used to update a known resource. 260 o DELETE is used to remove a known resource. 262 The Atom Protocol does not specify the form of the URIs that are 263 used. HTTP ([RFC2616]) specifies that the URI space of each server 264 is controlled by that server, and this protocol imposes no further 265 constraints on that control. What is specified here are the formats 266 of the representations that are exchanged and the actions that can be 267 performed on the IRIs embedded in those representations. 269 The Atom Protocol only covers the creation, update and deletion of 270 Entry and Media resources. Other resources could be created, 271 updated, and deleted as the result of manipulating a Collection, but 272 the number of those resources, their media-types, and effects of Atom 273 Protocol operations on them are outside the scope of this 274 specification. 276 Since all aspects of client-server interaction are defined in terms 277 of HTTP, [RFC2616] should be consulted for any areas not covered in 278 this specification. 280 Along with operations on Member Resources, the Atom Protocol defines 281 Collection Resources for managing and organizing Member Resources. 282 The representation of Collections are Atom Feed documents, and 283 contain the IRIs of, and metadata about the Collection's Member 284 Resources. The Atom Protocol does not make a structural distinction 285 between Feeds used for Collections and other Atom Feeds. The only 286 mechanism that this specification supplies for indicating a 287 Collection Feed is its appearance in a Service Document. 289 Atom Protocol documents allow the use of IRIs [RFC3987], as well as 290 URIs [RFC3986]. Before an IRI found in a document is used by HTTP, 291 the IRI is first converted to a URI according the procedure defined 292 in Section 3.1 of [RFC3987]. In accordance with that specification, 293 this conversion SHOULD be applied as late as possible. Conversion 294 does not imply resource creation - the IRI and the URI into which it 295 is converted identify the same resource. 297 There are two kinds of Member Resources - Entry Resources and Media 298 Resources. Entry Resources are represented as Atom Entries 299 [RFC4287]. Media Resources can have representations in any media 300 type. A Media Link Entry is an Entry Resource that contains metadata 301 about a Media Resource. This diagram shows the classification of the 302 resources: 304 Member Resource 305 -> Entry Resource 306 -> Media Link Entry 307 -> Media Resource 309 A Collection Feed's Atom Entries contain the Entry and Media Resource 310 IRIs of the Collection. A Collection Feed can contain any number of 311 Entries for either kind, or an ordered subset of the Entries (see 312 Section 10.1). In the diagram of a Collection below, there are two 313 Entries. The first contains the IRI of an Entry Resource. The 314 second contains the IRIs of both a Media Resource and a Media Link 315 Entry Resource, which contains the metadata for that Media Resource: 317 Collection 318 Entry 319 Member Entry IRI -> Entry Resource 320 Entry 321 Member Entry IRI -> Media Link Entry 322 Media IRI -> Media Resource 324 Service Documents represent server-defined groups of Collections, and 325 are used to initialize the process of creating and editing resources. 327 4.1. Client Implementation Considerations 329 The Atom Protocol imposes few restrictions on the actions of servers. 330 Unless a constraint is specified here, servers can be expected to 331 vary in behavior, in particular around the manipulation of Atom 332 Entries sent by clients. For example, although this specification 333 only defines the expected behavior of Collections with respect to GET 334 and POST, this does not imply that PUT, DELETE, PROPPATCH and others 335 are forbidden on Collection resources - only that this specification 336 does not define what the server's response would be to those methods. 337 Similarly while some HTTP status codes are mentioned explicitly, 338 clients ought to be prepared to handle any status code from a server. 339 Servers can choose to accept, reject, delay, moderate, censor, 340 reformat, translate, relocate or recategorize the content submitted 341 to them. Only some of these choices are immediately relayed back to 342 the client in responses to client requests; other choices may only 343 become apparent later, in the feed or published entries. The same 344 series of requests to two different publishing sites can result in a 345 different series of HTTP responses, different resulting feeds or 346 different entry contents. 348 As a result, client software has to be written flexibly to accept 349 what the server decides are the results of its submissions. Any 350 server response or server content modification not explicitly 351 forbidden by this specification or HTTP ([RFC2616]) is therefore 352 allowed. 354 5. Protocol Operations 356 5.1. Retrieving a Service Document 358 Client Server 359 | | 360 | 1.) GET to Service Document | 361 |------------------------------------------>| 362 | | 363 | 2.) Service Document | 364 |<------------------------------------------| 365 | | 367 1. The client sends a GET request using the URI of the Service 368 Document. 370 2. The server responds with the document enumerating the IRIs of a 371 group of Collections and the capabilities of those Collections 372 supported by the server. The content of this document can vary 373 based on aspects of the client request, including, but not 374 limited to, authentication credentials. 376 5.2. Listing Collection Members 378 To list the members of a Collection, the client sends a GET request 379 to the URI of a Collection. An Atom Feed Document is returned whose 380 Entries contain the IRIs of Member Resources. The returned Feed may 381 describe all, or only a partial list of the Members in a Collection 382 (see Section 10). 384 Client Server 385 | | 386 | 1.) GET to Collection URI | 387 |------------------------------->| 388 | | 389 | 2.) Atom Feed Doc | 390 |<-------------------------------| 391 | | 393 1. The client sends a GET request to the URI of the Collection. 395 2. The server responds with an Atom Feed Document containing the 396 IRIs of the Collection members. 398 5.3. Creating a Resource 400 Client Server 401 | | 402 | 1.) POST to URI of Collection | 403 |------------------------------------------>| 404 | | 405 | 2.) 201 Created | 406 | Location: Member Entry URI | 407 |<------------------------------------------| 408 | | 410 1. The client POSTs a representation of the Member to the URI of the 411 Collection. 413 2. If the Member Resource was created successfully, the server 414 responds with a status code of 201 and a Location: header that 415 contains the IRI of the newly created Entry Resource. Media 416 Resources could have also been created and their IRIs can be 417 found through the Entry Resource. See Section 9.6 for more 418 details. 420 5.4. Editing a Resource 422 Once a resource has been created and its Member URI is known, that 423 URI can be used to retrieve, update, and delete the resource. 424 Section 11 describes extensions to the Atom Syndication Format used 425 in the Atom Protocol for editing purposes. 427 5.4.1. Retrieving a Resource 429 Client Server 430 | | 431 | 1.) GET to Member URI | 432 |------------------------------------------>| 433 | | 434 | 2.) Member Representation | 435 |<------------------------------------------| 436 | | 438 1. The client sends a GET request to the URI of a Member Resource to 439 retrieve its representation. 441 2. The server responds with the representation of the resource. 443 5.4.2. Updating a Resource 445 Client Server 446 | | 447 | 1.) PUT to Member URI | 448 |------------------------------------------>| 449 | | 450 | 2.) 200 OK | 451 |<------------------------------------------| 453 1. The client PUTs an updated representation to the URI of a Member 454 Resource. 456 2. If the update is successful the server responds with a status 457 code of 200. 459 5.4.3. Deleting a Resource 461 Client Server 462 | | 463 | 1.) DELETE to Member URI | 464 |------------------------------------------>| 465 | | 466 | 2.) 200 OK | 467 |<------------------------------------------| 468 | | 470 1. The client sends a DELETE request to the URI of a Member 471 Resource. 473 2. If the deletion is successful the server responds with a status 474 code of 200. 476 A different approach is taken for deleting Media Resources; see 477 Section 9.6 for details. 479 5.5. Use of HTTP Response codes 481 The Atom Protocol uses the response status codes defined in HTTP to 482 indicate the success or failure of an operation. Consult the HTTP 483 specification [RFC2616] for detailed definitions of each status code. 484 Implementers are asked to note that according to the HTTP 485 specification, HTTP 4xx and 5xx response entities SHOULD include a 486 human-readable explanation of the error. 488 6. Atom Publishing Protocol Documents 490 6.1. Document Types 492 This specification defines two kinds of Documents - Category 493 Documents and Service Documents. 495 A Category Document (Section 7) contains lists of categories 496 specified using the "atom:category" element from the Atom Syndication 497 Format. 499 A Service Document (Section 8) groups available Collections into 500 Workspaces. 502 The namespace name [W3C.REC-xml-names] for either kind of document 503 is: 504 http://purl.org/atom/app# 506 [[anchor8: The namespace name needs to be updated with the final URI 507 upon publication]] 509 This specification uses the prefix "app:" for the namespace name. 510 The prefix "atom:" is used for "http://www.w3.org/2005/Atom", the 511 namespace name of the Atom Syndication Format [RFC4287]. These 512 namespace prefixes are not semantically significant. 514 Atom Publishing Protocol Documents MUST be well-formed XML. This 515 specification does not define any DTDs for Atom Protocol formats, and 516 hence does not require them to be "valid" in the sense used by XML. 518 6.2. Document Extensibility 520 Unrecognized markup in an Atom Publishing Protocol document is 521 considered "foreign markup" as defined in Section 6 of [RFC4287]. 522 Such foreign markup can be used anywhere within a Category or Service 523 Document unless it is explicitly forbidden. Processors that 524 encounter foreign markup MUST NOT stop processing and MUST NOT signal 525 an error. Clients SHOULD preserve foreign markup when transmitting 526 such documents. 528 The namespace name "http://purl.org/atom/app#" is reserved for 529 forward compatible revisions of the Category and Service Document 530 types - this does not exclude the addition of elements and attributes 531 that might not be recognized by processors conformant to this 532 specification. Such unrecognized markup from the 533 "http://purl.org/atom/app#" namespace MUST be treated as foreign 534 markup. 536 [[anchor9: The namespace name needs to be updated with the final URI 537 upon publication]] 539 7. Category Documents 541 Category Documents contain lists of categories described using the 542 "atom:category" element from the Atom Syndication Format [RFC4287]. 543 Categories can also appear in Service Documents, where they describe 544 the categories allowed in a Collection (see Section 8.3.5). 546 Category Documents are identified with the "application/atomcat+xml" 547 media type (see Section 16). 549 7.1. Example 551 552 556 557 558 559 561 This Category Document contains three categories, with the terms 562 "animal", "vegetable", and "mineral". None of the categories use the 563 'label' attribute defined in [RFC4287]. They all inherit the 564 "http://example.com/cats/big3" 'scheme' attribute declared on the 565 app:categories element. Therefore if the "mineral" category were to 566 appear in an Atom Entry or Feed Document, it would appear as: 568 570 7.2. Element Definitions 572 7.2.1. The "app:categories" element 574 The root of a Category Document is the "app:categories" element. An 575 app:categories element can contain zero or more "atom:category" 576 elements from the Atom namespace ("http://www.w3.org/2005/Atom"). 578 An app:category child element that has no "scheme" attribute inherits 579 the attribute from its app:categories parent. An app:category child 580 element with an existing "scheme" attribute does not inherit the 581 "scheme" value of its "app:categories" parent element. 583 atomCategory = 584 element atom:category { 585 atomCommonAttributes, 586 attribute term { text }, 587 attribute scheme { atomURI }?, 588 attribute label { text }?, 589 undefinedContent 590 } 592 appInlineCategories = 593 element app:categories { 594 attribute fixed { "yes" | "no" }?, 595 attribute scheme { atomURI }?, 596 (atomCategory*) 597 } 599 appOutOfLineCategories = 600 element app:categories { 601 attribute href { atomURI }, 602 undefinedContent 603 } 605 appCategories = appInlineCategories | appOutOfLineCategories 607 7.2.1.1. Attributes of "app:categories" 609 The app:categories element can contain a "fixed" attribute, with a 610 value of either "yes" or "no", indicating whether the list of 611 categories is a fixed or an open set. The absence of the "fixed" 612 attribute is equivalent to the presence of a "fixed" attribute with a 613 value of "no". 615 Alternatively, the app:categories element MAY contain an "href" 616 attribute, whose value MUST be an IRI reference identifying a 617 Category Document. If the "href" attribute is provided, the app: 618 categories element MUST be empty and MUST NOT have the "fixed" or 619 "scheme" attributes. 621 8. Service Documents 623 For authoring to commence, a client needs to discover the 624 capabilities and locations of the available Collections. Service 625 Documents are designed to support this discovery process. 627 How Service Documents are discovered is not defined in this 628 specification. 630 Service Documents are identified with the "application/atomserv+xml" 631 media type (see Section 16). 633 8.1. Workspaces 635 A Service Document groups a server's Collections into Workspaces. 636 Operations on Workspaces, such as creation or deletion, are not 637 defined by this specification. In general, this specification 638 assigns no meaning to Workspaces; that is, a Workspace does not imply 639 any specific processing assumptions. 641 There is no requirement that a server support multiple Workspaces. 642 In addition, a Collection MAY appear in more than one Workspace. 644 8.2. Example 646 647 649 650 Main Site 651 653 My Blog Entries 654 656 657 659 Pictures 660 image/* 661 662 663 664 Side Bar Blog 665 667 Remaindered Links 668 entry 669 670 673 676 677 678 679 681 The Service Document above describes two Workspaces. The first 682 Workspace is called "Main Site", and has two Collections called "My 683 Blog Entries" and "Pictures", whose IRIs are 684 "http://example.org/reilly/main" and "http://example.org/reilly/pic" 685 respectively. The "Pictures" Workspace includes an "accept" element 686 indicating that a client can post image files to the Collection to 687 create new Media Resources (entries with associated Media Resources 688 are discussed in Section 9.6). 690 The second Workspace is called "Side Bar Blog" and has a single 691 Collection called "Remaindered Links" whose IRI is 692 "http://example.org/reilly/list". 694 Within each of the two Entry collections, the categories element 695 provides a list of available categories for Member Entries. In the 696 "My Blog Entries" Collection, the list of available categories is 697 available through the "href" attribute. The "Side Bar Blog" 698 Collection provides a category list within the Service Document, but 699 states the list is fixed, signaling a request from the server that 700 Entries be POSTed using only those two categories. 702 8.3. Element Definitions 704 8.3.1. The "app:service" Element 706 The root of a Service Document is the "app:service" element. 708 The "app:service" element is the container for service information 709 associated with one or more Workspaces. An app:service element MUST 710 contain one or more app:workspace elements. 712 namespace app = "http://purl.org/atom/app#" 713 start = appService 715 appService = 716 element app:service { 717 appCommonAttributes, 718 ( appWorkspace+ 719 & extensionElement* ) 720 } 722 8.3.2. The "app:workspace" Element 724 Workspaces are server-defined groups of Collections. The "app: 725 workspace" element contains zero or more app:collection elements 726 describing the Collections of resources available for editing. 728 appWorkspace = 729 element app:workspace { 730 appCommonAttributes, 731 ( atomTitle 732 & appCollection* 733 & extensionSansTitleElement* ) 734 } 736 atomTitle = element atom:title { atomTextConstruct } 738 8.3.2.1. The "atom:title" Element 740 The app:workspace element MUST contain one "atom:title" element (as 741 defined in [RFC4287]), giving a human-readable title for the 742 Workspace. 744 8.3.3. The "app:collection" Element 746 The "app:collection" element describes a Collection. The app: 747 collection element MAY contain one app:accept element and MAY contain 748 any number of app:categories elements. The app:collection element 749 MUST NOT contain more than one app:accept element. 751 appCollection = 752 element app:collection { 753 appCommonAttributes, 754 attribute href { atomURI }, 755 ( atomTitle 756 & appAccept? 757 & appCategories* 758 & extensionSansTitleElement* ) 759 } 761 8.3.3.1. Usage in Atom Feed Documents 763 The app:collection element MAY appear as a child of an atom:feed or 764 atom:source element in an Atom Feed Document. Its content identifies 765 a Collection by which new Entries can be added to appear in the feed. 766 The app:collection element is considered foreign markup as defined in 767 Section 6 of [RFC4287]. 769 8.3.3.2. The "href" Attribute 771 The app:collection element MUST contain an "href" attribute, whose 772 value gives the IRI of the Collection. 774 8.3.3.3. The "atom:title" Element 776 The app:collection Element MUST contain one "atom:title" element (as 777 defined in [RFC4287]), giving a human-readable title for the 778 Collection. 780 8.3.4. The "app:accept" Element 782 The "app:accept" element value specifies a comma-separated list of 783 media-ranges (see [RFC2616]). The list identifies the types of 784 representations that can be POSTed to the URI of a Collection. 786 Whitespace around and between media-range values is insignificant and 787 MUST be ignored. 789 The app:accept element is similar to the HTTP Accept request-header 790 [RFC2616] with the exception that app:accept has no notion of 791 preference. As a result, the value syntax of app:accept does not use 792 "accept-params" or "q" arguments as specified in [RFC2616], section 793 14.1. 795 The order of media-ranges is not significant. For example, the 796 following lists are all equivalent: 798 image/png,image/* 799 image/*, image/png 800 image/* 802 A value of "entry" MAY appear in any list of media-ranges and 803 indicates that Atom Entry Documents can be POSTed to the Collection. 804 The value is equivalent to the media type and format parameter 805 "application/atom+xml;type=entry", as defined in Section 12. If the 806 accept element exists but is empty, clients SHOULD assume that the 807 Collection does not support the creation of new Entries. If the 808 accept element is not present, clients SHOULD treat this as 809 equivalent to entry. 811 appAccept = 812 element app:accept { 813 appCommonAttributes, 814 ( appTypeValue? ) 815 } 817 appTypeValue = ( "entry" | media-type |entry-or-media-type ) 818 media-type = xsd:string { pattern = "entry,(.+/.+,?)*" } 819 entry-or-media-type = xsd:string { pattern = "(.+/.+,?)*" } 821 8.3.5. The "app:categories" Element 823 The "app:categories" element provides a list of the categories that 824 can be applied to the members of a Collection. See Section 7.2.1 for 825 the detailed definition of app:categories. 827 The server MAY reject attempts to create or update members whose 828 categories are not listed in the Collection Document. Collections 829 that indicate the category set is open SHOULD NOT reject otherwise 830 acceptable members whose categories are not listed by the Collection. 832 The absence of an "app:categories" element means that the category 833 handling of the Collection is unspecified. 835 9. Creating and Editing Resources 837 9.1. Member URIs 839 The Member URI allows clients to retrieve, update and delete a Member 840 Resource using HTTP's GET, PUT and DELETE methods. As their name 841 indicates, Entry Resources have Atom Entry documents as 842 representations. 844 Member URIs appear in two places. They are returned in a Location 845 header after successful resource creation using POST, as described in 846 Section 9.2 below. They can also appear in a Collection feed's 847 entries, as atom:link elements with a link relation of "edit". 849 A Member Entry SHOULD contain such an atom:link element with a link 850 relation of "edit", which indicates the Member URI. 852 9.2. Creating resources with POST 854 To add members to a Collection, clients send POST requests to the URI 855 of the Collection. 857 Successful member creation is indicated with a 201 ("Created") 858 response code. When the Collection responds with a status code of 859 201 ("Created"), it SHOULD also return a response body, which MUST be 860 an Atom Entry Document representing the newly-created resource. 861 Since the server is free to alter the POSTed Entry, for example by 862 changing the content of the "atom:id" element, returning the Entry 863 can be useful to the client, enabling it to correlate the client and 864 server views of the new Entry. 866 When a Member Resource is created, its Member Entry URI MUST be 867 returned in a Location header in the Collections's response. 869 If the creation request contained an Atom Entry Document, and the 870 subsequent response from the server contains a Content-Location 871 header that matches the Location header character-for-character, then 872 the client is authorized to interpret the response entity as being 873 the representation of the newly created Entry. Without a matching 874 Content-Location header the client MUST NOT assume the returned 875 entity is a complete representation of the created resource. 877 The request body sent with the POST need not be an Atom Entry. For 878 example, it might be a picture, or a movie. Collections MAY return a 879 response with a status code of 415 ("Unsupported Media Type") to 880 indicate that the media-type of the POSTed entity is not allowed or 881 supported by the Collection. For a discussion of the issues in 882 creating such content, see Section 9.6. 884 9.2.1. Example 886 Below, the client sends a POST request containing an Atom Entry 887 representation to the URI of the Collection: 889 POST /myblog/entries HTTP/1.1 890 Host: example.org 891 User-Agent: Thingio/1.0 892 Authorization: Basic ZGFmZnk6c2VjZXJldA== 893 Content-Type: application/atom+xml 894 Content-Length: nnn 895 Slug: First Post 897 898 899 Atom-Powered Robots Run Amok 900 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 901 2003-12-13T18:30:02Z 902 John Doe 903 Some text. 904 906 The server signals a successful creation with a status code of 201. 907 The response includes a Location: header indicating the Member Entry 908 URI of the Atom Entry, and a representation of that Entry in the body 909 of the response. 911 HTTP/1.1 201 Created 912 Date: Fri, 7 Oct 2005 17:17:11 GMT 913 Content-Length: nnn 914 Content-Type: application/atom+xml; charset="utf-8" 915 Location: http://example.org/edit/first-post.atom 917 918 919 Atom-Powered Robots Run Amok 920 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 921 2003-12-13T18:30:02Z 922 John Doe 923 Some text. 924 926 928 The Entry created and returned by the Collection might not match the 929 Entry POSTed by the client. A server MAY change the values of 930 various elements in the Entry, such as the atom:id, atom:updated and 931 atom:author values, and MAY choose to remove or add other elements 932 and attributes, or change element content and attribute values. 934 9.3. Updating Resources with PUT 936 To update a Member Resource, clients send PUT requests to its Member 937 URI, as specified in [RFC2616]. 939 To avoid unintentional loss of data when editing Member Entries or 940 Media Link Entries, Atom Protocol clients SHOULD preserve all 941 metadata that has not been intentionally modified, including unknown 942 foreign markup as defined in Section 6 of [RFC4287]. 944 9.4. Deleting Resources with DELETE 946 To delete a Member Resource, clients send DELETE requests to its 947 Member URI, as specified in [RFC2616]. For a Media Resource, the 948 deletion of its Media Link Entry SHOULD result in the deletion of the 949 Media Resource. 951 9.5. Caching and entity tags 953 Implementers are advised to pay attention to cache controls, and to 954 make use of the mechanisms available in HTTP to make editing resource 955 easier, in particular entity-tags as outlined in 956 [W3C.NOTE-detect-lost-update-19990510]. Clients are not assured to 957 receive the most recent representations of Collection Members using 958 GET if the server is authorizing intermediaries to cache them. 960 9.5.1. Example 962 Below, the client creates a Member Entry using POST: 964 POST /myblog/entries HTTP/1.1 965 Host: example.org 966 Authorization: Basic ZGFmZnk6c2VjZXJldA== 967 Content-Type: application/atom+xml;type=entry 968 Content-Length: nnn 969 Slug: First Post 971 972 973 Atom-Powered Robots Run Amok 974 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 975 2007-02-123T17:09:02Z 976 Captain Lansing 977 It's something moving... solid metal 978 980 The server signals a successful creation with a status code of 201, 981 and returns an ETag header in the response. Because in this case the 982 server returned a Content-Location and Location header with the same 983 value, the returned Entry representation can be understood to be 984 complete (see Section 9.2) and thus the ETag entity value can be also 985 be used. 987 HTTP/1.1 201 Created 988 Date: Fri, 23 Feb 2007 21:17:11 GMT 989 Content-Length: nnn 990 Content-Type: application/atom+xml;type=entry 991 Location: http://example.org/edit/first-post.atom 992 Content-Location: http://example.org/edit/first-post.atom 993 ETag: "e180ee84f0671b1" 995 996 997 Atom-Powered Robots Run Amok 998 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 999 2007-02-123T17:09:02Z 1000 Captain Lansing 1001 It's something moving... solid metal 1002 1004 The client can if it wishes use the returned ETag value to later 1005 construct a "Conditional GET" as defined in [RFC2616]. In this case, 1006 prior to editing the client sends the ETag value for the Member using 1007 the If-None-Match: header. 1008 GET /edit/first-post.atom HTTP/1.1 1009 Host: example.org 1010 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1011 If-None-Match: "e180ee84f0671b1" 1013 If the Entry has not been modified, the server (or an intermediary 1014 cache) can return a status code of 304 (Not Modified). This allows 1015 the client to determine it still has the most recent representation 1016 of the Entry at the time of editing. 1018 HTTP/1.1 304 Not Modified 1019 Date: Sat, 24 Feb 2007 13:17:11 GMT 1020 ETag: "e180ee84f0671b1" 1022 After editing, the client can PUT the updated Entry and send the ETag 1023 entity value in an If-Match header, informing the server to accept 1024 the entry on the condition the entity value sent still matches the 1025 server's. 1027 PUT /edit/first-post.atom HTTP/1.1 1028 Host: example.org 1029 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1030 Content-Type: application/atom+xml;type=entry 1031 Content-Length: nnn 1032 If-Match: "e180ee84f0671b1" 1034 1035 1036 Atom-Powered Robots Run Amok 1037 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 1038 2007-02-24T16:34:06Z 1039 Captain Lansing 1040 Update: it's a hoax! 1041 1043 The server however has since received a more recent update than the 1044 client's, and responds with a status code of 412 (Precondition 1045 Failed). 1047 HTTP/1.1 412 Precondition Failed 1048 Date: Sat, 24 Feb 2007 16:34:11 GMT 1049 ETag: "r34rrt84f0671b22" 1051 This informs the client that the server has a more recent version of 1052 the Entry and will not allow the update. 1054 9.6. Media Resources and Media Link Entries 1056 A client can POST a media type other than application/atom+xml to a 1057 Collection. Such a request always creates two new resources - one 1058 that corresponds to the entity sent in the request, called the Media 1059 Resource, and an associated Member Entry, called the Media Link 1060 Entry. Media Link Entries are represented as Atom Entries and appear 1061 in the Collection. 1063 The Media Link Entry contains the metadata and IRI of the (perhaps 1064 non-textual) Media Resource. The Media Link Entry thus makes the 1065 metadata about the Media Resource separately available for retrieval 1066 and update. 1068 The server can signal the media types it will accept using the 1069 "accept" element in the Service Document as specified in 1070 Section 8.3.4. 1072 Successful responses to creation requests MUST include the URI of the 1073 Media Link Entry in the Location header. The Media Link Entry SHOULD 1074 contain an atom:link element with a link relation of "edit-media" 1075 that contains the Media Resource IRI. The Media Link Entry MUST have 1076 an "atom:content" element with a "src" attribute. The value of the 1077 "src" attribute is an IRI for the newly created Media Resource. It 1078 is OPTIONAL that the IRI of the "src" attribute on the atom:content 1079 element be the same as the Media Resource IRI. For example, the 1080 "src" attribute value might instead be a link into a static cache or 1081 content distribution network and not the Media Resource IRI. 1083 Implementers are asked to note that according to the requirements of 1084 [RFC4287], Entries, and thus Media Link Entries, MUST contain an 1085 atom:summary element. Upon successful creation of a Media Link 1086 Entry, a server MAY choose to populate the atom:summary element (as 1087 well as any other required elements such as atom:id, atom:author and 1088 atom:title) with content derived from the POSTed entity or from any 1089 other source. A server might not allow a client to modify the server 1090 selected values for these elements. 1092 For resource creation this specification only defines cases where the 1093 POST body has an Atom Entry entity declared as an Atom media type 1094 ("application/atom+xml"), or a non-Atom entity declared as a non-Atom 1095 media type. It does not specify any request semantics or server 1096 behavior in the case where the POSTed media-type is "application/ 1097 atom+xml" but the body is something other than an Atom Entry. In 1098 particular, what happens on POSTing an Atom Feed Document to a 1099 Collection using the "application/atom+xml" media type is undefined. 1101 The Atom Protocol does not specify a means to create multiple 1102 representations of the same resource (for example a PNG and a JPG of 1103 the same image) on creation or update. 1105 9.6.1. Examples 1107 Below, the client sends a POST request containing a PNG image to the 1108 URI of a Collection that accepts PNG images: 1110 POST /media/ HTTP/1.1 1111 Host: example.org 1112 Content-Type: image/png 1113 Slug: The Beach 1114 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1115 Content-Length: nnn 1117 ...binary data... 1119 The server signals a successful creation with a status code of 201. 1120 The response includes a Location header indicating the Member URI of 1121 the Media Link Entry and a representation of that entry in the body 1122 of the response. The Media Link Entry includes a content element 1123 with a src attribute. It also contains a link with a link relation 1124 of "edit-media", specifying the IRI to be used for modifying the 1125 Media Resource. 1127 HTTP/1.1 201 Created 1128 Date: Fri, 7 Oct 2005 17:17:11 GMT 1129 Content-Length: nnn 1130 Content-Type: application/atom+xml; charset="utf-8" 1131 Location: http://example.org/media/edit/the_beach.atom 1133 1134 1135 The Beach 1136 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 1137 2005-10-07T17:17:08Z 1138 Daffy 1139 1140 1142 1144 1146 1148 Later, the client PUTS a new PNG to the URI indicated in the Media 1149 Link Entry's "edit-media" link: 1151 PUT /edit/the_beach.png HTTP/1.1 1152 Host: media.example.org 1153 Content-Type: image/png 1154 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1155 Content-Length: nnn 1157 ...binary data... 1159 The server signals a successful update with a status code of 200. 1161 HTTP/1.1 200 Ok 1162 Date: Fri, 8 Oct 2006 17:17:11 GMT 1163 Content-Length: nnn 1165 The client can update the metadata for the picture. First GET the 1166 Media Link Entry: 1168 GET /media/edit/the_beach.atom HTTP/1.1 1169 Host: example.org 1170 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1172 The Media Link Entry is returned. 1174 HTTP/1.1 200 Ok 1175 Date: Fri, 7 Oct 2005 17:18:11 GMT 1176 Content-Length: nnn 1177 Content-Type: application/atom+xml; charset="utf-8" 1179 1180 1181 The Beach 1182 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 1183 2005-10-07T17:17:08Z 1184 Daffy 1185 1186 1188 1190 1192 1194 The metadata can be updated, in this case to add a summary, and then 1195 PUT back to the server. 1197 PUT /media/edit/the_beach.atom HTTP/1.1 1198 Host: example.org 1199 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1200 Content-Type: application/atom+xml 1201 Content-Length: nnn 1203 1204 1205 The Beach 1206 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 1207 2005-10-07T17:17:08Z 1208 Daffy 1209 1210 A nice sunset picture over the water. 1211 1212 1214 1216 1218 1220 The update was successful. 1222 HTTP/1.1 200 Ok 1223 Date: Fri, 7 Oct 2005 17:19:11 GMT 1224 Content-Length: 0 1226 Multiple media resources can be added to the Collection. 1228 POST /media/ HTTP/1.1 1229 Host: example.org 1230 Content-Type: image/png 1231 Slug: The Pier 1232 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1233 Content-Length: nnn 1235 ...binary data... 1237 The resource is created successfully. 1239 HTTP/1.1 201 Created 1240 Date: Fri, 7 Oct 2005 17:17:11 GMT 1241 Content-Length: nnn 1242 Content-Type: application/atom+xml; charset="utf-8" 1243 Location: http://example.org/media/edit/the_pier.atom 1245 1246 1247 The Pier 1248 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efe6b 1249 2005-10-07T17:26:43Z 1250 Daffy 1251 1252 1254 1256 1258 1260 The client can now create a new Atom Entry in the blog Entry 1261 Collection that references the two newly created Media Resources. 1263 POST /blog/ HTTP/1.1 1264 Host: example.org 1265 Content-Type: application/atom+xml 1266 Slug: A day at the beach 1267 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1268 Content-Length: nnn 1270 1271 1272 A fun day at the beach 1273 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6b 1274 2005-10-07T17:40:02Z 1275 Daffy 1276 1277 1278 We had a good day at the beach. 1279 1281 1282 Later we walked down to the pier. 1283 1285 1286 1287 1288 1290 The resource is created successfully. 1292 HTTP/1.1 200 Ok 1293 Date: Fri, 7 Oct 2005 17:20:11 GMT 1294 Content-Length: nnn 1295 Content-Type: application/atom+xml; charset="utf-8" 1296 Location: http://example.org/blog/atom/a-day-at-the-beach.atom 1298 1299 1300 A fun day at the beach 1301 http://example.org/blog/a-day-at-the-beach.xhtml 1302 2005-10-07T17:43:07Z 1303 Daffy 1304 1305 1306 We had a good day at the beach. 1307 1309 1310 Later we walked down to the pier. 1311 1313 1314 1315 1316 1318 1320 1322 Note that the returned Entry contains a link with a relation of 1323 "alternate" that points to the associated XHTML page that was 1324 created. This is not required by this specification, but is included 1325 to show the kinds of changes a server may make to an Entry. 1327 9.7. The Slug: Header 1329 Slug is a HTTP entity-header that when accompanying a POST to a 1330 Collection, constitutes a request by the client that its value be 1331 used as part of the URI for the to-be-created Member Resource. 1333 Servers MAY use the value of the Slug header when creating the Member 1334 URI of the newly-created resource, for instance by using some or all 1335 of the words in the value for the last URI segment. Servers MAY also 1336 use the value when creating the atom:id or as the title of a Media 1337 Link Entry (see Section 9.6.). 1339 Servers MAY choose to ignore the Slug entity-header and MAY alter the 1340 value before using it. For instance, a server might filter out some 1341 characters or replace accented letters with non-accented ones, 1342 replace spaces with underscores, change case, and so on. 1344 9.7.1. Slug: Header syntax 1346 The syntax of this header MUST conform to the augmented BNF grammar 1347 in section 2.1 of the HTTP/1.1 specification [RFC2616]. The TEXT 1348 rule is described in section 2.2 of the same document. 1350 Slug = "Slug" ":" *TEXT 1352 Clients MAY send non-ASCII characters in the Slug entity-header, 1353 which they MUST encode using "encoded-words", as defined in 1354 [RFC2047]. Servers SHOULD treat the slug as [RFC2047] encoded if it 1355 matches the "encoded-words" production. 1357 9.7.2. Example 1359 Here is an example of the Slug: header that uses the encoding rules 1360 of [RFC2047]. 1362 POST /myblog/entries HTTP/1.1 1363 Host: example.org 1364 Content-Type: image/png 1365 Slug: =?iso-8859-1?q?The_Beach?= 1366 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1367 Content-Length: nnn 1369 ...binary data... 1371 See Section 9.2.1 for an example of the Slug: header applied to the 1372 creation of an Entry Resource. 1374 10. Listing Collections 1376 Collection Resources MUST provide representations in the form of Atom 1377 Feed documents whose Entries contain the IRIs of the Members in the 1378 Collection. No structural distinction is made between Collection 1379 Feeds and other kinds of Feeds - a Feed might act both as a 'public' 1380 feed for subscription purposes and as a Collection Feed. 1382 Each Entry in the Feed Document SHOULD have an atom:link element with 1383 a relation of "edit" (See Section 11.1). 1385 The Entries in the returned Atom Feed SHOULD be ordered by their 1386 "atom:updated" property, with the most recently updated Entries 1387 coming first in the document order. Since the Atom Syndication 1388 Format states that the value of atom:updated is altered when the 1389 changes to an Entry are something that "the publisher considers 1390 significant", clients SHOULD be constructed in consideration of the 1391 fact that changes which do not result in alterations to the atom: 1392 updated value of an Entry will not affect the position of the Entry 1393 in a Collection. The atom:updated value is not equivalent to the 1394 HTTP Last-Modified: header and can not be used to determine the 1395 freshness of cached responses. 1397 Clients MUST NOT assume that an Atom Entry returned in the Feed is a 1398 full representation of an Entry Resource and SHOULD perform a GET on 1399 the URI of the Member Entry before editing it. See Section 9.5 for a 1400 discussion on the implications of cache control directives when 1401 obtaining entries. 1403 10.1. Collection partial lists 1405 Collections can contain large numbers of resources. A client such as 1406 a web spider or web browser might be overwhelmed if the response to a 1407 GET contained every Entry in a Collection - in turn the server might 1408 also waste bandwidth and processing time on generating a response 1409 that cannot be handled. For this reason, servers MAY respond to 1410 Collection GET requests with a feed document containing a 'partial 1411 list' of the Collection's members, which also links to the next 1412 partial list feed if it exists. The first such partial list returned 1413 MUST contain the most recently updated member resources and MUST have 1414 an atom:link with a "next" relation whose "href" value is the URI of 1415 the next partial list of the Collection. This next partial list will 1416 contain the next most recently updated set of Member Resources (and 1417 an atom:link to the following partial list if it exists). 1419 In addition, partial list feeds MAY contain link elements with "rel" 1420 attribute values of "next", "previous", "first" and "last" that can 1421 be used to navigate through the complete set of entries in the 1422 Collection. 1424 For instance, suppose a client is supplied the URI 1425 "http://example.org/entries/go" of a Collection of Member entries, 1426 where the server as a matter of policy avoids generating feed 1427 documents containing more than 10 Entries. The Atom Feed document 1428 for the Collection will then represent the first partial list of a 1429 set of 10 linked feed documents. The "first" relation will reference 1430 the initial feed document in the set and the "last" relation 1431 references the final Atom Feed Document in the set. Within each 1432 document, the "next" and "previous" link relations reference the 1433 preceding and subsequent documents. 1435 1436 1438 1440 1442 ... 1443 1445 The "next" and "previous" link elements for the partial list feed 1446 located at "http://example.org/entries/2" would look like this: 1448 1449 1451 1453 1455 1457 ... 1458 1460 10.2. The "app:edited" Element 1462 The "app:edited" element is a Date construct as defined by [RFC4287] 1463 whose content indicates the last time an Entry was edited. If the 1464 entry has not been edited yet, the content indicates the time it was 1465 created. Atom Entry elements in Collection documents SHOULD contain 1466 one "app:edited" element, and MUST NOT contain more than one. 1468 appEdited = element app:edited ( atomDateConstruct ) 1469 The server SHOULD change the value of this element every time a 1470 Collection Member Resource or an associated Media Resource has been 1471 edited. 1473 11. Atom Format Link Relation Extensions 1475 11.1. The "edit" Link Relation 1477 This specification adds the value "edit" to the Atom Registry of Link 1478 Relations (see section 7.1 of [RFC4287]). The value of "edit" 1479 specifies that the value of the href attribute is the IRI of an 1480 editable Member Entry. When appearing within an atom:entry, the href 1481 IRI can be used to retrieve, update and delete the resource 1482 represented by that Entry. An atom:entry MUST contain no more than 1483 one "edit" link relation. 1485 11.2. The "edit-media" Link Relation 1487 This specification adds the value "edit-media" to the Atom Registry 1488 of Link Relations (see section 7.1 of [RFC4287]). When appearing 1489 within an atom:entry, the value of the href attribute is an IRI that 1490 can be used to modify a Media Resource associated with that Entry. 1492 An atom:entry element MAY contain zero or more "edit-media" link 1493 relations. An atom:entry MUST NOT contain more than one atom:link 1494 element with a rel attribute value of "edit-media" that has the same 1495 "type" and "hreflang" attribute values. All "edit-media" link 1496 relations in the same Entry reference the same resource. If a client 1497 encounters multiple "edit-media" link relations in an Entry then it 1498 SHOULD choose a link based on the client preferences for "type" and 1499 "hreflang". If a client encounters multiple "edit-media" link 1500 relations in an Entry and has no preference based on the "type" and 1501 "hreflang" attributes then the client SHOULD pick the first "edit- 1502 media" link relation in document order. 1504 12. The Atom Format Type Parameter 1506 The Atom Syndication Format (RFC 4287) defines the "application/ 1507 atom+xml" media type to identify both Atom Feed and Atom Entry 1508 Documents. Implementation experience has demonstrated that Atom Feed 1509 and Entry Documents can have different processing models and that 1510 there are situations where they need to be differentiated. This 1511 document defines an optional "type" parameter used to differentiate 1512 the two types of Atom documents. 1514 12.1. The 'type' parameter 1516 This document defines a new "type" parameter for use with the 1517 "application/atom+xml" media type: 1519 type = "entry" / "feed" 1521 Neither the parameter name nor its value are case sensitive. 1523 The value "entry" indicates that the media type identifies an Atom 1524 Entry Document. The root element of the document MUST be atom:entry. 1526 The value "feed" indicates that the media type identifies an Atom 1527 Feed Document. The root element of the document MUST be atom:feed. 1529 If not specified, the type is assumed to be unspecified, requiring 1530 Atom processors to examine the root element to determine the type of 1531 Atom document. 1533 12.1.1. Conformance 1535 New specifications MAY require that the type parameter be used to 1536 identify the Atom Document type. Producers of Atom Entry Documents 1537 SHOULD use the type parameter regardless of whether or not it is 1538 required. Producers of Atom Feed Documents MAY use the parameter. 1540 Atom processors that do not recognize the "type" parameter MUST 1541 ignore its value and examine the root element to determine the 1542 document type. 1544 Atom processors that do recognize the "type" parameter SHOULD detect 1545 and report inconsistencies between the parameter's value and the 1546 actual type of the document's root element. 1548 13. Atom Publishing Controls 1550 This specification defines an Atom Format Structured Extension, as 1551 defined in Section 6 of [RFC4287], for publishing control within the 1552 "http://purl.org/atom/app#" namespace. 1554 13.1. The "app:control" Element 1556 namespace app = "http://purl.org/atom/app#" 1558 pubControl = 1559 element app:control { 1560 atomCommonAttributes, 1561 pubDraft? 1562 & extensionElement 1563 } 1565 pubDraft = 1566 element app:draft { "yes" | "no" } 1568 The "app:control" element MAY appear as a child of an atom:entry 1569 which is being created or updated via the Atom Publishing Protocol. 1570 The app:control element MUST appear only once in an Entry. The app: 1571 control element is considered foreign markup as defined in Section 6 1572 of [RFC4287]. 1574 The app:control element and its child elements MAY be included in 1575 Atom Feed or Entry Documents. 1577 The app:control element can contain an optional "app:draft" element 1578 as defined below, and can contain extension elements as defined in 1579 Section 6 of [RFC4287]. 1581 13.1.1. The "app:draft" Element 1583 The inclusion of the app:draft element represents a request by the 1584 client to control the visibility of a Member Resource. Server 1585 support is optional and thus the app:draft element MAY be ignored by 1586 the server. 1588 The number of app:draft elements in app:control MUST be zero or one. 1589 The content of an app:draft element MUST be one of "yes" or "no". If 1590 the element contains "no" this indicates a client request that the 1591 Member Resource be made publicly visible. If the app:draft element 1592 is not present then servers that support the extension MUST behave as 1593 though an app:draft element containing "no" was sent. 1595 14. Securing the Atom Publishing Protocol 1597 The Atom Publishing Protocol is based on HTTP. Authentication 1598 requirements for HTTP are covered in Section 11 of [RFC2616]. 1600 The use of authentication mechanisms to prevent POSTing or editing by 1601 unknown or unauthorized clients is RECOMMENDED but not required. 1602 When authentication is not used, clients and servers are vulnerable 1603 to trivial spoofing, denial of service and defacement attacks, 1604 however, in some contexts, this is an acceptable risk. 1606 The type of authentication deployed is a local decision made by the 1607 server operator. Clients are likely to face authentication schemes 1608 that vary across server deployments. At a minimum, client and server 1609 implementations MUST be capable of being configured to use HTTP Basic 1610 Authentication [RFC2617] in conjunction with a TLS connection as 1611 specified by [RFC2818]. See [RFC4346] for more information on TLS. 1613 The choice of authentication mechanism will impact interoperability. 1614 The minimum level of security referenced above (Basic Authentication 1615 with TLS) is considered good practice for Internet applications at 1616 the time of publication of this specification and sufficient for 1617 establishing a baseline for interoperability. Implementers are 1618 encouraged to investigate and use alternative mechanisms regarded as 1619 equivalently good or better at the time of deployment. It is 1620 RECOMMENDED that clients be implemented in such a way that allows new 1621 authentication schemes to be deployed. 1623 Because this protocol uses HTTP response status codes as the primary 1624 means of reporting the result of a request, servers are advised to 1625 respond to unauthorized or unauthenticated requests using an 1626 appropriate 4xx HTTP response code (e.g. 401 "Unauthorized" or 403 1627 "Forbidden") in accordance with [RFC2617]. 1629 15. Security Considerations 1631 As an HTTP-based protocol, APP is subject to the security 1632 considerations found in Section 15 of [RFC2616]. 1634 15.1. Denial of Service 1636 Atom Publishing server implementations need to take adequate 1637 precautions to ensure malicious clients cannot consume excessive 1638 server resources (CPU, memory, disk, etc). 1640 15.2. Replay Attacks 1642 Atom Publishing server implementations are susceptible to replay 1643 attacks. Specifically, this specification does not define a means of 1644 detecting duplicate requests. Accidentally sent duplicate requests 1645 are indistinguishable from intentional and malicious replay attacks. 1647 15.3. Spoofing Attacks 1649 Atom Publishing implementations are susceptible to a variety of 1650 spoofing attacks. Malicious clients may send Atom Entries containing 1651 inaccurate information anywhere in the document. 1653 15.4. Linked Resources 1655 Atom Feed and Entry documents can contain XML External Entities as 1656 defined in Section 4.2.2 of [W3C.REC-xml]. Atom implementations are 1657 not required to load external entities. External entities are 1658 subject to the same security concerns as any network operation and 1659 can alter the semantics of an Atom document. The same issues exist 1660 for resources linked to by Atom elements such as atom:link and atom: 1661 content. 1663 15.5. Digital Signatures and Encryption 1665 Atom Entry Documents sent to a server might contain XML Digital 1666 Signatures [W3C.REC-xmldsig-core] and might be encrypted using XML 1667 Encryption [W3C.REC-xmlenc-core] as specified in Section 5 of 1668 [RFC4287]. 1670 Servers are allowed to modify received resource representations in 1671 ways that can invalidate signatures covering those representations. 1673 15.6. URIs and IRIs 1675 Atom Publishing Protocol implementations handle URIs and IRIs. See 1676 Section 7 of [RFC3986] and Section 8 of [RFC3987]. 1678 16. IANA Considerations 1680 16.1. Content-type registration for 'application/atomserv+xml' 1682 An Atom Publishing Protocol Service Document, when serialized as XML 1683 1.0, can be identified with the following media type: 1685 MIME media type name: application 1687 MIME subtype name: atomsvc+xml 1689 Mandatory parameters: None. 1691 Optional parameters: 1693 "charset": This parameter has identical semantics to the charset 1694 parameter of the "application/xml" media type as specified in 1695 [RFC3023]. 1697 Encoding considerations: Identical to those of "application/xml" as 1698 described in [RFC3023], section 3.2. 1700 Security considerations: As defined in this specification. 1701 [[anchor30: update upon publication]] 1703 In addition, as this media type uses the "+xml" convention, it 1704 shares the same security considerations as described in [RFC3023], 1705 section 10. 1707 Interoperability considerations: There are no known interoperability 1708 issues. 1710 Published specification: This specification. [[anchor31: update upon 1711 publication]] 1713 Applications that use this media type: No known applications 1714 currently use this media type. 1716 Additional information: 1718 Magic number(s): As specified for "application/xml" in [RFC3023], 1719 section 3.2. 1721 File extension: .atomsvc 1722 Fragment identifiers: As specified for "application/xml" in 1723 [RFC3023], section 5. 1725 Base URI: As specified in [RFC3023], section 6. 1727 Macintosh File Type code: TEXT 1729 Person and email address to contact for further information: Joe 1730 Gregorio 1732 Intended usage: COMMON 1734 Author/Change controller: This specification's author(s). 1735 [[anchor32: update upon publication]] 1737 16.2. Content-type registration for 'application/atomcat+xml' 1739 An Atom Publishing Protocol Category Document, when serialized as XML 1740 1.0, can be identified with the following media type: 1742 MIME media type name: application 1744 MIME subtype name: atomcat+xml 1746 Mandatory parameters: None. 1748 Optional parameters: 1750 "charset": This parameter has identical semantics to the charset 1751 parameter of the "application/xml" media type as specified in 1752 [RFC3023]. 1754 Encoding considerations: Identical to those of "application/xml" as 1755 described in [RFC3023], section 3.2. 1757 Security considerations: As defined in this specification. 1758 [[anchor33: update upon publication]] 1760 In addition, as this media type uses the "+xml" convention, it 1761 shares the same security considerations as described in [RFC3023], 1762 section 10. 1764 Interoperability considerations: There are no known interoperability 1765 issues. 1767 Published specification: This specification. [[anchor34: update upon 1768 publication]] 1770 Applications that use this media type: No known applications 1771 currently use this media type. 1773 Additional information: 1775 Magic number(s): As specified for "application/xml" in [RFC3023], 1776 section 3.2. 1778 File extension: .atomcat 1780 Fragment identifiers: As specified for "application/xml" in 1781 [RFC3023], section 5. 1783 Base URI: As specified in [RFC3023], section 6. 1785 Macintosh File Type code: TEXT 1787 Person and email address to contact for further information: Joe 1788 Gregorio 1790 Intended usage: COMMON 1792 Author/Change controller: This specification's author(s). 1793 [[anchor35: update upon publication]] 1795 16.3. Header field registration for 'SLUG' 1797 Header field: SLUG 1799 Applicable protocol: http [RFC2616] 1801 Status: standard. 1803 Author/Change controller: IETF (iesg@ietf.org) Internet Engineering 1804 Task Force 1806 Specification document(s): draft-ietf-atompub-protocol-13.txt 1807 ([[anchor36: update on rfc number assignment]]) 1809 Related information: 1811 16.4. The Link Relation registration "edit" 1813 Attribute Value: edit 1815 Description: An IRI of an editable Member Entry. When appearing 1816 within an atom:entry, the href IRI can be used to retrieve, update 1817 and delete the resource represented by that Entry. 1819 Expected display characteristics: Undefined; this relation can be 1820 used for background processing or to provide extended 1821 functionality without displaying its value. 1823 Security considerations: Automated agents should take care when this 1824 relation crosses administrative domains (e.g., the URI has a 1825 different authority than the current document). 1827 16.5. The Link Relation registration "edit-media" 1829 Attribute Value: edit-media 1831 Description: An IRI of an editable Media Resource. When appearing 1832 within an atom:entry, the href IRI can be used to retrieve, update 1833 and delete the Media Resource associated with that Entry. 1835 Expected display characteristics: Undefined; this relation can be 1836 used for background processing or to provide extended 1837 functionality without displaying its value. 1839 Security considerations: Automated agents should take care when this 1840 relation crosses administrative domains (e.g., the URI has a 1841 different authority than the current document). 1843 16.6. The Atom Format Media Type Parameter 1845 IANA is requested to add a reference to this specification in the 1846 'application/atom+xml' media type registration. 1848 17. References 1850 17.1. Normative References 1852 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 1853 Part Three: Message Header Extensions for Non-ASCII Text", 1854 RFC 2047, November 1996. 1856 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1857 Requirement Levels", BCP 14, RFC 2119, March 1997. 1859 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1860 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1861 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1863 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1864 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1865 Authentication: Basic and Digest Access Authentication", 1866 RFC 2617, June 1999. 1868 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 1869 Types", RFC 3023, January 2001. 1871 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1872 Resource Identifier (URI): Generic Syntax", STD 66, 1873 RFC 3986, January 2005. 1875 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1876 Identifiers (IRIs)", RFC 3987, January 2005. 1878 [RFC4287] Nottingham, M. and R. Sayre, "The Atom Syndication 1879 Format", RFC 4287, December 2005. 1881 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 1882 (TLS) Protocol Version 1.1", RFC 4346, April 2006. 1884 [W3C.REC-xml] 1885 Yergeau, F., Paoli, J., Bray, T., Sperberg-McQueen, C., 1886 and E. Maler, "Extensible Markup Language (XML) 1.0 1887 (Fourth Edition)", World Wide Web Consortium 1888 Recommendation REC-xml-20060816, August 2006, 1889 . 1891 [W3C.REC-xml-infoset] 1892 Cowan, J. and R. Tobin, "XML Information Set (Second 1893 Edition)", World Wide Web Consortium Recommendation REC- 1894 xml-infoset-20040204, February 2004, 1895 . 1897 [W3C.REC-xml-names] 1898 Hollander, D., Bray, T., Tobin, R., and A. Layman, 1899 "Namespaces in XML 1.0 (Second Edition)", World Wide Web 1900 Consortium Recommendation REC-xml-names-20060816, 1901 August 2006, 1902 . 1904 [W3C.REC-xmlbase-20010627] 1905 Marsh, J., "XML Base", W3C REC W3C.REC-xmlbase-20010627, 1906 June 2001. 1908 [W3C.REC-xmldsig-core] 1909 Solo, D., Reagle, J., and D. Eastlake, "XML-Signature 1910 Syntax and Processing", World Wide Web Consortium 1911 Recommendation REC-xmldsig-core-20020212, February 2002, 1912 . 1914 [W3C.REC-xmlenc-core] 1915 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 1916 Processing", World Wide Web Consortium Recommendation REC- 1917 xmlenc-core-20021210, December 2002, 1918 . 1920 17.2. Informative References 1922 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1924 [RNC] Clark, J., "RELAX NG Compact Syntax", December 2001, . 1928 [W3C.NOTE-detect-lost-update-19990510] 1929 Nielsen, H. and D. LaLiberte, "Editing the Web: Detecting 1930 the Lost Update Problem Using Unreserved Checkout", World 1931 Wide Web Consortium NOTE NOTE-detect-lost-update, 1932 May 1999, . 1934 [W3C.REC-webarch-20041215] 1935 Walsh, N. and I. Jacobs, "Architecture of the World Wide 1936 Web, Volume One", W3C REC REC-webarch-20041215, 1937 December 2004. 1939 URIs 1941 [1] 1943 Appendix A. Contributors 1945 The content and concepts within are a product of the Atom community 1946 and the Atompub Working Group. 1948 [[anchor40: chairs to compile a contribution list for 1.0 --dehora]] 1950 Appendix B. RELAX NG Compact Schema 1952 This appendix is informative. 1954 The Relax NG schema explicitly excludes elements in the Atom Protocol 1955 namespace which are not defined in this revision of the 1956 specification. Requirements for Atom Protocol processors 1957 encountering such markup are given in Section 6.2 and Section 6.3 of 1958 [RFC4287]. 1960 The Schema for Service Documents: 1962 # -*- rnc -*- 1963 # RELAX NG Compact Syntax Grammar for the Atom Protocol 1965 namespace app = "http://purl.org/atom/app#" 1966 namespace atom = "http://www.w3.org/2005/Atom" 1967 namespace xsd = "http://www.w3.org/2001/XMLSchema" 1968 namespace xhtml = "http://www.w3.org/1999/xhtml" 1969 namespace local = "" 1971 start = appService 1973 # common:attrs 1975 atomURI = text 1977 appCommonAttributes = 1978 attribute xml:base { atomURI }?, 1979 attribute xml:lang { atomLanguageTag }?, 1980 undefinedAttribute* 1982 atomCommonAttributes = appCommonAttributes 1984 undefinedAttribute = 1985 attribute * - (xml:base | xml:lang | local:*) { text } 1987 atomLanguageTag = xsd:string { 1988 pattern = "[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*" 1989 } 1991 atomDateConstruct = 1992 appCommonAttributes, 1993 xsd:dateTime 1995 # app:service 1997 appService = 1998 element app:service { 1999 appCommonAttributes, 2000 ( appWorkspace+ 2001 & extensionElement* ) 2002 } 2004 # app:workspace 2006 appWorkspace = 2007 element app:workspace { 2008 appCommonAttributes, 2009 ( atomTitle 2010 & appCollection* 2011 & extensionSansTitleElement* ) 2012 } 2014 atomTitle = element atom:title { atomTextConstruct } 2016 # app:collection 2018 appCollection = 2019 element app:collection { 2020 appCommonAttributes, 2021 attribute href { atomURI }, 2022 ( atomTitle 2023 & appAccept? 2024 & appCategories* 2025 & extensionSansTitleElement* ) 2026 } 2028 # app:categories 2030 atomCategory = 2031 element atom:category { 2032 atomCommonAttributes, 2033 attribute term { text }, 2034 attribute scheme { atomURI }?, 2035 attribute label { text }?, 2036 undefinedContent 2037 } 2039 appInlineCategories = 2040 element app:categories { 2041 attribute fixed { "yes" | "no" }?, 2042 attribute scheme { atomURI }?, 2043 (atomCategory*) 2044 } 2046 appOutOfLineCategories = 2047 element app:categories { 2048 attribute href { atomURI }, 2049 undefinedContent 2050 } 2052 appCategories = appInlineCategories | appOutOfLineCategories 2054 # app:accept 2056 appAccept = 2057 element app:accept { 2058 appCommonAttributes, 2059 ( appTypeValue? ) 2060 } 2062 appTypeValue = ( "entry" | media-type |entry-or-media-type ) 2063 media-type = xsd:string { pattern = "entry,(.+/.+,?)*" } 2064 entry-or-media-type = xsd:string { pattern = "(.+/.+,?)*" } 2065 # above is an approximation, rnc doesn't support interleaved text 2067 # Simple Extension 2069 simpleSansTitleExtensionElement = 2070 element * - (app:*|atom:title) { 2071 text 2072 } 2074 simpleExtensionElement = 2075 element * - (app:*) { 2076 text 2077 } 2079 # Structured Extension 2081 structuredSansTitleExtensionElement = 2082 element * - (app:*|atom:title) { 2083 (attribute * { text }+, 2084 (text|anyElement)*) 2085 | (attribute * { text }*, 2086 (text?, anyElement+, (text|anyElement)*)) 2088 } 2090 structuredExtensionElement = 2091 element * - (app:*) { 2092 (attribute * { text }+, 2093 (text|anyElement)*) 2094 | (attribute * { text }*, 2095 (text?, anyElement+, (text|anyElement)*)) 2096 } 2098 # Other Extensibility 2100 extensionSansTitleElement = 2101 simpleSansTitleExtensionElement|structuredSansTitleExtensionElement 2103 extensionElement = 2104 simpleExtensionElement | structuredExtensionElement 2106 undefinedContent = (text|anyForeignElement)* 2108 # Extensions 2110 anyElement = 2111 element * { 2112 (attribute * { text } 2113 | text 2114 | anyElement)* 2115 } 2117 anyForeignElement = 2118 element * - app:* { 2119 (attribute * { text } 2120 | text 2121 | anyElement)* 2122 } 2124 atomPlainTextConstruct = 2125 atomCommonAttributes, 2126 attribute type { "text" | "html" }?, 2127 text 2129 atomXHTMLTextConstruct = 2130 atomCommonAttributes, 2131 attribute type { "xhtml" }, 2132 xhtmlDiv 2134 atomTextConstruct = atomPlainTextConstruct | atomXHTMLTextConstruct 2135 anyXHTML = element xhtml:* { 2136 (attribute * { text } 2137 | text 2138 | anyXHTML)* 2139 } 2141 xhtmlDiv = element xhtml:div { 2142 (attribute * { text } 2143 | text 2144 | anyXHTML)* 2145 } 2147 # EOF 2149 The Schema for Category Documents: 2151 # -*- rnc -*- 2152 # RELAX NG Compact Syntax Grammar for the Atom Protocol 2154 namespace app = "http://purl.org/atom/app#" 2155 namespace atom = "http://www.w3.org/2005/Atom" 2156 namespace xsd = "http://www.w3.org/2001/XMLSchema" 2157 namespace local = "" 2159 start = appCategories 2161 atomCommonAttributes = 2162 attribute xml:base { atomURI }?, 2163 attribute xml:lang { atomLanguageTag }?, 2164 undefinedAttribute* 2166 undefinedAttribute = 2167 attribute * - (xml:base | xml:lang | local:*) { text } 2169 atomURI = text 2171 atomLanguageTag = xsd:string { 2172 pattern = "[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*" 2173 } 2175 atomCategory = 2176 element atom:category { 2177 atomCommonAttributes, 2178 attribute term { text }, 2179 attribute scheme { atomURI }?, 2180 attribute label { text }?, 2181 undefinedContent 2183 } 2185 appInlineCategories = 2186 element app:categories { 2187 attribute fixed { "yes" | "no" }?, 2188 attribute scheme { atomURI }?, 2189 (atomCategory*) 2190 } 2192 appOutOfLineCategories = 2193 element app:categories { 2194 attribute href { atomURI }, 2195 (empty) 2196 } 2198 appCategories = appInlineCategories | appOutOfLineCategories 2200 # Extensibility 2202 undefinedContent = (text|anyForeignElement)* 2204 anyElement = 2205 element * { 2206 (attribute * { text } 2207 | text 2208 | anyElement)* 2209 } 2211 anyForeignElement = 2212 element * - atom:* { 2213 (attribute * { text } 2214 | text 2215 | anyElement)* 2216 } 2218 # EOF 2220 Appendix C. Revision History 2222 [[anchor42: This section to be removed upon publication.]] 2224 draft-ietf-atompub-protocol-14: typos; removed "The language context 2225 is only significant for elements and attributes declared to be 2226 "Language-Sensitive" by this specification. "; "Successful member 2227 creation is normally indicated with a 201 ("Created") response code." 2228 removed "normally" from that sentence (9.2); Added "Media Link 2229 Entries are represented as Atom Entries and appear in the 2230 Collection." to 9.6; said that an app:accept value of "entry" is 2231 equivalent to "application/atom+xml;type=entry"; double-check spec 2232 terms; Member Entry Resource -> Entry Resource; Added MLE, Entry 2233 Resource and Media Resource terms defs; 6.1 para split; 10.1 2234 collection paging, rewrote for clarity; 13.1.1 app:edited rewrote for 2235 clarity/conflict; text for GETting entries and cache handling; 4: 2236 Typo: "And Media Resources IRIs", s/Resources/Resource/; consensus 2237 call: application/atomsvc+xml, extension is .atomsvc; DRY app: 2238 categories; make it clear the app:draft support is optional whether 2239 or not the value is sent; 9.2: put related ideas together into 2240 paragraphs.; 10: partial list editing; security: use elharos text; 2241 app:edited: tweak text suplied by ari; create a section for 2242 workspaces and move the descriptive text there; Moved rfc2818 to non- 2243 normative references. Added the W3C note on lost updates as a 2244 reference. 2246 draft-ietf-atompub-protocol-13: Added Lisa's verbiage. Folded in 2247 James' Atom Format media type 'type' parameter spec. Updated 2248 document references to be more consistent, added URLs to some, and 2249 shortened up their anchors. Debugged rnc. 2251 draft-ietf-atompub-protocol-11: Parts of PaceAppEdited. 2252 PaceSecurityConsiderationsRevised. 2254 draft-ietf-atompub-protocol-10: PaceRemoveTitleHeader2, 2255 PaceSlugHeader4, PaceOnlyMemberURI,PaceOneAppNamespaceOnly, 2256 PaceAppCategories, PaceExtendIntrospection, 2257 UseElementsForAppCollectionTitles3, renamed Introspection to Service, 2258 lots of good editorials suggestions, updated media example with slug, 2259 moved xml conventions to convention sections, renamed XMl related 2260 Conventions to Atom Publishing Protocol Documents, added auth header 2261 to examples, consolidated definition of all resource types into the 2262 model section, added IANA reg info for application/atomcat+xml. 2264 draft-ietf-atompub-protocol-09: PaceWorkspaceMayHaveCollections, 2265 PaceMediaEntries5, 2266 http://www.imc.org/atom-protocol/mail-archive/msg05322.html, and 2267 http://www.imc.org/atom-protocol/mail-archive/msg05272.html 2268 draft-ietf-atompub-protocol-08: added infoset ref; added wording re 2269 IRI/URI; fixed URI/IRI ; next/previous fixed as per Atom 2270 LinkRelations Attribute 2271 (http://www.imc.org/atom-protocol/mail-archive/msg04095.html); 2272 incorporated: PaceEditLinkMustToMay; PaceMissingDraftHasNoMeaning, 2273 PaceRemoveMemberTypeMust, PaceRemoveMemberTypePostMust, 2274 PaceTitleHeaderOnlyInMediaCollections, PacePreserveForeignMarkup, 2275 PaceClarifyTitleHeader, PaceClarifyMediaResourceLinks, 2276 PaceTwoPrimaryCollections; 2278 draft-ietf-atompub-protocol-07: updated Atom refs to RFC4287; 2279 incorporated PaceBetterHttpResponseCode; 2280 PaceClarifyCollectionAndDeleteMethodByWritingLessInsteadOfMore; 2281 PaceRemoveAcceptPostText; PaceRemoveListTemplate2; 2282 PaceRemoveRegistry; PaceRemoveWhoWritesWhat; 2283 PaceSimplifyClarifyBetterfyRemoveBogusValidityText; 2284 PaceCollectionOrderSignificance; PaceFixLostIntrospectionText; 2285 PaceListPaging; PaceCollectionControl; element typo in Listing 2286 collections para3 (was app:member-type, not app:list-template); 2287 changed post atom entry example to be valid. Dropped inline use of 2288 'APP'. Removed nested diagram from section 4. Added ed notes in the 2289 security section. 2291 draft-ietf-atompub-protocol-06 - Removed: Robert Sayre from the 2292 contributors section per his request. Added in 2293 PaceCollectionControl. Fixed all the {daterange} verbage and 2294 examples so they all use a dash. Added full rnc schema. Collapsed 2295 Introspection and Collection documents into a single document. 2296 Removed {dateRange} queries. Renamed search to list. Moved 2297 discussion of media and entry collection until later in the document 2298 and tied the discussion to the Introspection element app:member-type. 2300 draft-ietf-atompub-protocol-05 - Added: Contributors section. Added: 2301 de hOra to editors. Fixed: typos. Added diagrams and description to 2302 model section. Incorporates PaceAppDocuments, PaceAppDocuments2, 2303 PaceSimplifyCollections2 (large-sized chunks of it anyhow: the 2304 notions of Entry and Generic resources, the section 4 language on the 2305 Protocol Model, 4.1 through 4.5.2, the notion of a Collection 2306 document, as in Section 5 through 5.3, Section 7 "Collection 2307 resources", Selection resources (modified from pace which talked 2308 about search); results in major mods to Collection Documents, Section 2309 9.2 "Title: Header" and brokeout para to section 9.1 Editing Generic 2310 Resources). Added XML namespace and language section. Some cleanup 2311 of front matter. Added Language Sensitivity to some attributes. 2312 Removed resource descriptions from terminology. Some juggling of 2313 sections. See: 2314 http://www.imc.org/atom-protocol/mail-archive/msg01812.html. 2316 draft-ietf-atompub-protocol-04 - Add ladder diagrams, reorganize, add 2317 SOAP interactions 2319 draft-ietf-atompub-protocol-03 - Incorporates PaceSliceAndDice3 and 2320 PaceIntrospection. 2322 draft-ietf-atompub-protocol-02 - Incorporates Pace409Response, 2323 PacePostLocationMust, and PaceSimpleResourcePosting. 2325 draft-ietf-atompub-protocol-01 - Added in sections on Responses for 2326 the EditURI. Allow 2xx for response to EditURI PUTs. Elided all 2327 mentions of WSSE. Started adding in some normative references. 2328 Added the section "Securing the Atom Protocol". Clarified that it is 2329 possible that the PostURI and FeedURI could be the same URI. Cleaned 2330 up descriptions for Response codes 400 and 500. 2332 Rev draft-ietf-atompub-protocol-00 - 5Jul2004 - Renamed the file and 2333 re-titled the document to conform to IETF submission guidelines. 2334 Changed MIME type to match the one selected for the Atom format. 2335 Numerous typographical fixes. We used to have two 'Introduction' 2336 sections. One of them was moved into the Abstract the other absorbed 2337 the Scope section. IPR and copyright notifications were added. 2339 Rev 09 - 10Dec2003 - Added the section on SOAP enabled clients and 2340 servers. 2342 Rev 08 - 01Dec2003 - Refactored the specification, merging the 2343 Introspection file into the feed format. Also dropped the 2344 distinction between the type of URI used to create new entries and 2345 the kind used to create comments. Dropped user preferences. 2347 Rev 07 - 06Aug2003 - Removed the use of the RSD file for auto- 2348 discovery. Changed copyright until a final standards body is chosen. 2349 Changed query parameters for the search facet to all begin with atom- 2350 to avoid name collisions. Updated all the Entries to follow the 0.2 2351 version. Changed the format of the search results and template file 2352 to a pure element based syntax. 2354 Rev 06 - 24Jul2003 - Moved to PUT for updating Entries. Changed all 2355 the mime-types to application/x.atom+xml. Added template editing. 2356 Changed 'edit-entry' to 'create-entry' in the Introspection file to 2357 more accurately reflect its purpose. 2359 Rev 05 - 17Jul2003 - Renamed everything Echo into Atom. Added 2360 version numbers in the Revision history. Changed all the mime-types 2361 to application/atom+xml. 2363 Rev 04 - 15Jul2003 - Updated the RSD version used from 0.7 to 1.0. 2365 Change the method of deleting an Entry from POSTing to 2366 using the HTTP DELETE verb. Also changed the query interface to GET 2367 instead of POST. Moved Introspection Discovery to be up under 2368 Introspection. Introduced the term 'facet' for the services listed 2369 in the Introspection file. 2371 Rev 03 - 10Jul2003 - Added a link to the Wiki near the front of the 2372 document. Added a section on finding an Entry. Retrieving an Entry 2373 now broken out into its own section. Changed the HTTP status code 2374 for a successful editing of an Entry to 205. 2376 Rev 02 - 7Jul2003 - Entries are no longer returned from POSTs, 2377 instead they are retrieved via GET. Cleaned up figure titles, as 2378 they are rendered poorly in HTML. All content-types have been 2379 changed to application/atom+xml. 2381 Rev 01 - 5Jul2003 - Renamed from EchoAPI.html to follow the more 2382 commonly used format: draft-gregorio-NN.html. Renamed all references 2383 to URL to URI. Broke out introspection into its own section. Added 2384 the Revision History section. Added more to the warning that the 2385 example URIs are not normative. 2387 Authors' Addresses 2389 Joe Gregorio (editor) 2390 IBM 2391 4205 South Miama Blvd. 2392 Research Triangle Park, NC 27709 2393 US 2395 Phone: +1 919 272 3764 2396 Email: joe@bitworking.org 2397 URI: http://ibm.com/ 2399 Bill de hOra (editor) 2400 Propylon Ltd. 2401 45 Blackbourne Square, Rathfarnham Gate 2402 Dublin, Dublin D14 2403 IE 2405 Phone: +353-1-4927444 2406 Email: bill.dehora@propylon.com 2407 URI: http://www.propylon.com/ 2409 Full Copyright Statement 2411 Copyright (C) The IETF Trust (2007). 2413 This document is subject to the rights, licenses and restrictions 2414 contained in BCP 78, and except as set forth therein, the authors 2415 retain all their rights. 2417 This document and the information contained herein are provided on an 2418 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2419 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 2420 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 2421 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 2422 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2423 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2425 Intellectual Property 2427 The IETF takes no position regarding the validity or scope of any 2428 Intellectual Property Rights or other rights that might be claimed to 2429 pertain to the implementation or use of the technology described in 2430 this document or the extent to which any license under such rights 2431 might or might not be available; nor does it represent that it has 2432 made any independent effort to identify any such rights. Information 2433 on the procedures with respect to rights in RFC documents can be 2434 found in BCP 78 and BCP 79. 2436 Copies of IPR disclosures made to the IETF Secretariat and any 2437 assurances of licenses to be made available, or the result of an 2438 attempt made to obtain a general license or permission for the use of 2439 such proprietary rights by implementers or users of this 2440 specification can be obtained from the IETF on-line IPR repository at 2441 http://www.ietf.org/ipr. 2443 The IETF invites any interested party to bring to its attention any 2444 copyrights, patents or patent applications, or other proprietary 2445 rights that may cover technology that may be required to implement 2446 this standard. Please address the information to the IETF at 2447 ietf-ipr@ietf.org. 2449 Acknowledgment 2451 Funding for the RFC Editor function is provided by the IETF 2452 Administrative Support Activity (IASA).