idnits 2.17.1 draft-ietf-atompub-protocol-15.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 2512. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2523. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2530. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2536. 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 ([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 == Line 1349 has weird spacing: '...tml:img alt="...' -- 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 (May 22, 2007) is 6182 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'REC-xml' -- Possible downref: Non-RFC (?) normative reference: ref. 'REC-xml-infoset' -- Possible downref: Non-RFC (?) normative reference: ref. 'REC-xml-names' -- Possible downref: Non-RFC (?) normative reference: ref. 'REC-xmlbase' -- Possible downref: Non-RFC (?) normative reference: ref. 'REC-xmldsig-core' -- Possible downref: Non-RFC (?) normative reference: ref. 'REC-xmlenc-core' ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838) ** Obsolete normative reference: RFC 4346 (Obsoleted by RFC 5246) Summary: 9 errors (**), 0 flaws (~~), 2 warnings (==), 14 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: November 23, 2007 Propylon Ltd. 6 May 22, 2007 8 The Atom Publishing Protocol 9 draft-ietf-atompub-protocol-15.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 November 23, 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. 47 Editorial Note 49 [[anchor1: Remove this section upon publication]] 51 To provide feedback on this Internet-Draft, join the atom-protocol 52 mailing list (http://www.imc.org/atom-protocol/index.html) [1]. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 6 57 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 7 58 2.1. XML-related Conventions . . . . . . . . . . . . . . . . . 7 59 2.1.1. Referring to Information Items . . . . . . . . . . . . 7 60 2.1.2. RELAX NG Schema . . . . . . . . . . . . . . . . . . . 7 61 2.1.3. Use of xml:base and xml:lang . . . . . . . . . . . . . 7 62 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 4. Protocol Model . . . . . . . . . . . . . . . . . . . . . . . . 10 64 4.1. Identity and Naming . . . . . . . . . . . . . . . . . . . 10 65 4.2. Documents and Resource classification . . . . . . . . . . 10 66 4.3. Control and Publishing . . . . . . . . . . . . . . . . . . 12 67 4.4. Client Implementation Considerations . . . . . . . . . . . 12 68 5. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 14 69 5.1. Retrieving a Service Document . . . . . . . . . . . . . . 14 70 5.2. Listing Collection Members . . . . . . . . . . . . . . . . 14 71 5.3. Creating a Resource . . . . . . . . . . . . . . . . . . . 15 72 5.4. Editing a Resource . . . . . . . . . . . . . . . . . . . . 15 73 5.4.1. Retrieving a Resource . . . . . . . . . . . . . . . . 15 74 5.4.2. Editing a Resource . . . . . . . . . . . . . . . . . . 16 75 5.4.3. Deleting a Resource . . . . . . . . . . . . . . . . . 16 76 5.5. Use of HTTP Response codes . . . . . . . . . . . . . . . . 16 77 6. Protocol Documents . . . . . . . . . . . . . . . . . . . . . . 18 78 6.1. Document Types . . . . . . . . . . . . . . . . . . . . . . 18 79 6.2. Document Extensibility . . . . . . . . . . . . . . . . . . 18 80 7. Category Documents . . . . . . . . . . . . . . . . . . . . . . 20 81 7.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 20 82 7.2. Element Definitions . . . . . . . . . . . . . . . . . . . 20 83 7.2.1. The "app:categories" element . . . . . . . . . . . . . 20 84 8. Service Documents . . . . . . . . . . . . . . . . . . . . . . 22 85 8.1. Workspaces . . . . . . . . . . . . . . . . . . . . . . . . 22 86 8.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 23 87 8.3. Element Definitions . . . . . . . . . . . . . . . . . . . 24 88 8.3.1. The "app:service" Element . . . . . . . . . . . . . . 24 89 8.3.2. The "app:workspace" Element . . . . . . . . . . . . . 24 90 8.3.3. The "app:collection" Element . . . . . . . . . . . . . 25 91 8.3.4. The "app:accept" Element . . . . . . . . . . . . . . . 26 92 8.3.5. Usage in Atom Feed Documents . . . . . . . . . . . . . 26 93 8.3.6. The "app:categories" Element . . . . . . . . . . . . . 26 95 9. Creating and Editing Resources . . . . . . . . . . . . . . . . 28 96 9.1. Member URIs . . . . . . . . . . . . . . . . . . . . . . . 28 97 9.2. Creating Resources with POST . . . . . . . . . . . . . . . 28 98 9.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 29 99 9.3. Editing Resources with PUT . . . . . . . . . . . . . . . . 30 100 9.4. Deleting Resources with DELETE . . . . . . . . . . . . . . 30 101 9.5. Caching and entity tags . . . . . . . . . . . . . . . . . 30 102 9.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 30 103 9.6. Media Resources and Media Link Entries . . . . . . . . . . 32 104 9.6.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 33 105 9.7. The Slug: Header . . . . . . . . . . . . . . . . . . . . . 39 106 9.7.1. Slug: Header syntax . . . . . . . . . . . . . . . . . 40 107 9.7.2. Example . . . . . . . . . . . . . . . . . . . . . . . 40 108 10. Listing Collections . . . . . . . . . . . . . . . . . . . . . 41 109 10.1. Collection partial lists . . . . . . . . . . . . . . . . . 41 110 10.2. The "app:edited" Element . . . . . . . . . . . . . . . . . 42 111 11. Atom Format Link Relation Extensions . . . . . . . . . . . . . 43 112 11.1. The "edit" Link Relation . . . . . . . . . . . . . . . . . 43 113 11.2. The "edit-media" Link Relation . . . . . . . . . . . . . . 43 114 12. The Atom Format Type Parameter . . . . . . . . . . . . . . . . 44 115 12.1. The 'type' parameter . . . . . . . . . . . . . . . . . . . 44 116 12.1.1. Conformance . . . . . . . . . . . . . . . . . . . . . 44 117 13. Atom Publishing Controls . . . . . . . . . . . . . . . . . . . 45 118 13.1. The "app:control" Element . . . . . . . . . . . . . . . . 45 119 13.1.1. The "app:draft" Element . . . . . . . . . . . . . . . 45 120 14. Securing the Atom Publishing Protocol . . . . . . . . . . . . 46 121 15. Security Considerations . . . . . . . . . . . . . . . . . . . 47 122 15.1. Denial of Service . . . . . . . . . . . . . . . . . . . . 47 123 15.2. Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 47 124 15.3. Spoofing Attacks . . . . . . . . . . . . . . . . . . . . . 47 125 15.4. Linked Resources . . . . . . . . . . . . . . . . . . . . . 47 126 15.5. Digital Signatures and Encryption . . . . . . . . . . . . 47 127 15.6. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 47 128 15.7. Code Injection and Cross Site Scripting . . . . . . . . . 48 129 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49 130 16.1. Content-type registration for 'application/atomcat+xml' . 49 131 16.2. Content-type registration for 'application/atomsvc+xml' . 50 132 16.3. Header field registration for 'SLUG' . . . . . . . . . . . 51 133 16.4. The Link Relation registration "edit" . . . . . . . . . . 52 134 16.5. The Link Relation registration "edit-media" . . . . . . . 52 135 16.6. The Atom Format Media Type Parameter . . . . . . . . . . . 52 136 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 53 137 17.1. Normative References . . . . . . . . . . . . . . . . . . . 53 138 17.2. Informative References . . . . . . . . . . . . . . . . . . 54 139 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 56 140 Appendix B. RELAX NG Compact Schema . . . . . . . . . . . . . . . 57 141 Appendix C. Revision History . . . . . . . . . . . . . . . . . . 63 142 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 67 143 Intellectual Property and Copyright Statements . . . . . . . . . . 68 145 1. Introduction 147 The Atom Publishing Protocol is an application-level protocol for 148 publishing and editing Web Resources using HTTP [RFC2616] and XML 1.0 149 [REC-xml]. The protocol supports the creation of Web Resources and 150 provides facilities for: 152 o Collections: Sets of Resources, which can be retrieved in whole or 153 in part. 155 o Services: Discovery and description of Collections. 157 o Editing: Creating, editing, and deleting Resources. 159 The Atom Publishing Protocol is different from many contemporary 160 protocols in that the server is given wide latitude in processing 161 requests from clients. See Section 4.4 for more details. 163 2. Notational Conventions 165 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 166 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 167 document are to be interpreted as described in [RFC2119]. 169 2.1. XML-related Conventions 171 2.1.1. Referring to Information Items 173 Atom Protocol Document formats are specified in terms of the XML 174 Information Set [REC-xml-infoset], serialized as XML 1.0 [REC-xml]. 176 The Infoset terms "Element Information Item" and "Attribute 177 Information Item" are shortened to "element" and "attribute" 178 respectively. Therefore, when this specification uses the term 179 "element", it is referring to an Element Information Item, and when 180 it uses the term "attribute", it is referring to an Attribute 181 Information Item. 183 2.1.2. RELAX NG Schema 185 Some sections of this specification are illustrated with fragments of 186 a non-normative RELAX NG Compact schema [RNC]. However, the text of 187 this specification provides the definition of conformance. Complete 188 schemas appear in Appendix B. 190 2.1.3. Use of xml:base and xml:lang 192 XML elements defined by this specification MAY have an xml:base 193 attribute [REC-xmlbase]. When xml:base is used, it serves the 194 function described in Section 5.1.1 of URI Generic Syntax [RFC3986], 195 by establishing the base URI (or IRI) for resolving relative 196 references found within the scope of the xml:base attribute. 198 Any element defined by this specification MAY have an xml:lang 199 attribute, whose content indicates the natural language for the 200 element and its descendents. Requirements regarding the content and 201 interpretation of xml:lang are specified in Section 2.12 of XML 1.0 202 [REC-xml]. 204 3. Terminology 206 For convenience, this protocol can be referred to as the "Atom 207 Protocol" or "APP". The following terminology is used by this 208 specification: 210 o URI - A Uniform Resource Identifier as defined in [RFC3986]. In 211 this specification the phrase "the URI of a document" is shorthand 212 for "a URI which, when dereferenced, is expected to produce that 213 document as a representation". 215 o IRI - An Internationalized Resource Identifier as defined in 216 [RFC3987]. Before an IRI found in a document is used by HTTP, the 217 IRI is first converted to a URI. See Section 4.1. 219 o Resource - A network-accessible data object or service identified 220 by an IRI, as defined in [RFC2616]. See [REC-webarch] for further 221 discussion on Resources. 223 o relation (or "relation of") - Refers to the "rel" attribute value 224 of an atom:link element. 226 o Representation - An entity included with a request or response as 227 defined in [RFC2616]. 229 o Collection - A Resource that contains a set of Member Resources. 230 Collections are represented as Atom Feeds. See Section 9. 232 o Member (or Member Resource) - A Resource whose IRI is listed in a 233 Collection by an atom:link element with a relation of "edit" or 234 "edit-media". See Section 9.1. The protocol defines two kinds of 235 Members: 237 * Entry Resource - Members of a Collection that are represented 238 as Atom Entry Documents, as defined in [RFC4287]. 240 * Media Resource - Members of a Collection that have 241 representations other than Atom Entry Documents. 243 o Media Link Entry - an Entry Resource that contains metadata about 244 a Media Resource. See Section 9.6. 246 o Workspace - A named group of Collections. See Section 8.1. 248 o Service Document - A document that describes the location and 249 capabilities of one or more Collections, grouped into Workspaces. 250 See Section 8. 252 o Category Document - A document that describes the categories 253 allowed in a Collection. See Section 7. 255 4. Protocol Model 257 The Atom Protocol specifies operations for publishing and editing 258 Resources using HTTP. It uses Atom-formatted representations to 259 describe the state and metadata of those Resources. It defines how 260 Collections of Resources can be organized, and specifies formats to 261 support their discovery, grouping and categorization. 263 4.1. Identity and Naming 265 Atom Protocol documents allow the use of IRIs [RFC3987], as well as 266 URIs [RFC3986] to identify Resources. Before an IRI in a document is 267 used by HTTP, the IRI is first converted to a URI according to the 268 procedure defined in Section 3.1 of [RFC3987]. In accordance with 269 that specification, the conversion SHOULD be applied as late as 270 possible. Conversion does not imply Resource creation - the IRI and 271 the URI into which it is converted identify the same Resource. 273 While the Atom Protocol specifies the formats of the representations 274 that are exchanged and the actions that can be performed on the IRIs 275 embedded in those representations, it does not constrain the form of 276 the URIs that are used. HTTP [RFC2616] specifies that the URI space 277 of each server is controlled by that server, and this protocol 278 imposes no further constraints on that control. 280 4.2. Documents and Resource classification 282 A Resource whose IRI is listed in a Collection is called a Member 283 Resource. The protocol defines two kinds of Member Resources - Entry 284 Resources and Media Resources. Entry Resources are represented as 285 Atom Entry Documents [RFC4287]. Media Resources can have 286 representations in any media type. A Media Resource is described 287 within a Collection using an Entry called a Media Link Entry. This 288 diagram shows the classification of Resources within the Atom 289 Protocol: 291 Member Resources 292 | 293 ----------------- 294 | | 295 Entry Resources Media Resources 296 | 297 Media Link Entry 299 The Atom Protocol defines Collection Resources for managing and 300 organizing both kinds of Member Resource. A Collection is 301 represented by an Atom Feed Document. A Collection Feed's Entries 302 contain the IRIs of, and metadata about, the Collection's Member 303 Resources. A Collection Feed can contain any number of Entries, 304 which might represent all the Members of the Collection, or an 305 ordered subset of them (see Section 10.1). In the diagram of a 306 Collection below, there are two Entries. The first contains the IRI 307 of an Entry Resource. The second contains the IRIs of both a Media 308 Resource and a Media Link Entry Resource, which contains the metadata 309 for that Media Resource: 311 Collection 312 | 313 o- Entry 314 | | 315 | o- Member Entry IRI (Entry Resource) 316 | 317 o- Entry 318 | 319 o- Member Entry IRI (Media Link Entry) 320 | 321 o- Media IRI (Media Resource) 323 The Atom Protocol does not make a distinction between Feeds used for 324 Collections and other Atom Feeds. The only mechanism that this 325 specification supplies for indicating a Feed is a Collection Feed is 326 the presence of its IRI in a Service Document. 328 Service Documents represent server-defined groups of Collections, and 329 are used to initialize the process of creating and editing Resources. 330 These groups of Collections are called Workspaces. Workspaces have 331 names, but no IRIs, and no specified processing model. The Service 332 Document can indicate which media types, and which categories, a 333 Collection will accept. In the diagram below, there are two 334 Workspaces each describing the IRIs, acceptable media types, and 335 categories for a Collection: 337 Service 338 o- Workspace 339 | | 340 | o- Collection 341 | | 342 | o- IRI, categories, mediatypes 343 | 344 o- Workspace 345 | 346 o- Collection 347 | 348 o- IRI, categories, mediatypes 350 4.3. Control and Publishing 352 The Atom Publishing Protocol uses HTTP methods to author Member 353 Resources as follows: 355 o GET is used to retrieve a representation of a known Resource. 357 o POST is used to create a new, dynamically-named, Resource. When 358 the client submits non-Atom-Entry representations to a Collection 359 for creation, two Resources are always created - a Media Entry for 360 the requested Resource, and a Media Link Entry for metadata about 361 the Resource that will appear in the Collection. 363 o PUT is used to edit a known Resource. It is not used for Resource 364 creation. 366 o DELETE is used to remove a known Resource. 368 The Atom Protocol only covers the creating, editing, and deleting of 369 Entry and Media Resources. Other Resources could be created, edited 370 and deleted as the result of manipulating a Collection, but the 371 number of those Resources, their media-types, and effects of Atom 372 Protocol operations on them are outside the scope of this 373 specification. 375 Since all aspects of client-server interaction are defined in terms 376 of HTTP, [RFC2616] should be consulted for any areas not covered in 377 this specification. 379 4.4. Client Implementation Considerations 381 The Atom Protocol imposes few restrictions on the actions of servers. 382 Unless a constraint is specified here, servers can be expected to 383 vary in behavior, in particular around the manipulation of Atom 384 Entries sent by clients. For example, although this specification 385 only defines the expected behavior of Collections with respect to GET 386 and POST, this does not imply that PUT, DELETE, PROPPATCH and others 387 are forbidden on Collection Resources - only that this specification 388 does not define what the server's response would be to those methods. 389 Similarly while some HTTP status codes are mentioned explicitly, 390 clients ought to be prepared to handle any status code from a server. 391 Servers can choose to accept, reject, delay, moderate, censor, 392 reformat, translate, relocate or re-categorize the content submitted 393 to them. Only some of these choices are immediately relayed back to 394 the client in responses to client requests; other choices may only 395 become apparent later, in the feed or published entries. The same 396 series of requests to two different publishing sites can result in a 397 different series of HTTP responses, different resulting feeds or 398 different entry contents. 400 As a result, client software has to be written flexibly to accept 401 what the server decides are the results of its submissions. Any 402 server response or server content modification not explicitly 403 forbidden by this specification or HTTP [RFC2616] is therefore 404 allowed. 406 5. Protocol Operations 408 While specific HTTP status codes are shown in the interaction 409 diagrams below, an APP client should be prepared to handle any status 410 code. For example, a PUT to a Member URI could result in the return 411 of a "204 No Content" status code, which still indicates success. 413 5.1. Retrieving a Service Document 415 Client Server 416 | | 417 | 1.) GET to Service Document URI | 418 |------------------------------------------>| 419 | | 420 | 2.) 200 Ok | 421 | Service Document | 422 |<------------------------------------------| 423 | | 425 1. The client sends a GET request to the URI of the Service 426 Document. 428 2. The server responds with a Service Document enumerating the IRIs 429 of a group of Collections and the capabilities of those 430 Collections supported by the server. The content of this 431 document can vary based on aspects of the client request, 432 including, but not limited to, authentication credentials. 434 5.2. Listing Collection Members 436 To list the members of a Collection, the client sends a GET request 437 to the URI of a Collection. An Atom Feed Document is returned whose 438 Entries contain the IRIs of Member Resources. The returned Feed may 439 describe all, or only a partial list, of the Members in a Collection 440 (see Section 10). 442 Client Server 443 | | 444 | 1.) GET to Collection URI | 445 |------------------------------->| 446 | | 447 | 2.) 200 Ok | 448 | Atom Feed | 449 |<-------------------------------| 450 | | 452 1. The client sends a GET request to the URI of the Collection. 454 2. The server responds with an Atom Feed Document containing the 455 IRIs of the Collection Members. 457 5.3. Creating a Resource 459 Client Server 460 | | 461 | 1.) POST to Collection URI | 462 | Member Representation | 463 |------------------------------------------>| 464 | | 465 | 2.) 201 Created | 466 | Location: Member Entry URI | 467 |<------------------------------------------| 468 | | 470 1. The client POSTs a representation of the Member to the URI of the 471 Collection. 473 2. If the Member Resource was created successfully, the server 474 responds with a status code of 201 and a Location: header that 475 contains the IRI of the newly created Entry Resource. Media 476 Resources could have also been created and their IRIs can be 477 found through the Entry Resource. See Section 9.6 for more 478 details. 480 5.4. Editing a Resource 482 Once a Resource has been created and its Member URI is known, that 483 URI can be used to retrieve, edit, and delete the Resource. 484 Section 11 describes extensions to the Atom Syndication Format used 485 in the Atom Protocol for editing purposes. 487 5.4.1. Retrieving a Resource 489 Client Server 490 | | 491 | 1.) GET to Member URI | 492 |------------------------------------------>| 493 | | 494 | 2.) 200 Ok | 495 | Member Representation | 496 |<------------------------------------------| 497 | | 499 1. The client sends a GET request to the URI of a Member Resource to 500 retrieve its representation. 502 2. The server responds with the representation of the Member 503 Resource. 505 5.4.2. Editing a Resource 507 Client Server 508 | | 509 | 1.) PUT to Member URI | 510 | Member Representation | 511 |------------------------------------------>| 512 | | 513 | 2.) 200 OK | 514 |<------------------------------------------| 516 1. The client sends a PUT request to store a representation of a 517 Member Resource. 519 2. If the request is successful, the server responds with a status 520 code of 200. 522 5.4.3. Deleting a Resource 524 Client Server 525 | | 526 | 1.) DELETE to Member URI | 527 |------------------------------------------>| 528 | | 529 | 2.) 200 OK | 530 |<------------------------------------------| 531 | | 533 1. The client sends a DELETE request to the URI of a Member 534 Resource. 536 2. If the deletion is successful the server responds with a status 537 code of 200. 539 A different approach is taken for deleting Media Resources; see 540 Section 9.6 for details. 542 5.5. Use of HTTP Response codes 544 The Atom Protocol uses the response status codes defined in HTTP to 545 indicate the success or failure of an operation. Consult the HTTP 546 specification [RFC2616] for detailed definitions of each status code. 548 Implementers are asked to note that according to the HTTP 549 specification, HTTP 4xx and 5xx response entities SHOULD include a 550 human-readable explanation of the error. 552 6. Protocol Documents 554 6.1. Document Types 556 This specification defines two kinds of documents - Category 557 Documents and Service Documents. 559 A Category Document (Section 7) contains lists of categories 560 specified using the "atom:category" element from the Atom Syndication 561 Format (see Section 4.2.2 of [RFC4287]). 563 A Service Document (Section 8) groups available Collections into 564 Workspaces. 566 The namespace name [REC-xml-names] for either kind of document is: 568 http://purl.org/atom/app# 570 [[anchor9: The namespace name 'http://purl.org/atom/app#' needs to be 571 updated throughout the document with the final URI upon publication]] 573 Atom Publishing Protocol XML Documents MUST be "namespace-well- 574 formed" as specified in Section 7 of [REC-xml-names]. 576 This specification uses the prefix "app:" for the namespace name. 577 The prefix "atom:" is used for "http://www.w3.org/2005/Atom", the 578 namespace name of the Atom Syndication Format [RFC4287]. These 579 namespace prefixes are not semantically significant. 581 This specification does not define any DTDs for Atom Protocol 582 formats, and hence does not require them to be "valid" in the sense 583 used by [REC-xml]. 585 6.2. Document Extensibility 587 Unrecognized markup in an Atom Publishing Protocol document is 588 considered "foreign markup" as defined in Section 6 of the Atom 589 Syndication Format [RFC4287]. Foreign markup can be used anywhere 590 within a Category or Service Document unless it is explicitly 591 forbidden. Processors that encounter foreign markup MUST NOT stop 592 processing and MUST NOT signal an error. Clients SHOULD preserve 593 foreign markup when transmitting such documents. 595 The namespace name "http://purl.org/atom/app#" is reserved for 596 forward compatible revisions of the Category and Service Document 597 types - this does not exclude the addition of elements and attributes 598 that might not be recognized by processors conformant to this 599 specification. Such unrecognized markup from the 600 "http://purl.org/atom/app#" namespace MUST be treated as foreign 601 markup. 603 7. Category Documents 605 Category Documents contain lists of categories described using the 606 "atom:category" element from the Atom Syndication Format [RFC4287]. 607 Categories can also appear in Service Documents, where they indicate 608 the categories allowed in a Collection (see Section 8.3.6). 610 Category Documents are identified with the "application/atomcat+xml" 611 media type (see Section 16.1). 613 7.1. Example 615 616 620 621 622 623 625 This Category Document contains atom:category elements, with the 626 terms 'animal', 'vegetable', and 'mineral'. None of the categories 627 use the "label" attribute defined in [RFC4287]. They all inherit the 628 "http://example.com/cats/big3" "scheme" attribute declared on the 629 app:categories element. Therefore if the 'mineral' category were to 630 appear in an Atom Entry or Feed Document, it would appear as: 632 634 7.2. Element Definitions 636 7.2.1. The "app:categories" element 638 The root of a Category Document is the "app:categories" element. An 639 app:categories element can contain zero or more "atom:category" 640 elements from the Atom Syndication Format [RFC4287] namespace 641 ("http://www.w3.org/2005/Atom"). 643 An atom:category child element that has no "scheme" attribute 644 inherits the attribute from its app:categories parent. An atom: 645 category child element with an existing "scheme" attribute does not 646 inherit the "scheme" value of its "app:categories" parent element. 648 atomCategory = 649 element atom:category { 650 atomCommonAttributes, 651 attribute term { text }, 652 attribute scheme { atomURI }?, 653 attribute label { text }?, 654 undefinedContent 655 } 657 appInlineCategories = 658 element app:categories { 659 attribute fixed { "yes" | "no" }?, 660 attribute scheme { atomURI }?, 661 (atomCategory*, 662 undefinedContent) 663 } 665 appOutOfLineCategories = 666 element app:categories { 667 attribute href { atomURI }, 668 undefinedContent 669 } 671 appCategories = appInlineCategories | appOutOfLineCategories 673 7.2.1.1. Attributes of "app:categories" 675 The app:categories element can contain a "fixed" attribute, with a 676 value of either "yes" or "no", indicating whether the list of 677 categories is a fixed or an open set. The absence of the "fixed" 678 attribute is equivalent to the presence of a "fixed" attribute with a 679 value of "no". 681 Alternatively, the app:categories element MAY contain an "href" 682 attribute, whose value MUST be an IRI reference identifying a 683 Category Document. If the "href" attribute is provided, the app: 684 categories element MUST be empty and MUST NOT have the "fixed" or 685 "scheme" attributes. 687 8. Service Documents 689 For authoring to commence, a client needs to discover the 690 capabilities and locations of the available Collections. Service 691 Documents are designed to support this discovery process. 693 How Service Documents are discovered is not defined in this 694 specification. 696 Service Documents are identified with the "application/atomsvc+xml" 697 media type (see Section 16.2). 699 8.1. Workspaces 701 A Service Document groups Collections into Workspaces. Operations on 702 Workspaces, such as creation or deletion, are not defined by this 703 specification. This specification assigns no meaning to Workspaces; 704 that is, a Workspace does not imply any specific processing 705 assumptions. 707 There is no requirement that a server support multiple Workspaces. 708 In addition, a Collection MAY appear in more than one Workspace. 710 8.2. Example 712 713 715 716 Main Site 717 719 My Blog Entries 720 722 723 725 Pictures 726 image/png 727 image/jpeg 728 image/gif 729 730 731 732 Sidebar Blog 733 735 Remaindered Links 736 application/atom+xml;type=entry 737 738 741 744 745 746 747 749 The Service Document above describes two Workspaces. The first 750 Workspace is called "Main Site", and has two Collections called "My 751 Blog Entries" and "Pictures", whose IRIs are 752 "http://example.org/blog/main" and "http://example.org/blog/pic" 753 respectively. The "Pictures" Collection includes three "accept" 754 elements indicating the types of image files the client can send to 755 the Collection to create new Media Resources (entries associated with 756 Media Resources are discussed in Section 9.6). 758 The second Workspace is called "Sidebar Blog" and has a single 759 Collection called "Remaindered Links" whose IRI is 760 "http://example.org/sidebar/list". The Collection has an "accept" 761 element whose content is "application/atom+xml;type=entry", 762 indicating it will accept Atom Entries from a client. 764 Within each of the two Entry Collections, the "categories" element 765 provides a list of available categories for Member Entries. In the 766 "My Blog Entries" Collection, the list of available categories is 767 available through the "href" attribute. The "Sidebar Blog" 768 Collection provides a category list within the Service Document, but 769 states the list is fixed, signaling a request from the server that 770 Entries be POSTed using only those two categories. 772 8.3. Element Definitions 774 8.3.1. The "app:service" Element 776 The root of a Service Document is the "app:service" element. 778 The app:service element is the container for service information 779 associated with one or more Workspaces. An app:service element MUST 780 contain one or more app:workspace elements. 782 namespace app = "http://purl.org/atom/app#" 783 start = appService 785 appService = 786 element app:service { 787 appCommonAttributes, 788 ( appWorkspace+ 789 & extensionElement* ) 790 } 792 8.3.2. The "app:workspace" Element 794 Workspaces are server-defined groups of Collections. The "app: 795 workspace" element contains zero or more app:collection elements 796 describing the Collections of Resources available for editing. 798 appWorkspace = 799 element app:workspace { 800 appCommonAttributes, 801 ( atomTitle 802 & appCollection* 803 & extensionSansTitleElement* ) 804 } 806 atomTitle = element atom:title { atomTextConstruct } 808 8.3.2.1. The "atom:title" Element 810 The app:workspace element MUST contain one "atom:title" element (as 811 defined in [RFC4287]), giving a human-readable title for the 812 Workspace. 814 8.3.3. The "app:collection" Element 816 The "app:collection" element describes a Collection. The app: 817 collection Element MUST contain one "atom:title" element. 819 The app:collection element MAY contain any number of app:accept 820 elements, indicating the types of representations accepted by the 821 Collection. The order of such elements is not significant. 823 The app:collection element MAY contain any number of app:categories 824 elements. 826 appCollection = 827 element app:collection { 828 appCommonAttributes, 829 attribute href { atomURI }, 830 ( atomTitle 831 & appAccept* 832 & appCategories* 833 & extensionSansTitleElement* ) 834 } 836 8.3.3.1. The "href" Attribute 838 The app:collection element MUST contain an "href" attribute, whose 839 value gives the IRI of the Collection. 841 8.3.3.2. The "atom:title" Element 843 The "atom:title" element is defined in [RFC4287], and gives a human- 844 readable title for the Collection. 846 8.3.4. The "app:accept" Element 848 The content of an "app:accept" element value is a media-range as 849 defined in [RFC2616]. The media range specifies a type of 850 representation that can be POSTed to a Collection. 852 The app:accept element is similar to the HTTP Accept request-header 853 [RFC2616]. Media type parameters are allowed within app:accept, but 854 app:accept has no notion of preference - "accept-params" or "q" 855 arguments, as specified in Section 14.1 of [RFC2616] are not 856 significant. 858 White space (as defined in [REC-xml]) around the app:accept element's 859 media-range is insignificant and MUST be ignored. 861 A value of "application/atom+xml;type=entry" MAY appear in any app: 862 accept list of media-ranges and indicates that Atom Entry Documents 863 can be POSTed to the Collection. If no app:accept element is 864 present, clients SHOULD treat this as equivalent to an app:accept 865 element with the content "application/atom+xml;type=entry". 867 If one accept element exists and is empty, clients SHOULD assume that 868 the Collection does not support the creation of new Entries. 870 appAccept = 871 element app:accept { 872 appCommonAttributes, 873 ( text? ) 874 } 876 8.3.5. Usage in Atom Feed Documents 878 The app:collection element MAY appear as a child of an atom:feed or 879 atom:source element in an Atom Feed Document. Its content identifies 880 a Collection by which new Entries can be added to appear in the feed. 881 When it appears in an atom:feed or atom:source element, the app: 882 collection element is considered foreign markup as defined in Section 883 6 of [RFC4287]. 885 8.3.6. The "app:categories" Element 887 The "app:categories" element provides a list of the categories that 888 can be applied to the members of a Collection. See Section 7.2.1 for 889 the detailed definition of app:categories. 891 The server MAY reject attempts to create or store members whose 892 categories are not present in it's categories list. Collections that 893 indicate the category set is open SHOULD NOT reject otherwise 894 acceptable members whose categories are not in its categories list. 895 The absence of an "app:categories" element means that the category 896 handling of the Collection is unspecified. A "fixed" category list 897 that contains zero categories indicates the Collection does not 898 accept category data. 900 9. Creating and Editing Resources 902 9.1. Member URIs 904 The Member URI allows clients to retrieve, edit and delete a Member 905 Resource using HTTP's GET, PUT and DELETE methods. Entry Resources 906 are represented as Atom Entry documents. 908 Member URIs appear in two places. They are returned in a Location 909 header after successful Resource creation using POST, as described in 910 Section 9.2 below. They can also appear in a Collection Feed's 911 entries, as atom:link elements with a link relation of "edit". 913 A Member Entry SHOULD contain such an atom:link element with a link 914 relation of "edit", which indicates the Member URI. 916 9.2. Creating Resources with POST 918 To add members to a Collection, clients send POST requests to the URI 919 of the Collection. 921 Successful member creation is indicated with a 201 ("Created") 922 response code. When the Collection responds with a status code of 923 201, it SHOULD also return a response body, which MUST be an Atom 924 Entry Document representing the newly-created Resource. Since the 925 server is free to alter the POSTed Entry, for example by changing the 926 content of the atom:id element, returning the Entry can be useful to 927 the client, enabling it to correlate the client and server views of 928 the new Entry. 930 When a Member Resource is created, its Member Entry URI MUST be 931 returned in a Location header in the Collection's response. 933 If the creation request contained an Atom Entry Document, and the 934 subsequent response from the server contains a Content-Location 935 header that matches the Location header character-for-character, then 936 the client is authorized to interpret the response entity as being a 937 complete representation of the newly created Entry. Without a 938 matching Content-Location header, the client MUST NOT assume the 939 returned entity is a complete representation of the created Resource. 941 The request body sent with the POST need not be an Atom Entry. For 942 example, it might be a picture, or a movie. Collections MAY return a 943 response with a status code of 415 ("Unsupported Media Type") to 944 indicate that the media-type of the POSTed entity is not allowed or 945 supported by the Collection. For a discussion of the issues in 946 creating such content, see Section 9.6. 948 9.2.1. Example 950 Below, the client sends a POST request containing an Atom Entry 951 representation using the URI of the Collection: 953 POST /edit/ HTTP/1.1 954 Host: example.org 955 User-Agent: Thingio/1.0 956 Authorization: Basic ZGFmZnk6c2VjZXJldA== 957 Content-Type: application/atom+xml;type=entry 958 Content-Length: nnn 959 Slug: First Post 961 962 963 Atom-Powered Robots Run Amok 964 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 965 2003-12-13T18:30:02Z 966 John Doe 967 Some text. 968 970 The server signals a successful creation with a status code of 201. 971 The response includes a Location: header indicating the Member Entry 972 URI of the Atom Entry, and a representation of that Entry in the body 973 of the response. 975 HTTP/1.1 201 Created 976 Date: Fri, 7 Oct 2005 17:17:11 GMT 977 Content-Length: nnn 978 Content-Type: application/atom+xml;type=entry;charset="utf-8" 979 Location: http://example.org/edit/first-post.atom 980 ETag: "c180de84f991g8" 982 983 984 Atom-Powered Robots Run Amok 985 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 986 2003-12-13T18:30:02Z 987 John Doe 988 Some text. 989 991 993 The Entry created and returned by the Collection might not match the 994 Entry POSTed by the client. A server MAY change the values of 995 various elements in the Entry, such as the atom:id, atom:updated and 996 atom:author values, and MAY choose to remove or add other elements 997 and attributes, or change element content and attribute values. 999 9.3. Editing Resources with PUT 1001 To edit a Member Resource, clients send PUT requests to its Member 1002 URI, as specified in [RFC2616]. 1004 To avoid unintentional loss of data when editing Member Entries or 1005 Media Link Entries, Atom Protocol clients SHOULD preserve all 1006 metadata that has not been intentionally modified, including unknown 1007 foreign markup as defined in Section 6 of [RFC4287]. 1009 9.4. Deleting Resources with DELETE 1011 To delete a Member Resource, clients send a DELETE request to its 1012 Member URI, as specified in [RFC2616]. The deletion of a Media Link 1013 Entry SHOULD result in the deletion of the corresponding Media 1014 Resource. 1016 9.5. Caching and entity tags 1018 Implementers are advised to pay attention to cache controls, and to 1019 make use of the mechanisms available in HTTP when editing Resources, 1020 in particular entity-tags as outlined in [NOTE-detect-lost-update]. 1021 Clients are not assured to receive the most recent representations of 1022 Collection Members using GET if the server is authorizing 1023 intermediaries to cache them. 1025 9.5.1. Example 1027 Below, the client creates a Member Entry using POST: 1029 POST /myblog/entries HTTP/1.1 1030 Host: example.org 1031 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1032 Content-Type: application/atom+xml;type=entry 1033 Content-Length: nnn 1034 Slug: First Post 1036 1037 1038 Atom-Powered Robots Run Amok 1039 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 1040 2007-02-123T17:09:02Z 1041 Captain Lansing 1042 It's something moving... solid metal 1043 1045 The server signals a successful creation with a status code of 201, 1046 and returns an ETag header in the response. Because, in this case, 1047 the server returned a Content-Location and Location header with the 1048 same value, the returned Entry representation can be understood to be 1049 a complete representation of the newly created Entry (see 1050 Section 9.2). 1052 HTTP/1.1 201 Created 1053 Date: Fri, 23 Feb 2007 21:17:11 GMT 1054 Content-Length: nnn 1055 Content-Type: application/atom+xml;type=entry 1056 Location: http://example.org/edit/first-post.atom 1057 Content-Location: http://example.org/edit/first-post.atom 1058 ETag: "e180ee84f0671b1" 1060 1061 1062 Atom-Powered Robots Run Amok 1063 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 1064 2007-02-123T17:09:02Z 1065 Captain Lansing 1066 It's something moving... solid metal 1067 1069 The client can, if it wishes, use the returned ETag value to later 1070 construct a "Conditional GET" as defined in [RFC2616]. In this case, 1071 prior to editing, the client sends the ETag value for the Member 1072 using the If-None-Match: header. 1074 GET /edit/first-post.atom HTTP/1.1 1075 Host: example.org 1076 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1077 If-None-Match: "e180ee84f0671b1" 1079 If the Entry has not been modified, the response will be a status 1080 code of 304 (Not Modified). This allows the client to determine it 1081 still has the most recent representation of the Entry at the time of 1082 editing. 1084 HTTP/1.1 304 Not Modified 1085 Date: Sat, 24 Feb 2007 13:17:11 GMT 1087 After editing, the client can PUT the Entry and send the ETag entity 1088 value in an If-Match header, informing the server to accept the entry 1089 on the condition the entity value sent still matches the server's. 1091 PUT /edit/first-post.atom HTTP/1.1 1092 Host: example.org 1093 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1094 Content-Type: application/atom+xml;type=entry 1095 Content-Length: nnn 1096 If-Match: "e180ee84f0671b1" 1098 1099 1100 Atom-Powered Robots Run Amok 1101 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 1102 2007-02-24T16:34:06Z 1103 Captain Lansing 1104 Update: it's a hoax! 1105 1107 The server however has since received a more recent copy than the 1108 client's, and responds with a status code of 412 (Precondition 1109 Failed). 1111 HTTP/1.1 412 Precondition Failed 1112 Date: Sat, 24 Feb 2007 16:34:11 GMT 1114 This informs the client that the server has a more recent version of 1115 the Entry and will not allow the sent entity to be stored. 1117 9.6. Media Resources and Media Link Entries 1119 A client can POST Media Resources as well as Entry Resources to a 1120 Collection. If a server accepts such a request, then it MUST create 1121 two new Resources - one that corresponds to the entity sent in the 1122 request, called the Media Resource, and an associated Member Entry, 1123 called the Media Link Entry. Media Link Entries are represented as 1124 Atom Entries, and appear in the Collection. 1126 The Media Link Entry contains the metadata and IRI of the (perhaps 1127 non-textual) Media Resource. The Media Link Entry thus makes the 1128 metadata about the Media Resource separately available for retrieval 1129 and alteration. 1131 The server can signal the media types it will accept using the app: 1132 accept element in the Service Document, as specified in 1133 Section 8.3.4. 1135 Successful responses to creation requests MUST include the URI of the 1136 Media Link Entry in the Location header. The Media Link Entry SHOULD 1137 contain an atom:link element with a link relation of "edit-media" 1138 that contains the Media Resource IRI. The Media Link Entry MUST have 1139 an atom:content element with a "src" attribute. The value of the 1140 "src" attribute is an IRI for the newly created Media Resource. It 1141 is OPTIONAL that the IRI of the "src" attribute on the atom:content 1142 element be the same as the Media Resource IRI. For example, the 1143 "src" attribute value might instead be a link into a static cache or 1144 content distribution network and not the Media Resource IRI. 1146 Implementers are asked to note that [RFC4287] specifies that Atom 1147 Entries MUST contain an atom:summary element. Thus, upon successful 1148 creation of a Media Link Entry, a server MAY choose to populate the 1149 atom:summary element (as well as any other required elements such as 1150 atom:id, atom:author and atom:title) with content derived from the 1151 POSTed entity or from any other source. A server might not allow a 1152 client to modify the server selected values for these elements. 1154 For Resource creation this specification only defines cases where the 1155 POST body has an Atom Entry entity declared as an Atom media type 1156 ("application/atom+xml"), or a non-Atom entity declared as a non-Atom 1157 media type. When a client is POSTing an Atom Entry to a collection, 1158 it may use a media-type of either "application/atom+xml" or 1159 "application/atom +xml;type=entry". This specification does not 1160 specify any request semantics or server behavior in the case where 1161 the POSTed media-type is "application/atom+xml" but the body is 1162 something other than an Atom Entry. In particular, what happens on 1163 POSTing an Atom Feed Document to a Collection using the "application/ 1164 atom+xml" media type is undefined. 1166 The Atom Protocol does not specify a means to create multiple 1167 representations of the same Resource (for example a PNG and a JPG of 1168 the same image) either on creation or editing. 1170 9.6.1. Examples 1172 Below, the client sends a POST request containing a PNG image to the 1173 URI of a Collection that accepts PNG images: 1175 POST /edit/ HTTP/1.1 1176 Host: media.example.org 1177 Content-Type: image/png 1178 Slug: The Beach 1179 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1180 Content-Length: nnn 1182 ...binary data... 1184 The server signals a successful creation with a status code of 201. 1185 The response includes a Location header indicating the Member URI of 1186 the Media Link Entry and a representation of that entry in the body 1187 of the response. The Media Link Entry includes a content element 1188 with a src attribute. It also contains a link with a link relation 1189 of "edit-media", specifying the IRI to be used for modifying the 1190 Media Resource. 1192 HTTP/1.1 201 Created 1193 Date: Fri, 7 Oct 2005 17:17:11 GMT 1194 Content-Length: nnn 1195 Content-Type: application/atom+xml;type=entry;charset="utf-8" 1196 Location: http://example.org/media/edit/the_beach.atom 1198 1199 1200 The Beach 1201 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 1202 2005-10-07T17:17:08Z 1203 Daffy 1204 1205 1207 1209 1211 1213 Later, the client sends a PUT request containing the new PNG using 1214 the URI indicated in the Media Link Entry's "edit-media" link: 1216 PUT /edit/the_beach.png HTTP/1.1 1217 Host: media.example.org 1218 Content-Type: image/png 1219 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1220 Content-Length: nnn 1222 ...binary data... 1224 The server signals a successful edit with a status code of 200. 1226 HTTP/1.1 200 Ok 1227 Date: Fri, 8 Oct 2006 17:17:11 GMT 1229 The client can edit the metadata for the picture. First GET the 1230 Media Link Entry: 1232 GET /media/edit/the_beach.atom HTTP/1.1 1233 Host: example.org 1234 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1236 The Media Link Entry is returned. 1238 HTTP/1.1 200 Ok 1239 Date: Fri, 7 Oct 2005 17:18:11 GMT 1240 Content-Length: nnn 1241 Content-Type: application/atom+xml;type=entry;charset="utf-8" 1242 ETag: "c181bb840673b5" 1244 1245 1246 The Beach 1247 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 1248 2005-10-07T17:17:08Z 1249 Daffy 1250 1251 1253 1255 1257 1259 The metadata can be updated, in this case to add a summary, and then 1260 PUT back to the server. 1262 PUT /media/edit/the_beach.atom HTTP/1.1 1263 Host: example.org 1264 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1265 Content-Type: application/atom+xml;type=entry 1266 Content-Length: nnn 1267 If-Match: "c181bb840673b5" 1269 1270 1271 The Beach 1272 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 1273 2005-10-07T17:17:08Z 1274 Daffy 1275 1276 A nice sunset picture over the water. 1277 1278 1280 1282 1284 1286 The update was successful. 1288 HTTP/1.1 200 Ok 1289 Date: Fri, 7 Oct 2005 17:19:11 GMT 1290 Content-Length: 0 1292 Multiple media Resources can be added to the Collection. 1294 POST /edit/ HTTP/1.1 1295 Host: media.example.org 1296 Content-Type: image/png 1297 Slug: The Pier 1298 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1299 Content-Length: nnn 1301 ...binary data... 1303 The Resource is created successfully. 1305 HTTP/1.1 201 Created 1306 Date: Fri, 7 Oct 2005 17:17:11 GMT 1307 Content-Length: nnn 1308 Content-Type: application/atom+xml;type=entry;charset="utf-8" 1309 Location: http://example.org/media/edit/the_pier.atom 1311 1312 1313 The Pier 1314 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efe6b 1315 2005-10-07T17:26:43Z 1316 Daffy 1317 1318 1320 1322 1324 1326 The client can now create a new Atom Entry in the blog Entry 1327 Collection that references the two newly created Media Resources. 1329 POST /blog/ HTTP/1.1 1330 Host: example.org 1331 Content-Type: application/atom+xml;type=entry 1332 Slug: A day at the beach 1333 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1334 Content-Length: nnn 1336 1337 1338 A fun day at the beach 1339 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6b 1340 2005-10-07T17:40:02Z 1341 Daffy 1342 1343 1344 We had a good day at the beach. 1345 1347 1348 Later we walked down to the pier. 1349 1351 1352 1353 1354 1356 The Resource is created successfully. 1358 HTTP/1.1 200 Ok 1359 Date: Fri, 7 Oct 2005 17:20:11 GMT 1360 Content-Length: nnn 1361 Content-Type: application/atom+xml;type=entry;charset="utf-8" 1362 Location: http://example.org/blog/atom/a-day-at-the-beach.atom 1364 1365 1366 A fun day at the beach 1367 http://example.org/blog/a-day-at-the-beach.xhtml 1368 2005-10-07T17:43:07Z 1369 Daffy 1370 1371 1372 We had a good day at the beach. 1373 1375 1376 Later we walked down to the pier. 1377 1379 1380 1381 1382 1384 1386 1388 Note that the returned Entry contains a link with a relation of 1389 "alternate" that points to the associated HTML page that was created. 1390 This is not required by this specification, but is included to show 1391 the kinds of changes a server can make to an Entry. 1393 9.7. The Slug: Header 1395 Slug is an HTTP entity-header whose presence in a POST to a 1396 Collection constitutes a request by the client to use the header's 1397 value as part of any URIs that would normally used to retrieve the 1398 to-be-created Entry or Media resources. 1400 Servers MAY use the value of the Slug header when creating the Member 1401 URI of the newly-created Resource, for instance, by using some or all 1402 of the words in the value for the last URI segment. Servers MAY also 1403 use the value when creating the atom:id, or as the title of a Media 1404 Link Entry (see Section 9.6.). 1406 Servers MAY choose to ignore the Slug entity-header. Servers MAY 1407 alter the header value before using it. For instance, a server might 1408 filter out some characters or replace accented letters with non- 1409 accented ones, replace spaces with underscores, change case, and so 1410 on. 1412 9.7.1. Slug: Header syntax 1414 The syntax of this header MUST conform to the augmented BNF grammar 1415 in section 2.1 of the HTTP/1.1 specification [RFC2616]. The TEXT 1416 rule is described in section 2.2 of the same document. 1418 Slug = "Slug" ":" *TEXT 1420 The field-value of the Slug header is a percent-encoded utf-8 Unicode 1421 string that does not contain CR or LF, where CR and LF are defined in 1422 [RFC2616]. All non-ASCII characters in the utf-8 representation MUST 1423 be percent-encoded according to the rules in Section 2.1 of 1424 [RFC3986]. 1426 9.7.2. Example 1428 Here is an example of the Slug: header that uses percent-encoding to 1429 represent the Unicode character U+00E8 (LATIN SMALL LETTER E WITH 1430 GRAVE): 1432 POST /myblog/entries HTTP/1.1 1433 Host: example.org 1434 Content-Type: image/png 1435 Slug: The Beach at S%C3%A8te 1436 Authorization: Basic ZGFmZnk6c2VjZXJldA== 1437 Content-Length: nnn 1439 ...binary data... 1441 See Section 9.2.1 for an example of the Slug: header applied to the 1442 creation of an Entry Resource. 1444 10. Listing Collections 1446 Collection Resources MUST provide representations in the form of Atom 1447 Feed documents whose Entries contain the IRIs of the Members in the 1448 Collection. No distinction is made between Collection Feeds and 1449 other kinds of Feeds - a Feed might act both as a 'public' feed for 1450 subscription purposes and as a Collection Feed. 1452 Each Entry in the Feed Document SHOULD have an atom:link element with 1453 a relation of "edit" (See Section 11.1). 1455 The Entries in the returned Atom Feed SHOULD be ordered by their 1456 "app:edited" property, with the most recently edited Entries coming 1457 first in the document order. The app:edited value is not equivalent 1458 to the HTTP Last-Modified: header and cannot be used to determine the 1459 freshness of cached responses. 1461 Clients MUST NOT assume that an Atom Entry returned in the Feed is a 1462 full representation of an Entry Resource and SHOULD perform a GET on 1463 the URI of the Member Entry before editing it. See Section 9.5 for a 1464 discussion on the implications of cache control directives when 1465 obtaining entries. 1467 10.1. Collection partial lists 1469 Collections can contain large numbers of Resources. A client such as 1470 a web spider or web browser might be overwhelmed if the response to a 1471 GET contained every Entry in a Collection - in turn the server might 1472 also waste bandwidth and processing time on generating a response 1473 that cannot be handled. For this reason, servers MAY respond to 1474 Collection GET requests with a Feed Document containing a partial 1475 list of the Collection's members, and a link to the next partial list 1476 feed, if it exists. The first such partial list returned MUST 1477 contain the most recently edited member Resources and MUST have an 1478 atom:link with a "next" relation whose "href" value is the URI of the 1479 next partial list of the Collection. This next partial list will 1480 contain the next most recently edited set of Member Resources (and an 1481 atom:link to the following partial list if it exists). 1483 In addition to the "next" relation, partial list feeds MAY contain 1484 link elements with "rel" attribute values of "previous", "first", and 1485 "last", that can be used to navigate through the complete set of 1486 entries in the Collection. 1488 For instance, suppose a client is supplied the URI 1489 "http://example.org/entries/go" of a Collection of Member entries, 1490 where the server as a matter of policy avoids generating feed 1491 documents containing more than 10 Entries. The Atom Feed Document 1492 for the Collection will then represent the first partial list of a 1493 set of 10 linked feed documents. The "first" relation will reference 1494 the initial Feed Document in the set and the "last" relation 1495 references the final Feed Document in the set. Within each document, 1496 the "next" and "previous" link relations reference the preceding and 1497 subsequent documents. 1499 1500 1502 1504 1506 ... 1507 1509 The "next" and "previous" link elements for the partial list feed 1510 located at "http://example.org/entries/2" would look like this: 1512 1513 1515 1517 1519 1521 ... 1522 1524 10.2. The "app:edited" Element 1526 The "app:edited" element is a Date construct (as defined by 1527 [RFC4287]), whose content indicates the last time an Entry was 1528 edited. If the entry has not been edited yet, the content indicates 1529 the time it was created. Atom Entry elements in Collection documents 1530 SHOULD contain one "app:edited" element, and MUST NOT contain more 1531 than one. 1533 appEdited = element app:edited ( atomDateConstruct ) 1535 The server SHOULD change the value of this element every time an 1536 Entry Resource or an associated Media Resource has been edited. 1538 11. Atom Format Link Relation Extensions 1540 11.1. The "edit" Link Relation 1542 This specification adds the value "edit" to the Atom Registry of Link 1543 Relations (see section 7.1 of [RFC4287]). The value of "edit" 1544 specifies that the value of the href attribute is the IRI of an 1545 editable Member Entry. When appearing within an atom:entry, the href 1546 IRI can be used to retrieve, update and delete the Resource 1547 represented by that Entry. An atom:entry MUST NOT contain more than 1548 one "edit" link relation. 1550 11.2. The "edit-media" Link Relation 1552 This specification adds the value "edit-media" to the Atom Registry 1553 of Link Relations (see section 7.1 of [RFC4287]). When appearing 1554 within an atom:entry, the value of the href attribute is an IRI that 1555 can be used to modify a Media Resource associated with that Entry. 1557 An atom:entry element MAY contain zero or more "edit-media" link 1558 relations. An atom:entry MUST NOT contain more than one atom:link 1559 element with a rel attribute value of "edit-media" that has the same 1560 "type" and "hreflang" attribute values. All "edit-media" link 1561 relations in the same Entry reference the same Resource. If a client 1562 encounters multiple "edit-media" link relations in an Entry then it 1563 SHOULD choose a link based on the client preferences for "type" and 1564 "hreflang". If a client encounters multiple "edit-media" link 1565 relations in an Entry and has no preference based on the "type" and 1566 "hreflang" attributes then the client SHOULD pick the first "edit- 1567 media" link relation in document order. 1569 12. The Atom Format Type Parameter 1571 The Atom Syndication Format [RFC4287] defines the "application/ 1572 atom+xml" media type to identify both Atom Feed and Atom Entry 1573 Documents. Implementation experience has demonstrated that Atom Feed 1574 and Entry Documents can have different processing models and that 1575 there are situations where they need to be differentiated. This 1576 document defines an optional "type" parameter used to differentiate 1577 the two types of Atom documents. 1579 12.1. The 'type' parameter 1581 This document defines a new "type" parameter for use with the 1582 "application/atom+xml" media type. The "type" parameter has a value 1583 of "entry" or "feed". 1585 Neither the parameter name nor its value are case sensitive. 1587 The value "entry" indicates that the media type identifies an Atom 1588 Entry Document. The root element of the document MUST be atom:entry. 1590 The value "feed" indicates that the media type identifies an Atom 1591 Feed Document. The root element of the document MUST be atom:feed. 1593 If not specified, the type is assumed to be unspecified, requiring 1594 Atom processors to examine the root element to determine the type of 1595 Atom document. 1597 12.1.1. Conformance 1599 New specifications MAY require that the "type" parameter be used to 1600 identify the Atom Document type. Producers of Atom Entry Documents 1601 SHOULD use the "type" parameter regardless of whether or not it is 1602 required. Producers of Atom Feed Documents MAY use the parameter. 1604 Atom processors that do not recognize the "type" parameter MUST 1605 ignore its value and examine the root element to determine the 1606 document type. 1608 Atom processors that do recognize the "type" parameter SHOULD detect 1609 and report inconsistencies between the parameter's value and the 1610 actual type of the document's root element. 1612 13. Atom Publishing Controls 1614 This specification defines an Atom Format Structured Extension, as 1615 defined in Section 6 of [RFC4287], for publishing control within the 1616 "http://purl.org/atom/app#" namespace. 1618 13.1. The "app:control" Element 1620 namespace app = "http://purl.org/atom/app#" 1622 pubControl = 1623 element app:control { 1624 atomCommonAttributes, 1625 pubDraft? 1626 & extensionElement 1627 } 1629 pubDraft = 1630 element app:draft { "yes" | "no" } 1632 The "app:control" element MAY appear as a child of an atom:entry that 1633 is being created or updated via the Atom Publishing Protocol. The 1634 app:control element MUST appear only once in an Entry. The app: 1635 control element is considered foreign markup as defined in Section 6 1636 of [RFC4287]. 1638 The app:control element and its child elements MAY be included in 1639 Atom Feed or Entry Documents. 1641 The app:control element can contain an optional "app:draft" element 1642 as defined below, and can contain extension elements as defined in 1643 Section 6 of [RFC4287]. 1645 13.1.1. The "app:draft" Element 1647 The inclusion of the "app:draft" element represents a request by the 1648 client to control the visibility of a Member Resource. Server 1649 support is optional and thus the app:draft element MAY be ignored by 1650 the server. 1652 The number of app:draft elements in app:control MUST be zero or one. 1653 The content of an app:draft element MUST be one of "yes" or "no". If 1654 the element contains "no" this indicates a client request that the 1655 Member Resource be made publicly visible. If the app:draft element 1656 is not present then servers that support the extension MUST behave as 1657 though an app:draft element containing "no" was sent. 1659 14. Securing the Atom Publishing Protocol 1661 The Atom Publishing Protocol is based on HTTP. Authentication 1662 requirements for HTTP are covered in Section 11 of [RFC2616]. 1664 The use of authentication mechanisms to prevent POSTing or editing by 1665 unknown or unauthorized clients is RECOMMENDED but not required. 1666 When authentication is not used, clients and servers are vulnerable 1667 to trivial spoofing, denial of service, and defacement attacks. 1668 However, in some contexts, this is an acceptable risk. 1670 The type of authentication deployed is a local decision made by the 1671 server operator. Clients are likely to face authentication schemes 1672 that vary across server deployments. At a minimum, client and server 1673 implementations MUST be capable of being configured to use HTTP Basic 1674 Authentication [RFC2617] in conjunction with a TLS [RFC2246] 1675 connection as defined in [RFC2818] (but note that [RFC2246] has been 1676 superseded by [RFC4346]). See [RFC4346] for more information on TLS. 1678 The choice of authentication mechanism will impact interoperability. 1679 The minimum level of security referenced above (Basic Authentication 1680 with TLS) is considered good practice for Internet applications at 1681 the time of publication of this specification and sufficient for 1682 establishing a baseline for interoperability. Implementers are 1683 encouraged to investigate and use alternative mechanisms regarded as 1684 equivalently good or better at the time of deployment. It is 1685 RECOMMENDED that clients be implemented in such a way that new 1686 authentication schemes can be deployed. 1688 Because this protocol uses HTTP response status codes as the primary 1689 means of reporting the result of a request, servers are advised to 1690 respond to unauthorized or unauthenticated requests using an 1691 appropriate 4xx HTTP response code (e.g. 401 "Unauthorized" or 403 1692 "Forbidden") in accordance with [RFC2617]. 1694 15. Security Considerations 1696 The Atom Publishing Protocol is based on HTTP and thus subject to the 1697 security considerations found in Section 15 of [RFC2616]. 1699 15.1. Denial of Service 1701 Atom Publishing Protocol server implementations need to take adequate 1702 precautions to ensure malicious clients cannot consume excessive 1703 server resources (CPU, memory, disk, etc). 1705 15.2. Replay Attacks 1707 Atom Publishing Protocol server implementations are susceptible to 1708 replay attacks. Specifically, this specification does not define a 1709 means of detecting duplicate requests. Accidentally sent duplicate 1710 requests are indistinguishable from intentional and malicious replay 1711 attacks. 1713 15.3. Spoofing Attacks 1715 Atom Publishing Protocol implementations are susceptible to a variety 1716 of spoofing attacks. Malicious clients may send Atom Entries 1717 containing inaccurate information anywhere in the document. 1719 15.4. Linked Resources 1721 Atom Feed and Entry documents can contain XML External Entities as 1722 defined in Section 4.2.2 of [REC-xml]. Atom implementations are not 1723 required to load external entities. External entities are subject to 1724 the same security concerns as any network operation and can alter the 1725 semantics of an Atom document. The same issues exist for Resources 1726 linked to by Atom elements such as atom:link and atom:content. 1728 15.5. Digital Signatures and Encryption 1730 Atom Entry Documents sent to a server might contain XML Digital 1731 Signatures [REC-xmldsig-core] and might be encrypted using XML 1732 Encryption [REC-xmlenc-core] as specified in Section 5 of [RFC4287]. 1734 Servers are allowed to modify received Resource representations in 1735 ways that can invalidate signatures covering those representations. 1737 15.6. URIs and IRIs 1739 Atom Publishing Protocol implementations handle URIs and IRIs. See 1740 Section 7 of [RFC3986] and Section 8 of [RFC3987] for security 1741 considerations related to their handling and use. 1743 15.7. Code Injection and Cross Site Scripting 1745 Atom Feed and Entry documents can contain a broad range of content 1746 types including code that might be executable in some contexts. 1747 Malicious clients could attempt to attack servers or other clients by 1748 injecting code into a Collection Document's Entry or Media Resources. 1750 Server implementations are strongly encouraged to verify that client 1751 supplied content is safe prior to accepting, processing or publishing 1752 it. In the case of HTML, experience indicates that verification 1753 based on a white list of acceptable content is more effective than a 1754 black list of forbidden content. 1756 Additional information about XHTML and HTML content safety can be 1757 found in Section 8.1 of [RFC4287] 1759 16. IANA Considerations 1761 This document uses two new media types that conform to the registry 1762 mechanism described in [RFC4288], a new message header that conforms 1763 to the registry mechanism described in [RFC3864], and two new link 1764 relations that conform to the registry mechanism described in 1765 [RFC4287]. 1767 16.1. Content-type registration for 'application/atomcat+xml' 1769 An Atom Publishing Protocol Category Document, when serialized as XML 1770 1.0, can be identified with the following media type: 1772 MIME media type name: application 1774 MIME subtype name: atomcat+xml 1776 Mandatory parameters: None. 1778 Optional parameters: 1780 "charset": This parameter has identical semantics to the charset 1781 parameter of the "application/xml" media type as specified in 1782 [RFC3023]. 1784 Encoding considerations: Identical to those of "application/xml" as 1785 described in [RFC3023], section 3.2. 1787 Security considerations: As defined in this specification. 1788 [[anchor31: update upon publication]] 1790 In addition, as this media type uses the "+xml" convention, it 1791 shares the same security considerations as described in [RFC3023], 1792 section 10. 1794 Interoperability considerations: There are no known interoperability 1795 issues. 1797 Published specification: This specification. [[anchor32: update upon 1798 publication]] 1800 Applications that use this media type: No known applications 1801 currently use this media type. 1803 Additional information: 1805 Magic number(s): As specified for "application/xml" in [RFC3023], 1806 section 3.2. 1808 File extension: .atomcat 1810 Fragment identifiers: As specified for "application/xml" in 1811 [RFC3023], section 5. 1813 Base URI: As specified in [RFC3023], section 6. 1815 Macintosh File Type code: TEXT 1817 Person and email address to contact for further information: Joe 1818 Gregorio 1820 Intended usage: COMMON 1822 Author/Change controller: This specification's author(s). 1823 [[anchor33: update upon publication]] 1825 16.2. Content-type registration for 'application/atomsvc+xml' 1827 An Atom Publishing Protocol Service Document, when serialized as XML 1828 1.0, can be identified with the following media type: 1830 MIME media type name: application 1832 MIME subtype name: atomsvc+xml 1834 Mandatory parameters: None. 1836 Optional parameters: 1838 "charset": This parameter has identical semantics to the charset 1839 parameter of the "application/xml" media type as specified in 1840 [RFC3023]. 1842 Encoding considerations: Identical to those of "application/xml" as 1843 described in [RFC3023], section 3.2. 1845 Security considerations: As defined in this specification. 1846 [[anchor34: update upon publication]] 1848 In addition, as this media type uses the "+xml" convention, it 1849 shares the same security considerations as described in [RFC3023], 1850 section 10. 1852 Interoperability considerations: There are no known interoperability 1853 issues. 1855 Published specification: This specification. [[anchor35: update upon 1856 publication]] 1858 Applications that use this media type: No known applications 1859 currently use this media type. 1861 Additional information: 1863 Magic number(s): As specified for "application/xml" in [RFC3023], 1864 section 3.2. 1866 File extension: .atomsvc 1868 Fragment identifiers: As specified for "application/xml" in 1869 [RFC3023], section 5. 1871 Base URI: As specified in [RFC3023], section 6. 1873 Macintosh File Type code: TEXT 1875 Person and email address to contact for further information: Joe 1876 Gregorio 1878 Intended usage: COMMON 1880 Author/Change controller: This specification's author(s). 1881 [[anchor36: update upon publication]] 1883 16.3. Header field registration for 'SLUG' 1885 Header field: SLUG 1887 Applicable protocol: http [RFC2616] 1889 Status: standard. 1891 Author/Change controller: IETF (iesg@ietf.org) Internet Engineering 1892 Task Force 1894 Specification document(s): This specification. [[anchor37: update on 1895 rfc number assignment]]) 1897 Related information: 1899 16.4. The Link Relation registration "edit" 1901 Attribute Value: edit 1903 Description: An IRI of an editable Member Entry. When appearing 1904 within an atom:entry, the href IRI can be used to retrieve, update 1905 and delete the Resource represented by that Entry. 1907 Expected display characteristics: Undefined; this relation can be 1908 used for background processing or to provide extended 1909 functionality without displaying its value. 1911 Security considerations: Automated agents should take care when this 1912 relation crosses administrative domains (e.g., the URI has a 1913 different authority than the current document). 1915 16.5. The Link Relation registration "edit-media" 1917 Attribute Value: edit-media 1919 Description: An IRI of an editable Media Resource. When appearing 1920 within an atom:entry, the href IRI can be used to retrieve, update 1921 and delete the Media Resource associated with that Entry. 1923 Expected display characteristics: Undefined; this relation can be 1924 used for background processing or to provide extended 1925 functionality without displaying its value. 1927 Security considerations: Automated agents should take care when this 1928 relation crosses administrative domains (e.g., the URI has a 1929 different authority than the current document). 1931 16.6. The Atom Format Media Type Parameter 1933 IANA is requested to add a reference to this specification in the 1934 'application/atom+xml' media type registration. 1936 17. References 1938 17.1. Normative References 1940 [REC-xml] Yergeau, F., Paoli, J., Bray, T., Sperberg-McQueen, C., 1941 and E. Maler, "Extensible Markup Language (XML) 1.0 1942 (Fourth Edition)", World Wide Web Consortium 1943 Recommendation REC-xml-20060816, August 2006, 1944 . 1946 [REC-xml-infoset] 1947 Cowan, J. and R. Tobin, "XML Information Set (Second 1948 Edition)", World Wide Web Consortium Recommendation REC- 1949 xml-infoset-20040204, February 2004, 1950 . 1952 [REC-xml-names] 1953 Hollander, D., Bray, T., Tobin, R., and A. Layman, 1954 "Namespaces in XML 1.0 (Second Edition)", World Wide Web 1955 Consortium Recommendation REC-xml-names-20060816, 1956 August 2006, 1957 . 1959 [REC-xmlbase] 1960 Marsh, J., "XML Base", W3C REC W3C.REC-xmlbase-20010627, 1961 June 2001. 1963 [REC-xmldsig-core] 1964 Solo, D., Reagle, J., and D. Eastlake, "XML-Signature 1965 Syntax and Processing", World Wide Web Consortium 1966 Recommendation REC-xmldsig-core-20020212, February 2002, 1967 . 1969 [REC-xmlenc-core] 1970 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 1971 Processing", World Wide Web Consortium Recommendation REC- 1972 xmlenc-core-20021210, December 2002, 1973 . 1975 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1976 Requirement Levels", BCP 14, RFC 2119, March 1997. 1978 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 1979 RFC 2246, January 1999. 1981 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1982 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1983 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1985 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1986 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1987 Authentication: Basic and Digest Access Authentication", 1988 RFC 2617, June 1999. 1990 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1992 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 1993 Types", RFC 3023, January 2001. 1995 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1996 Procedures for Message Header Fields", BCP 90, RFC 3864, 1997 September 2004. 1999 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2000 Resource Identifier (URI): Generic Syntax", STD 66, 2001 RFC 3986, January 2005. 2003 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 2004 Identifiers (IRIs)", RFC 3987, January 2005. 2006 [RFC4287] Nottingham, M. and R. Sayre, "The Atom Syndication 2007 Format", RFC 4287, December 2005. 2009 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 2010 Registration Procedures", BCP 13, RFC 4288, December 2005. 2012 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 2013 (TLS) Protocol Version 1.1", RFC 4346, April 2006. 2015 17.2. Informative References 2017 [NOTE-detect-lost-update] 2018 Nielsen, H. and D. LaLiberte, "Editing the Web: Detecting 2019 the Lost Update Problem Using Unreserved Checkout", World 2020 Wide Web Consortium NOTE NOTE-detect-lost-update, 2021 May 1999, . 2023 [REC-webarch] 2024 Walsh, N. and I. Jacobs, "Architecture of the World Wide 2025 Web, Volume One", W3C REC REC-webarch-20041215, 2026 December 2004. 2028 [RNC] Clark, J., "RELAX NG Compact Syntax", December 2001, . 2032 URIs 2034 [1] 2036 Appendix A. Contributors 2038 The content and concepts within are a product of the Atom community 2039 and the Atompub Working Group. 2041 Appendix B. RELAX NG Compact Schema 2043 This appendix is informative. 2045 The Relax NG schema explicitly excludes elements in the Atom Protocol 2046 namespace which are not defined in this revision of the 2047 specification. Requirements for Atom Protocol processors 2048 encountering such markup are given in Section 6.2 and Section 6.3 of 2049 [RFC4287]. 2051 The Schema for Service Documents: 2053 # -*- rnc -*- 2054 # RELAX NG Compact Syntax Grammar for the Atom Protocol 2056 namespace app = "http://purl.org/atom/app#" 2057 namespace atom = "http://www.w3.org/2005/Atom" 2058 namespace xsd = "http://www.w3.org/2001/XMLSchema" 2059 namespace xhtml = "http://www.w3.org/1999/xhtml" 2060 namespace local = "" 2062 start = appService 2064 # common:attrs 2066 atomURI = text 2068 appCommonAttributes = 2069 attribute xml:base { atomURI }?, 2070 attribute xml:lang { atomLanguageTag }?, 2071 attribute xml:space {"default"|"preserved"}?, 2072 undefinedAttribute* 2074 atomCommonAttributes = appCommonAttributes 2076 undefinedAttribute = 2077 attribute * - (xml:base | xml:space | xml:lang | local:*) { text } 2079 atomLanguageTag = xsd:string { 2080 pattern = "([A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*)?" 2081 } 2083 atomDateConstruct = 2084 appCommonAttributes, 2085 xsd:dateTime 2087 # app:service 2088 appService = 2089 element app:service { 2090 appCommonAttributes, 2091 ( appWorkspace+ 2092 & extensionElement* ) 2093 } 2095 # app:workspace 2097 appWorkspace = 2098 element app:workspace { 2099 appCommonAttributes, 2100 ( atomTitle 2101 & appCollection* 2102 & extensionSansTitleElement* ) 2103 } 2105 atomTitle = element atom:title { atomTextConstruct } 2107 # app:collection 2109 appCollection = 2110 element app:collection { 2111 appCommonAttributes, 2112 attribute href { atomURI }, 2113 ( atomTitle 2114 & appAccept* 2115 & appCategories* 2116 & extensionSansTitleElement* ) 2117 } 2119 # app:categories 2121 atomCategory = 2122 element atom:category { 2123 atomCommonAttributes, 2124 attribute term { text }, 2125 attribute scheme { atomURI }?, 2126 attribute label { text }?, 2127 undefinedContent 2128 } 2130 appInlineCategories = 2131 element app:categories { 2132 attribute fixed { "yes" | "no" }?, 2133 attribute scheme { atomURI }?, 2134 (atomCategory*, 2135 undefinedContent) 2137 } 2139 appOutOfLineCategories = 2140 element app:categories { 2141 attribute href { atomURI }, 2142 undefinedContent 2143 } 2145 appCategories = appInlineCategories | appOutOfLineCategories 2147 # app:accept 2149 appAccept = 2150 element app:accept { 2151 appCommonAttributes, 2152 ( text? ) 2153 } 2155 # Simple Extension 2157 simpleSansTitleExtensionElement = 2158 element * - (app:*|atom:title) { 2159 text 2160 } 2162 simpleExtensionElement = 2163 element * - (app:*) { 2164 text 2165 } 2167 # Structured Extension 2169 structuredSansTitleExtensionElement = 2170 element * - (app:*|atom:title) { 2171 (attribute * { text }+, 2172 (text|anyElement)*) 2173 | (attribute * { text }*, 2174 (text?, anyElement+, (text|anyElement)*)) 2175 } 2177 structuredExtensionElement = 2178 element * - (app:*) { 2179 (attribute * { text }+, 2180 (text|anyElement)*) 2181 | (attribute * { text }*, 2182 (text?, anyElement+, (text|anyElement)*)) 2184 } 2186 # Other Extensibility 2188 extensionSansTitleElement = 2189 simpleSansTitleExtensionElement|structuredSansTitleExtensionElement 2191 extensionElement = 2192 simpleExtensionElement | structuredExtensionElement 2194 undefinedContent = (text|anyForeignElement)* 2196 # Extensions 2198 anyElement = 2199 element * { 2200 (attribute * { text } 2201 | text 2202 | anyElement)* 2203 } 2205 anyForeignElement = 2206 element * - app:* { 2207 (attribute * { text } 2208 | text 2209 | anyElement)* 2210 } 2212 atomPlainTextConstruct = 2213 atomCommonAttributes, 2214 attribute type { "text" | "html" }?, 2215 text 2217 atomXHTMLTextConstruct = 2218 atomCommonAttributes, 2219 attribute type { "xhtml" }, 2220 xhtmlDiv 2222 atomTextConstruct = atomPlainTextConstruct | atomXHTMLTextConstruct 2224 anyXHTML = element xhtml:* { 2225 (attribute * { text } 2226 | text 2227 | anyXHTML)* 2228 } 2230 xhtmlDiv = element xhtml:div { 2231 (attribute * { text } 2232 | text 2233 | anyXHTML)* 2234 } 2236 # EOF 2238 The Schema for Category Documents: 2240 # -*- rnc -*- 2241 # RELAX NG Compact Syntax Grammar for the Atom Protocol 2243 namespace app = "http://purl.org/atom/app#" 2244 namespace atom = "http://www.w3.org/2005/Atom" 2245 namespace xsd = "http://www.w3.org/2001/XMLSchema" 2246 namespace local = "" 2248 start = appCategories 2250 atomCommonAttributes = 2251 attribute xml:base { atomURI }?, 2252 attribute xml:lang { atomLanguageTag }?, 2253 undefinedAttribute* 2255 undefinedAttribute = 2256 attribute * - (xml:base | xml:lang | local:*) { text } 2258 atomURI = text 2260 atomLanguageTag = xsd:string { 2261 pattern = "([A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*)?" 2262 } 2264 atomCategory = 2265 element atom:category { 2266 atomCommonAttributes, 2267 attribute term { text }, 2268 attribute scheme { atomURI }?, 2269 attribute label { text }?, 2270 undefinedContent 2271 } 2273 appInlineCategories = 2274 element app:categories { 2275 attribute fixed { "yes" | "no" }?, 2276 attribute scheme { atomURI }?, 2277 (atomCategory*, 2278 undefinedContent) 2279 } 2281 appOutOfLineCategories = 2282 element app:categories { 2283 attribute href { atomURI }, 2284 (empty) 2285 } 2287 appCategories = appInlineCategories | appOutOfLineCategories 2289 # Extensibility 2291 undefinedContent = (text|anyForeignElement)* 2293 anyElement = 2294 element * { 2295 (attribute * { text } 2296 | text 2297 | anyElement)* 2298 } 2300 anyForeignElement = 2301 element * - atom:* { 2302 (attribute * { text } 2303 | text 2304 | anyElement)* 2305 } 2307 # EOF 2309 Appendix C. Revision History 2311 [[anchor42: This section to be removed upon publication.]] 2313 draft-ietf-atompub-protocol-14: typos; removed "The language context 2314 is only significant for elements and attributes declared to be 2315 "Language-Sensitive" by this specification. "; "Successful member 2316 creation is normally indicated with a 201 ("Created") response code." 2317 removed "normally" from that sentence (9.2); Added "Media Link 2318 Entries are represented as Atom Entries and appear in the 2319 Collection." to 9.6; said that an app:accept value of "entry" is 2320 equivalent to "application/atom+xml;type=entry"; double-check spec 2321 terms; Member Entry resource -> Entry Resource; Added MLE, Entry 2322 Resource and Media Resource terms defs; 6.1 para split; 10.1 2323 collection paging, rewrote for clarity; 13.1.1 app:edited rewrote for 2324 clarity/conflict; text for GETting entries and cache handling; 4: 2325 Typo: "And Media Resources IRIs", s/Resources/Resource/; consensus 2326 call: application/atomsvc+xml, extension is .atomsvc; DRY app: 2327 categories; make it clear the app:draft support is optional whether 2328 or not the value is sent; 9.2: put related ideas together into 2329 paragraphs.; 10: partial list editing; security: use elharos text; 2330 app:edited: tweak text suplied by ari; create a section for 2331 workspaces and move the descriptive text there; Moved rfc2818 to non- 2332 normative references. Added the W3C note on lost updates as a 2333 reference. 2335 draft-ietf-atompub-protocol-13: Added Lisa's verbiage. Folded in 2336 James' Atom Format media type 'type' parameter spec. Updated 2337 document references to be more consistent, added URLs to some, and 2338 shortened up their anchors. Debugged rnc. 2340 draft-ietf-atompub-protocol-11: Parts of PaceAppEdited. 2341 PaceSecurityConsiderationsRevised. 2343 draft-ietf-atompub-protocol-10: PaceRemoveTitleHeader2, 2344 PaceSlugHeader4, PaceOnlyMemberURI,PaceOneAppNamespaceOnly, 2345 PaceAppCategories, PaceExtendIntrospection, 2346 UseElementsForAppCollectionTitles3, renamed Introspection to Service, 2347 lots of good editorials suggestions, updated media example with slug, 2348 moved xml conventions to convention sections, renamed XMl related 2349 Conventions to Atom Publishing Protocol Documents, added auth header 2350 to examples, consolidated definition of all resource types into the 2351 model section, added IANA reg info for application/atomcat+xml. 2353 draft-ietf-atompub-protocol-09: PaceWorkspaceMayHaveCollections, 2354 PaceMediaEntries5, 2355 http://www.imc.org/atom-protocol/mail-archive/msg05322.html, and 2356 http://www.imc.org/atom-protocol/mail-archive/msg05272.html 2357 draft-ietf-atompub-protocol-08: added infoset ref; added wording re 2358 IRI/URI; fixed URI/IRI ; next/previous fixed as per Atom 2359 LinkRelations Attribute 2360 (http://www.imc.org/atom-protocol/mail-archive/msg04095.html); 2361 incorporated: PaceEditLinkMustToMay; PaceMissingDraftHasNoMeaning, 2362 PaceRemoveMemberTypeMust, PaceRemoveMemberTypePostMust, 2363 PaceTitleHeaderOnlyInMediaCollections, PacePreserveForeignMarkup, 2364 PaceClarifyTitleHeader, PaceClarifyMediaResourceLinks, 2365 PaceTwoPrimaryCollections; 2367 draft-ietf-atompub-protocol-07: updated Atom refs to RFC4287; 2368 incorporated PaceBetterHttpResponseCode; 2369 PaceClarifyCollectionAndDeleteMethodByWritingLessInsteadOfMore; 2370 PaceRemoveAcceptPostText; PaceRemoveListTemplate2; 2371 PaceRemoveRegistry; PaceRemoveWhoWritesWhat; 2372 PaceSimplifyClarifyBetterfyRemoveBogusValidityText; 2373 PaceCollectionOrderSignificance; PaceFixLostIntrospectionText; 2374 PaceListPaging; PaceCollectionControl; element typo in Listing 2375 collections para3 (was app:member-type, not app:list-template); 2376 changed post atom entry example to be valid. Dropped inline use of 2377 'APP'. Removed nested diagram from section 4. Added ed notes in the 2378 security section. 2380 draft-ietf-atompub-protocol-06 - Removed: Robert Sayre from the 2381 contributors section per his request. Added in 2382 PaceCollectionControl. Fixed all the {daterange} verbage and 2383 examples so they all use a dash. Added full rnc schema. Collapsed 2384 Introspection and Collection documents into a single document. 2385 Removed {dateRange} queries. Renamed search to list. Moved 2386 discussion of media and entry collection until later in the document 2387 and tied the discussion to the Introspection element app:member-type. 2389 draft-ietf-atompub-protocol-05 - Added: Contributors section. Added: 2390 de hOra to editors. Fixed: typos. Added diagrams and description to 2391 model section. Incorporates PaceAppDocuments, PaceAppDocuments2, 2392 PaceSimplifyCollections2 (large-sized chunks of it anyhow: the 2393 notions of Entry and Generic resources, the section 4 language on the 2394 Protocol Model, 4.1 through 4.5.2, the notion of a Collection 2395 document, as in Section 5 through 5.3, Section 7 "Collection 2396 resources", Selection resources (modified from pace which talked 2397 about search); results in major mods to Collection Documents, Section 2398 9.2 "Title: Header" and brokeout para to section 9.1 Editing Generic 2399 Resources). Added XML namespace and language section. Some cleanup 2400 of front matter. Added Language Sensitivity to some attributes. 2401 Removed resource descriptions from terminology. Some juggling of 2402 sections. See: 2403 http://www.imc.org/atom-protocol/mail-archive/msg01812.html. 2405 draft-ietf-atompub-protocol-04 - Add ladder diagrams, reorganize, add 2406 SOAP interactions 2408 draft-ietf-atompub-protocol-03 - Incorporates PaceSliceAndDice3 and 2409 PaceIntrospection. 2411 draft-ietf-atompub-protocol-02 - Incorporates Pace409Response, 2412 PacePostLocationMust, and PaceSimpleResourcePosting. 2414 draft-ietf-atompub-protocol-01 - Added in sections on Responses for 2415 the EditURI. Allow 2xx for response to EditURI PUTs. Elided all 2416 mentions of WSSE. Started adding in some normative references. 2417 Added the section "Securing the Atom Protocol". Clarified that it is 2418 possible that the PostURI and FeedURI could be the same URI. Cleaned 2419 up descriptions for Response codes 400 and 500. 2421 Rev draft-ietf-atompub-protocol-00 - 5Jul2004 - Renamed the file and 2422 re-titled the document to conform to IETF submission guidelines. 2423 Changed MIME type to match the one selected for the Atom format. 2424 Numerous typographical fixes. We used to have two 'Introduction' 2425 sections. One of them was moved into the Abstract the other absorbed 2426 the Scope section. IPR and copyright notifications were added. 2428 Rev 09 - 10Dec2003 - Added the section on SOAP enabled clients and 2429 servers. 2431 Rev 08 - 01Dec2003 - Refactored the specification, merging the 2432 Introspection file into the feed format. Also dropped the 2433 distinction between the type of URI used to create new entries and 2434 the kind used to create comments. Dropped user preferences. 2436 Rev 07 - 06Aug2003 - Removed the use of the RSD file for auto- 2437 discovery. Changed copyright until a final standards body is chosen. 2438 Changed query parameters for the search facet to all begin with atom- 2439 to avoid name collisions. Updated all the Entries to follow the 0.2 2440 version. Changed the format of the search results and template file 2441 to a pure element based syntax. 2443 Rev 06 - 24Jul2003 - Moved to PUT for updating Entries. Changed all 2444 the mime-types to application/x.atom+xml. Added template editing. 2445 Changed 'edit-entry' to 'create-entry' in the Introspection file to 2446 more accurately reflect its purpose. 2448 Rev 05 - 17Jul2003 - Renamed everything Echo into Atom. Added 2449 version numbers in the Revision history. Changed all the mime-types 2450 to application/atom+xml. 2452 Rev 04 - 15Jul2003 - Updated the RSD version used from 0.7 to 1.0. 2454 Change the method of deleting an Entry from POSTing to 2455 using the HTTP DELETE verb. Also changed the query interface to GET 2456 instead of POST. Moved Introspection Discovery to be up under 2457 Introspection. Introduced the term 'facet' for the services listed 2458 in the Introspection file. 2460 Rev 03 - 10Jul2003 - Added a link to the Wiki near the front of the 2461 document. Added a section on finding an Entry. Retrieving an Entry 2462 now broken out into its own section. Changed the HTTP status code 2463 for a successful editing of an Entry to 205. 2465 Rev 02 - 7Jul2003 - Entries are no longer returned from POSTs, 2466 instead they are retrieved via GET. Cleaned up figure titles, as 2467 they are rendered poorly in HTML. All content-types have been 2468 changed to application/atom+xml. 2470 Rev 01 - 5Jul2003 - Renamed from EchoAPI.html to follow the more 2471 commonly used format: draft-gregorio-NN.html. Renamed all references 2472 to URL to URI. Broke out introspection into its own section. Added 2473 the Revision History section. Added more to the warning that the 2474 example URIs are not normative. 2476 Authors' Addresses 2478 Joe Gregorio (editor) 2479 IBM 2480 4205 South Miama Blvd. 2481 Research Triangle Park, NC 27709 2482 US 2484 Phone: +1 919 272 3764 2485 Email: joe@bitworking.org 2486 URI: http://ibm.com/ 2488 Bill de hOra (editor) 2489 Propylon Ltd. 2490 45 Blackbourne Square, Rathfarnham Gate 2491 Dublin, Dublin D14 2492 IE 2494 Phone: +353-1-4927444 2495 Email: bill@dehora.net 2496 URI: http://www.propylon.com/ 2498 Full Copyright Statement 2500 Copyright (C) The IETF Trust (2007). 2502 This document is subject to the rights, licenses and restrictions 2503 contained in BCP 78, and except as set forth therein, the authors 2504 retain all their rights. 2506 This document and the information contained herein are provided on an 2507 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2508 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 2509 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 2510 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 2511 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2512 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2514 Intellectual Property 2516 The IETF takes no position regarding the validity or scope of any 2517 Intellectual Property Rights or other rights that might be claimed to 2518 pertain to the implementation or use of the technology described in 2519 this document or the extent to which any license under such rights 2520 might or might not be available; nor does it represent that it has 2521 made any independent effort to identify any such rights. Information 2522 on the procedures with respect to rights in RFC documents can be 2523 found in BCP 78 and BCP 79. 2525 Copies of IPR disclosures made to the IETF Secretariat and any 2526 assurances of licenses to be made available, or the result of an 2527 attempt made to obtain a general license or permission for the use of 2528 such proprietary rights by implementers or users of this 2529 specification can be obtained from the IETF on-line IPR repository at 2530 http://www.ietf.org/ipr. 2532 The IETF invites any interested party to bring to its attention any 2533 copyrights, patents or patent applications, or other proprietary 2534 rights that may cover technology that may be required to implement 2535 this standard. Please address the information to the IETF at 2536 ietf-ipr@ietf.org. 2538 Acknowledgment 2540 Funding for the RFC Editor function is provided by the IETF 2541 Administrative Support Activity (IASA).