idnits 2.17.1 draft-ietf-atompub-protocol-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 1342. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1314. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1321. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1327. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- The 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 (October 27, 2005) is 6756 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. 'AtomFormat' ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) Summary: 8 errors (**), 0 flaws (~~), 2 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Gregorio, Ed. 3 Internet-Draft BitWorking, Inc 4 Expires: April 30, 2006 B. de hOra, Ed. 5 Propylon Ltd. 6 October 27, 2005 8 The Atom Publishing Protocol 9 draft-ietf-atompub-protocol-06.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 April 30, 2006. 36 Copyright Notice 38 Copyright (C) The Internet Society (2005). 40 Abstract 42 The Atom Publishing Protocol (APP) is an application-level protocol 43 for publishing and editing Web resources. The protocol is based on 44 HTTP transport of Atom-formatted representations. The Atom format is 45 documented in the Atom Syndication Format 46 (draft-ietf-atompub-format-11.txt). 48 Editorial Note 49 To provide feedback on this Internet-Draft, join the atom-protocol 50 mailing list (http://www.imc.org/atom-protocol/index.html) [1]. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 55 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 5 56 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 6 57 4. Protocol Model . . . . . . . . . . . . . . . . . . . . . . . 7 58 5. Protocol Operations . . . . . . . . . . . . . . . . . . . . 8 59 5.1 Retrieving an Introspection Document . . . . . . . . . . . 8 60 5.2 Creating a Resource . . . . . . . . . . . . . . . . . . . 8 61 5.3 Editing a Resource . . . . . . . . . . . . . . . . . . . . 8 62 5.3.1 Retrieving a Resource . . . . . . . . . . . . . . . . 9 63 5.3.2 Updating a Resource . . . . . . . . . . . . . . . . . 9 64 5.3.3 Deleting a Resource . . . . . . . . . . . . . . . . . 9 65 5.4 Listing Collections . . . . . . . . . . . . . . . . . . . 10 66 5.5 Success and Failure . . . . . . . . . . . . . . . . . . . 10 67 6. XML-related Conventions . . . . . . . . . . . . . . . . . . 11 68 6.1 Referring to Information Items . . . . . . . . . . . . . . 11 69 6.2 XML Namespace Usage . . . . . . . . . . . . . . . . . . . 11 70 6.3 RELAX NG Schema . . . . . . . . . . . . . . . . . . . . . 11 71 6.4 Use of xml:base and xml:lang . . . . . . . . . . . . . . . 11 72 7. Introspection Documents . . . . . . . . . . . . . . . . . . 13 73 7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . 13 74 7.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . 13 75 7.3 Element Definitions . . . . . . . . . . . . . . . . . . . 14 76 7.3.1 The 'app:service' Element . . . . . . . . . . . . . . 14 77 7.3.2 The 'app:workspace' Element . . . . . . . . . . . . . 14 78 7.3.3 The 'app:collection' Element . . . . . . . . . . . . . 15 79 7.3.4 The 'app:member-type' Element . . . . . . . . . . . . 15 80 7.3.5 The 'app:list-template' Element . . . . . . . . . . . 16 81 8. Collections . . . . . . . . . . . . . . . . . . . . . . . . 18 82 8.1 Creating resources with POST . . . . . . . . . . . . . . . 18 83 8.1.1 Title: Header . . . . . . . . . . . . . . . . . . . . 18 84 8.2 Entry Collections . . . . . . . . . . . . . . . . . . . . 19 85 8.2.1 Role of Atom Entry Elements During Editing . . . . . . 19 86 8.3 Media Collections . . . . . . . . . . . . . . . . . . . . 20 87 8.3.1 Editing Media Resources . . . . . . . . . . . . . . . 20 88 9. Listing Collections . . . . . . . . . . . . . . . . . . . . 21 89 10. Atom Entry Extensions . . . . . . . . . . . . . . . . . . . 23 90 10.1 The 'edit' Link Relation . . . . . . . . . . . . . . . . 23 91 10.2 Publishing Control . . . . . . . . . . . . . . . . . . . 23 92 10.2.1 The app:draft Element . . . . . . . . . . . . . . . 24 93 11. Example . . . . . . . . . . . . . . . . . . . . . . . . . . 25 94 12. Securing the Atom Protocol . . . . . . . . . . . . . . . . . 27 95 13. Security Considerations . . . . . . . . . . . . . . . . . . 28 96 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . 29 97 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 98 15.1 Normative References . . . . . . . . . . . . . . . . . . 31 99 15.2 Informative References . . . . . . . . . . . . . . . . . 32 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 33 101 A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 34 102 B. RELAX NG Compact Schema . . . . . . . . . . . . . . . . . . 35 103 C. Revision History . . . . . . . . . . . . . . . . . . . . . . 38 104 Intellectual Property and Copyright Statements . . . . . . . 40 106 1. Introduction 108 The Atom Publishing Protocol is an application-level protocol for 109 publishing and editing Web resources using HTTP [RFC2616] and XML 1.0 110 [W3C.REC-xml-20040204]. The protocol supports the creation of 111 arbitrary web resources and provides facilities for: 113 o Collections: Sets of resources, which may be retrieved in whole or 114 in part. 116 o Introspection: Discovering and describing collections. 118 o Editing: Creating, updating and deleting resources. 120 2. Notational Conventions 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 124 document are to be interpreted as described in [RFC2119]. 126 Note: The Introspection Document allows the use of IRIs [RFC3987], as 127 well as URIs [RFC3986]. Every URI is an IRI, so any URI can be used 128 where an IRI is needed. How to map an IRI to a URI is specified in 129 Section 3.1 of Internationalized Resource Identifiers (IRIs) 130 [RFC3987]. 132 3. Terminology 134 For convenience, this protocol may be referred to as "Atom Protocol" 135 or "APP". 137 The phrase "the IRI of a document" in this specification is shorthand 138 for "an IRI which, when dereferenced, is expected to produce that 139 document as a representation". 141 URI/IRI - A Uniform Resource Identifier and Internationalized 142 Resource Identifier, respectively. These terms (and the distinction 143 between them) are defined in [RFC3986] and [RFC3987]. 145 resource - A network data object or service that can be identified 146 by a IRI, as defined in [RFC2616]. See [W3C.REC-webarch-20041215] 147 for further discussion on resources. 149 representation - An entity included with a request or response as 150 defined in [RFC2616]. 152 collection - A resource that contains a set of member IRIs, as 153 described in Section 8 of this specification. 155 member - A resource whose IRI is listed in a collection. 157 IRI template - A parameterized string that becomes a IRI when the 158 parameters are filled in. See Section 9. 160 introspection document - A document that describes the location and 161 capabilities of one or more collections. See Section 7 163 client writable element - An element of an Atom Entry whose value is 164 editable by the client and not enforced by the server. 166 server-controlled element - An element of an Atom Entry whose value 167 is enforced by the server and not editable by the client. 169 4. Protocol Model 171 The Atom Publishing Protocol uses HTTP to edit resources on the web. 172 It provides a list based mechanism for managing collections of 173 editable resources called member resources. Collections contain the 174 IRIs and metadata describing member resources. The APP uses these 175 HTTP verbs: 177 o GET is used to retrieve a representation of a resource or perform 178 a query. 180 o POST is used to create a new, dynamically-named resource. 182 o PUT is used to update a known resource. 184 o DELETE is used to remove a resource. 186 This diagram shows the APP model: 188 +---------------+ 189 | Introspection | +------------+ 190 | |-->| Collection | 191 +---------------+ | | 192 | | +--------+ 193 | |-->| Member | 194 | | +--------+ 195 | | 196 | | . 197 | | . 198 | | . 199 | | 200 | | +--------+ 201 | |-->| Member | 202 | | +--------+ 203 | | 204 +------------+ 206 The introspection document contains the IRIs of one or more 207 collections. A collection contains IRIs and metadata describing 208 member resources. The protocol allows editing of resources with 209 representations of any media-type. Some types of collections are 210 specialized and restrict the resource representations of their 211 members. 213 5. Protocol Operations 215 5.1 Retrieving an Introspection Document 217 Client Server 218 | | 219 | 1.) GET to IRI of Introspection Document | 220 |------------------------------------------>| 221 | | 222 | 2.) Introspection Document | 223 |<------------------------------------------| 224 | | 226 1. The client sends a GET request to the IRI of the introspection 227 document. 229 2. The server responds with the introspection document which 230 enumerates the IRIs of all the collections, and the capabilities 231 of those collections, that the service supports. 233 5.2 Creating a Resource 235 Client Server 236 | | 237 | 1.) POST to IRI of Collection | 238 |------------------------------------------>| 239 | | 240 | 2.) 201 Created | 241 |<------------------------------------------| 242 | | 244 1. The client POSTs a representation to the IRI of the collection. 246 2. If the member resource was created successfully the server 247 responds with a status code of 201 and a Location: header that 248 contains the IRI of the newly created member resource. 250 5.3 Editing a Resource 252 Once a resource has been created and its IRI is known, that IRI may 253 be used to retrieve, update, and delete it. 255 5.3.1 Retrieving a Resource 257 Client Server 258 | | 259 | 1.) GET to Member IRI | 260 |------------------------------------------>| 261 | | 262 | 2.) Member Representation | 263 |<------------------------------------------| 264 | | 266 1. The client sends a GET request to the member's IRI to retrieve 267 its representation . 269 2. The server responds with the representation of the resource. 271 5.3.2 Updating a Resource 273 Client Server 274 | | 275 | 1.) PUT to Member IRI | 276 |------------------------------------------>| 277 | | 278 | 2.) 200 OK | 279 |<------------------------------------------| 281 1. The client PUTs an updated representation to the member's IRI. 283 2. Upon a successful update of the resource the server responds with 284 a status code of 200. 286 5.3.3 Deleting a Resource 288 Client Server 289 | | 290 | 1.) DELETE to Member Resource IRI | 291 |------------------------------------------>| 292 | | 293 | 2.) 200 Ok | 294 |<------------------------------------------| 295 | | 297 1. The client sends a DELETE request to the member's IRI. 299 2. Upon the successful deletion of the resource the server responds 300 with a status code of 200. 302 Note: deleting a member also removes it from all the collections to 303 which it belongs. 305 5.4 Listing Collections 307 To enumerate the members of a collection the client sends a GET to 308 its IRI. This IRI is constructed from information in the 309 introspection document. An Atom Feed Document is returned with one 310 Atom Entry for each member resource that matches the selection 311 criteria in the IRI. See Section 9 and Section 10 for a description 312 of the feed contents. 314 Client Server 315 | | 316 | 1.) GET to List IRI | 317 |------------------------------->| 318 | | 319 | 2.) 200 OK, Atom Feed Doc | 320 |<-------------------------------| 321 | | 323 1. The client sends a GET request to the membership list IRI. 325 2. The server responds with an Atom Feed Document containing the 326 IRIs of all the collection members that match the selection 327 criteria. 329 5.5 Success and Failure 331 The Atom Protocol uses HTTP status codes to signal the results of 332 protocol operations. Status codes of the form 2xx signal that a 333 request was successful. HTTP status codes of the form 4xx or 5xx 334 signal that an error has occurred. Consult the HTTP specification 335 [RFC2616] for the definitions of HTTP status codes. 337 6. XML-related Conventions 339 The data format in this specification is specified in terms of the 340 XML Information Set, serialised as XML 1.0 [W3C.REC-xml-20040204]. 341 Atom Publishing Protocol Documents MUST be well-formed XML. This 342 specification does not define any DTDs for Atom Protocol, and hence 343 does not require them to be valid (in the sense used by XML). 345 6.1 Referring to Information Items 347 This specification uses a shorthand for two common terms: the phrase 348 "Information Item" is omitted when naming Element Information Items 349 and Attribute Information Items. Therefore, when this specification 350 uses the term "element," it is referring to an Element Information 351 Item in Infoset terms. Likewise, when it uses the term "attribute," 352 it is referring to an Attribute Information Item. 354 6.2 XML Namespace Usage 356 The Namespace URI [W3C.REC-xml-names-19990114] for the data format 357 described in this specification is: 359 http://purl.org/atom/app# 361 This specification uses the prefix "app:" for the Namespace URI. The 362 choice of namespace prefix is not semantically significant. 364 This specification also uses the prefix "atom:" for the Namespace URI 365 identified in [AtomFormat]. 367 6.3 RELAX NG Schema 369 Some sections of this specification are illustrated with fragments of 370 a non-normative RELAX NG Compact schema [RNC]. However, the text of 371 this specification provides the definition of conformance. A 372 complete schema appears in Appendix B. 374 6.4 Use of xml:base and xml:lang 376 XML elements defined by this specification MAY have an xml:base 377 attribute [W3C.REC-xmlbase-20010627]. When xml:base is used, it 378 serves the function described in section 5.1.1 of [RFC3986], 379 establishing the base URI (or IRI) for resolving any relative 380 references found within the effective scope of the xml:base 381 attribute. 383 Any element defined by this specification MAY have an xml:lang 384 attribute, whose content indicates the natural language for the 385 element and its descendents. The language context is only 386 significant for elements and attributes declared to be "Language- 387 Sensitive" by this specification. Requirements regarding the content 388 and interpretation of xml:lang are specified in Section 2.12 of XML 389 1.0 [W3C.REC-xml-20040204], . 390 appCommonAttributes = 391 attribute xml:base { atomUri }?, 392 attribute xml:lang { atomLanguageTag }?, 393 undefinedAttribute* 395 7. Introspection Documents 397 7.1 Introduction 399 For authoring to commence, a client needs to first discover the 400 capabilities and locations of collections offered. This is done 401 using Introspection Documents. An Introspection Document describes 402 workspaces, which are server-defined groupings of collections. 404 7.2 Example 406 407 408 409 412 entry 413 http://example.org/{index} 414 415 418 media 419 http://example.org/p/{index} 420 421 422 423 425 entry 426 http://example.org/l/{index} 427 428 429 431 This Introspection Document describes two workspaces. The first, 432 called 'Main Site', has two collections called 'My Blog Entries' and 433 'Pictures' whose IRIs are 'http://example.org/reilly/main' and 434 'http://example.org/reilly/pic' respectively. 'My Blog Entries' is 435 an Entry collection and 'Pictures' is a Media collection. Entry and 436 Media collections are discussed in Section 7.3.4. 438 The second workspace is called 'Side Bar Blog' and has a single 439 collection called 'Remaindered Links' whose collection IRI is 440 'http://example.org/reilly/list'. 'Remaindered Links' is an Entry 441 collection. 443 Introspection documents are identified with the "application/ 444 atomserv+xml" media type (see Section 14). 446 While an introspection document allows multiple workspaces, there is 447 no requirement that a service support multiple workspaces. In 448 addition, a collection MAY appear in more than one workspace. 450 7.3 Element Definitions 452 7.3.1 The 'app:service' Element 454 The root of an introspection document is the app:service element. 455 namespace app = "http://purl.org/atom/app#" 456 start = appService 458 The "app:service" element is the container for introspection 459 information associated with one or more workspaces. An app:service 460 element MUST contain one or more app:workspace elements. 462 appService = 463 element app:service { 464 appCommonAttributes, 465 ( appWorkspace+ 466 & extensionElement* ) 467 } 469 7.3.2 The 'app:workspace' Element 471 The 'app:workspace' element contains information elements about the 472 collections of resources available for editing. The app:workspace 473 element MUST contain one or more app:collection elements. 475 appWorkspace = 476 element app:workspace { 477 appCommonAttributes, 478 attribute title { text }, 479 ( appCollection+ 480 & extensionElement* ) 481 } 483 7.3.2.1 The 'title' Attribute 485 The app:workspace element MUST contain a 'title' attribute, which 486 conveys a human-readable name for the workspace. This attribute is 487 Language-Sensitive. 489 7.3.3 The 'app:collection' Element 491 The app:collection contains information elements that describe the 492 location and capabilities of a collection. 494 appCollection = 495 element app:collection { 496 appCommonAttributes, 497 attribute title { text }, 498 attribute href { text }, 499 ( appMemberType 500 & appListTemplate 501 & extensionElement* ) 502 } 504 7.3.3.1 The 'title' Attribute 506 The app:collection element MUST contain a 'title' attribute, whose 507 value conveys a human-readable name for the collection. This 508 attribute is Language-Sensitive. 510 7.3.3.2 The 'href' Attribute 512 The app:collection element MUST contain an 'href' attribute, whose 513 value conveys the IRI of the collection. 515 This specification defines two child elements for app:collection: 517 o app:member-type: a single element that contains the type of 518 members that the collection can contain. 520 o app:list-template: a single element that contains a IRI template 521 of a membership list. (See Section 9). 523 7.3.4 The 'app:member-type' Element 525 The app:collection element MUST contain one 'app:member-type' 526 element. The app:member-type element value specifies the types of 527 members that can appear in the collection. 529 appMemberType = 530 element app:member-type { 531 appCommonAttributes, 532 ( appTypeValue ) 533 } 535 appTypeValue = "entry" | "media" 537 An Entry POSTed to a collection MUST meet the constraints of the app: 538 member-type element. 540 This specification defines two initial values for the app:member-type 541 IANA registry: 543 o "entry" - The collection contains only member resources whose 544 representation MUST be an Atom Entry. Further constraints on the 545 representations of members in a collection of type "entry" are 546 listed in Section 8.2. 548 o "media" - The collection contains member resources whose 549 representation can be of any media type. Additional constraints 550 are listed in Section 8.3. 552 In general the value of app:member-type MUST be a string that is non- 553 empty, and matches either the "isegment-nz-nc" or the "IRI" 554 production in [RFC3987]. Note that use of a relative reference other 555 than a simple name is not allowed. If a name is given, 556 implementations MUST consider the link relation type to be equivalent 557 to the same name registered within the IANA Registry of Link 558 Relations Section 14, and thus the IRI that would be obtained by 559 appending the value of the rel attribute to the string 560 "http://www.iana.org/assignments/member-type/". 562 7.3.5 The 'app:list-template' Element 564 The app:collection element MUST contain one 'app:list-template' 565 elements. The element content of app:list-template is an IRI 566 template (Section 9) for a collection. 568 appListTemplate = 569 element app:list-template { 570 appCommonAttributes, 571 ( appUriTemplate ) 572 } 574 appUriTemplate = xsd:string { pattern = ".+\{.+\}.*" } 576 8. Collections 578 8.1 Creating resources with POST 580 Every collection accepts POST requests to create resources - the 581 client POSTs a representation of the desired resource to the IRI of 582 the collection. Collections MAY impose constraints on the media- 583 types that are created in a collection and MAY generate a response 584 with a status code of 415 ("Unsupported Media Type"). 586 The status code returned for a successful creation POST MUST be 201 587 ("Created"). 589 A successful creation POST MUST return a Location: header with the 590 URI of the newly created resource. 592 Clients MAY POST invalid Atom for initial resource creation - 593 specifically the id and link elements MAY be omitted. 595 Below, the client requests to create a resource in a collection: 597 POST /edit HTTP/1.1 598 Host: example.org 599 User-Agent: Thingio/1.0 600 Content-Type: application/atom+xml 601 Content-Length: nnn 603 604 Atom-Powered Robots Run Amok 605 2003-12-13T18:30:02Z 606 Some text. 607 608 The resource is created by sending an Atom Entry as the entity body. 610 Successful creation is indicated by a 201 created response and 611 includes a Location: header. 613 HTTP/1.1 201 Created 614 Date: Fri, 7 Oct 2005 17:17:11 GMT 615 Content-Length: 0 616 Location: http://example.org/edit/first-post.atom 618 8.1.1 Title: Header 620 The POST to a collection MAY contain a Title: header that indicates 621 the client's suggested title for the resource. The server MAY ignore 622 the Title: header or modify the requested title. 624 Title = "Title" ":" [text] 626 The syntax of this header MUST conform to the augmented BNF grammar 627 in section 2.1 of the HTTP/1.1 specification [RFC2616]. 629 8.2 Entry Collections 631 Entry Collections are collections that restrict their membership to 632 Atom Entries. They are identified by having an app:member-type of 633 "entry". Every member representation MUST contain an atom:link 634 element with a relation of rel="edit" that contains the IRI of the 635 member resource. Member representations MAY contain an app:control 636 element (Section 10.2). 638 8.2.1 Role of Atom Entry Elements During Editing 640 The elements of an Atom Entry Document are either a client writable 641 or server controlled. 643 Client Writable - An element of an Atom Entry whose value is editable 644 by the client. Servers MAY modify the content of client writable 645 elements. Some reasons that a server may change client writable 646 content include length limits, obscenity filters or the addition of 647 boilerplate text. 649 Server Controlled - An element of an Atom Entry whose value is 650 enforced by the server and not editable by the client. Clients 651 SHOULD NOT change the value of server controlled elements. Servers 652 MUST NOT rely on clients preserving the values of server controlled 653 elements. 655 +--------------------+--------------------+ 656 | Atom Entry Element | Property | 657 +--------------------+--------------------+ 658 | atom:author | Client Writable | 659 | | | 660 | atom:category | Client Writable | 661 | | | 662 | atom:content | Client Writable | 663 | | | 664 | atom:contributor | Client Writable | 665 | | | 666 | atom:id | Server Controlled | 667 | | | 668 | atom:link | Client Writable | 669 | | | 670 | atom:published | Client Writable | 671 | | | 672 | atom:source | Client Writable | 673 | | | 674 | atom:summary | Client Writable | 675 | | | 676 | atom:title | Client Writable | 677 | | | 678 | atom:updated | Server Controlled | 679 | | | 680 | app:control | Client Writable | 681 +--------------------+--------------------+ 683 Table 1 685 8.3 Media Collections 687 Media Collections are collections whose member representations are 688 not constrained. They are identified by having an app:member-type of 689 "media". 691 8.3.1 Editing Media Resources 693 When a membership list resource returns an Atom Feed enumerating the 694 contents of a Media Collection, all the Entries MUST have an atom: 695 content element with a 'src' attribute. When creating a public, 696 read-only reference to the member resource, a client SHOULD use the 697 "atom:content/@src" attribute value. 699 9. Listing Collections 701 Collections, as identified in an Introspection Document, are 702 resources that MUST provide representations in the form of Atom Feed 703 documents. The entries in the returned Feed MUST be ordered by their 704 'atom:updated' property, with the most recently updated entries 705 coming first in the document order. Every entry in the Feed Document 706 MUST have an atom:link element with a relation of "edit" (See 707 Section 10.1). Clients MUST NOT assume that an Atom Entry returned 708 in the Feed is a full representation of a member resource. The value 709 of atom:updated is only changed when the change to a member resource 710 is considered significant. Insignificant changes do not result in 711 changes to the atom:updated value and thus do not change the position 712 of the corresponding entry in a membership list. Clients SHOULD be 713 constructed with this in mind and SHOULD perform a GET on the member 714 resource before editing. 716 Collections can contain extremely large numbers of resources. A 717 naive client such as a web spider or web browser would be overwhelmed 718 if the response to a GET contained every entry in the feed, and the 719 server would waste large amounts of bandwidth and processing time on 720 clients unable to handle the response. 722 For this reason, Introspection documents refer to collections not 723 with IRIs but with IRI Templates, contained in the "app:member-type" 724 child of "app:collection". An IRI Template is a string containing 725 the embedded token "{index}". 727 To produce an IRI that can be used to retrieve part or all of the 728 collection, software replaces the "{index}" with a pair of positive 729 integer indices separated by a dash character. An IRI template MUST, 730 after such substitution has been performed, constitute a 731 syntactically valid IRI. 733 One or other index MAY be omitted, in which case the range is 734 understood as stretching to 0 or infinity. The index values are 0 735 based and select members from the collection based on the member's 736 index, with all of the members ordered by their 'atom:updated' 737 property. The response to the selection request MUST be an Atom Feed 738 where all the entries fall within the requested criteria. The 739 request range is considered a closed set - if an entry matches one 740 end of the range exactly it MUST be included in the response. If no 741 members fall in the requested range, the server MUST respond with an 742 Atom Feed containing no entries. If a membership list is returned 743 with a number of entries that is less than the number of entries 744 requested than the client MAY assume that it has made a request that 745 exceeds the last index of the members. 747 For example, suppose the client is supplied this IRI template: 749 http://example.org/blog/edit/{index} 750 If the client wants the first 15 entries in the collection it would 751 substitute the brace-delimited parameter {index}, with the value 752 0-14, giving: 754 http://example.org/blog/edit/0-14 756 10. Atom Entry Extensions 758 This specification adds one new value to the Registry of Link 759 Relations and also adds a new element to Atom Entries called "app: 760 control" for controlling publishing. These new links and app: 761 control elements MAY appear in both membership lists and in member 762 representations. 764 10.1 The 'edit' Link Relation 766 This specification adds the value "edit" to the Registry of Link 767 Relations. The value of "edit" signifies that the IRI in the value 768 of the href attribute is the IRI of the member resource, and is 769 intended to be used to update and delete resources as described in 770 this specification. 772 10.2 Publishing Control 774 This specification also adds a new element to Atom Entries for 775 controlling publishing. 777 pubControl = 778 element app:control { 779 atomCommonAttributes, 780 pubDraft? 781 & extensionElement 782 } 784 pubDraft = 785 element app:draft { "yes" | "no" } 787 The "app:control" element MAY appear as a child of an "atom:entry" 788 which is being created or updated via the Atom Publishing Protocol. 789 The "app:control" element, if it does appear in an entry, MUST only 790 appear at most one time. 792 The "app:control" element and its children elements MAY be included 793 in Atom Feed or Entry Documents. The "app:control" element is 794 considered "foreign markup" as defined in Section 6 of the Atom 795 Syndication Format. 797 The "app:control" element MAY contain exactly one app:draft element 798 and MAY contain zero or more extension elements as outlined in the 799 Atom Syndication Format, Section 6. Both clients and servers MUST 800 ignore foreign markup present in the app:control element that they do 801 not know. 803 10.2.1 The app:draft Element 805 This specification defines only one child element for "app:control", 806 "app:draft". 808 The number of "app:draft" elements in "app:control" MUST be zero or 809 one. Its content MUST be one of the values "yes" or "no". A value 810 of "no" means that the entry MAY be made publicly visible. If the 811 "app:draft" element is missing then the value is understood to be 812 "no". That is, if "app:control" and/or the "app:draft" elements are 813 missing from an entry then the entry is considered not a draft and 814 can be made publicly visible. Clients MUST understand "app:draft" 815 elements and MUST NOT drop them from Atom Entries during editing. 816 Clients MUST NOT operate on the expectation that a server will honor 817 the value of an "app:draft" element. Servers MAY ignore "app:draft" 818 elements and drop them from Atom Entries. 820 11. Example 822 This is an example of a client creating a new entry with an image. 823 The client has an image to publish and an entry that includes an HTML 824 'img' element that uses that image. In this scenario we consider a 825 client that has IRIs of two collections, an entry collection and a 826 media collection, both of which were discovered through an 827 introspection document. The IRI of the entry collection is: 829 http://example.net/blog/edit/ 831 The IRI of the media collection is: 833 http://example.net/binary/edit 835 First the client creates a new image resource by POSTing the image to 836 the IRI of the media collection. 838 POST /binary/edit/ HTTP/1.1 839 Host: example.net 840 User-Agent: Thingio/1.0 841 Content-Type: image/png 842 Content-Length: nnnn 843 Title: A picture of the beach 845 ...binary data... 847 The member resource is created and an HTTP status code of 201 is 848 returned. 850 HTTP/1.1 201 Created 851 Date: Fri, 25 Mar 2005 17:17:11 GMT 852 Content-Length: nnnn 853 Content-Type: application/atom+xml 854 Location: http://example.net/binary/edit/b/129.png 856 857 858 A picture of the beach. 859 861 urn:uuid:1225c695-cfb8-4ebb-aaaa-568596895695 862 2005-09-02T10:30:00Z 863 Waves 864 866 867 The client then POSTs the Atom Entry that refers to the newly created 868 image resource. Note that the client takes the IRI 869 http://example.net/binary/readonly/129.png and uses it in the 'img' 870 element in the Entry content: 872 POST /blog/edit/ HTTP/1.1 873 Host: example.net 874 User-Agent: Thingio/1.0 875 Content-Type: application/atom+xml 876 Content-Length: nnnn 878 879 880 What I did on my summer vacation 881 2005-09-02T10:30:00Z 882 Beach! 883 884
885

We went to the beach for summer vacation. 886 Here is a picture of the waves rolling in: 887 A picture of the beach. 891

892
893 894 896 12. Securing the Atom Protocol 898 All instances of publishing Atom entries SHOULD be protected by 899 authentication to prevent posting or editing by unknown sources. 900 Atom servers and clients MUST support one of the following 901 authentication mechanisms, and SHOULD support both. 903 o HTTP Digest Authentication [RFC2617] 905 o [@@TBD@@ CGI Authentication ref] 907 Atom servers and clients MAY support encryption of the session using 908 TLS (see [RFC2246]). 910 There are cases where an authentication mechanism is not be required, 911 such as a publicly editable Wiki, or when using POST to send comments 912 to a site that does not require authentication from a commenter. 914 12.1 [@@TBD@@ CGI Authentication] 916 This authentication method is included as part of the protocol to 917 allow Atom servers and clients that cannot use HTTP Digest 918 Authentication but where the user can both insert its own HTTP 919 headers and create a CGI program to authenticate entries to the 920 server. This scenario is common in environments where the user 921 cannot control what services the server employs, but the user can 922 write their own HTTP services. 924 13. Security Considerations 926 The security of Atom is based on HTTP Digest Authentication and/or 927 [@@TBD@@ CGI Authentication]. Any weaknesses in either of these 928 authentication schemes will affect the security of the Atom 929 Publishing Protocol. 931 Both HTTP Digest Authentication and [@@TBD@@ CGI Authentication] are 932 susceptible to dictionary-based attacks on the shared secret. If the 933 shared secret is a password (instead of a random string with 934 sufficient entropy), an attacker can determine the secret by 935 exhaustively comparing the authenticating string with hashed results 936 of the public string and dictionary entries. 938 See [RFC2617] for the description of the security properties of HTTP 939 Digest Authentication. 941 @@TBD@@ Talk here about using HTTP basic and digest authentication. 943 @@TBD@@ Talk here about denial of service attacks using large XML 944 files, or the billion laughs DTD attack. 946 14. IANA Considerations 948 An Atom Introspection Document, when serialized as XML 1.0, can be 949 identified with the following media type: 951 MIME media type name: application 953 MIME subtype name: atomserv+xml 955 Mandatory parameters: None. 957 Optional parameters: 959 "charset": This parameter has identical semantics to the charset 960 parameter of the "application/xml" media type as specified in 961 [RFC3023]. 963 Encoding considerations: Identical to those of "application/xml" as 964 described in [RFC3023], section 3.2. 966 Security considerations: As defined in this specification. 967 [[anchor22: update upon publication]] 969 In addition, as this media type uses the "+xml" convention, it 970 shares the same security considerations as described in [RFC3023], 971 section 10. 973 Interoperability considerations: There are no known interoperability 974 issues. 976 Published specification: This specification. [[anchor23: update upon 977 publication]] 979 Applications that use this media type: No known applications 980 currently use this media type. 982 Additional information: 984 Magic number(s): As specified for "application/xml" in [RFC3023], 985 section 3.2. 987 File extension: .atomsrv 989 Fragment identifiers: As specified for "application/xml" in 990 [RFC3023], section 5. 992 Base URI: As specified in [RFC3023], section 6. 994 Macintosh File Type code: TEXT 996 Person and email address to contact for further information: Joe 997 Gregorio 999 Intended usage: COMMON 1001 Author/Change controller: This specification's author(s). [[anchor24: 1002 update upon publication]] 1004 15. References 1006 15.1 Normative References 1008 [AtomFormat] 1009 Nottingham, M. and R. Sayre, "The Atom Syndication 1010 Format", 1.0, July 2005. 1012 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1013 Requirement Levels", BCP 14, RFC 2119, March 1997. 1015 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 1016 RFC 2246, January 1999. 1018 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1019 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1020 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1022 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1023 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1024 Authentication: Basic and Digest Access Authentication", 1025 RFC 2617, June 1999. 1027 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 1028 Types", RFC 3023, January 2001. 1030 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1031 Resource Identifier (URI): Generic Syntax", STD 66, 1032 RFC 3986, January 2005. 1034 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1035 Identifiers (IRIs)", RFC 3987, January 2005. 1037 [W3C.REC-xml-20040204] 1038 Yergeau, F., Paoli, J., Sperberg-McQueen, C., Bray, T., 1039 and E. Maler, "Extensible Markup Language (XML) 1.0 (Third 1040 Edition)", W3C REC REC-xml-20040204, February 2004. 1042 [W3C.REC-xml-names-19990114] 1043 Hollander, D., Bray, T., and A. Layman, "Namespaces in 1044 XML", W3C REC REC-xml-names-19990114, January 1999. 1046 [W3C.REC-xmlbase-20010627] 1047 Marsh, J., "XML Base", W3C REC W3C.REC-xmlbase-20010627, 1048 June 2001. 1050 15.2 Informative References 1052 [RNC] Clark, J., "RELAX NG Compact Syntax", December 2001. 1054 [W3C.REC-webarch-20041215] 1055 Walsh, N. and I. Jacobs, "Architecture of the World Wide 1056 Web, Volume One", W3C REC REC-webarch-20041215, 1057 December 2004. 1059 URIs 1061 [1] 1063 Authors' Addresses 1065 Joe Gregorio (editor) 1066 BitWorking, Inc 1067 1002 Heathwood Dairy Rd. 1068 Apex, NC 27502 1069 US 1071 Phone: +1 919 272 3764 1072 Email: joe@bitworking.com 1073 URI: http://bitworking.com/ 1075 Bill de hOra (editor) 1076 Propylon Ltd. 1077 45 Blackbourne Square, Rathfarnham Gate 1078 Dublin, Dublin D14 1079 IE 1081 Phone: +353-1-4927444 1082 Email: bill.dehora@propylon.com 1083 URI: http://www.propylon.com/ 1085 Appendix A. Contributors 1087 The content and concepts within are a product of the Atom community 1088 and the Atompub Working Group. 1090 Appendix B. RELAX NG Compact Schema 1092 This appendix is informative. 1094 The Relax NG schema explicitly excludes elements in the APP namespace 1095 which are not defined in this revision of the specification. 1096 Requirements for APP Processors encountering such markup are given in 1097 Section 6.2 and Section 6.3 of [AtomFormat]. 1099 # -*- rnc -*- 1100 # RELAX NG Compact Syntax Grammar for the Atom Protocol 1102 namespace app = "http://purl.org/atom/app#" 1103 namespace local = "" 1105 start = appService 1107 # common:attrs 1109 appCommonAttributes = 1110 attribute xml:base { atomUri }?, 1111 attribute xml:lang { atomLanguageTag }?, 1112 undefinedAttribute* 1114 undefinedAttribute = 1115 attribute * - (xml:base | xml:lang | local:*) { text } 1117 atomUri = text 1119 atomLanguageTag = xsd:string { 1120 pattern = "[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*" 1121 } 1123 # app:service 1125 appService = 1126 element app:service { 1127 appCommonAttributes, 1128 ( appWorkspace+ 1129 & extensionElement* ) 1130 } 1132 # app:workspace 1134 appWorkspace = 1135 element app:workspace { 1136 appCommonAttributes, 1137 attribute title { text }, 1138 ( appCollection+ 1139 & extensionElement* ) 1140 } 1142 # app:collection 1144 appCollection = 1145 element app:collection { 1146 appCommonAttributes, 1147 attribute title { text }, 1148 attribute href { text }, 1149 ( appMemberType 1150 & appListTemplate 1151 & extensionElement* ) 1152 } 1154 # app:member 1156 appMemberType = 1157 element app:member-type { 1158 appCommonAttributes, 1159 ( appTypeValue ) 1160 } 1162 appTypeValue = "entry" | "media" 1164 # app:list-template 1166 appListTemplate = 1167 element app:list-template { 1168 appCommonAttributes, 1169 ( appUriTemplate ) 1170 } 1172 # Whatever an IRI template is, it contains at least {index} 1174 appUriTemplate = xsd:string { pattern = ".+\{index\}.*" } 1176 # Simple Extension 1178 simpleExtensionElement = 1179 element * - app:* { 1180 text 1181 } 1183 # Structured Extension 1184 structuredExtensionElement = 1185 element * - app:* { 1186 (attribute * { text }+, 1187 (text|anyElement)*) 1188 | (attribute * { text }*, 1189 (text?, anyElement+, (text|anyElement)*)) 1190 } 1192 # Other Extensibility 1194 extensionElement = 1195 simpleExtensionElement | structuredExtensionElement 1197 # Extensions 1199 anyElement = 1200 element * { 1201 (attribute * { text } 1202 | text 1203 | anyElement)* 1204 } 1206 # EOF 1208 Appendix C. Revision History 1210 draft-ietf-atompub-protocol-06 - Removed: Robert Sayre from the 1211 contributors section per his request. Added in 1212 PaceCollectionControl. Fixed all the {daterange} verbage and 1213 examples so they all use a dash. Added full rnc schema. Collapsed 1214 Introspection and Collection documents into a single document. 1215 Removed {dateRange} queries. Renamed search to list. Moved 1216 discussion of media and entry collection until later in the document 1217 and tied the discussion to the Introspection element app:member-type. 1219 draft-ietf-atompub-protocol-05 - Added: Contributors section. Added: 1220 de hOra to editors. Fixed: typos. Added diagrams and description to 1221 model section. Incorporates PaceAppDocuments, PaceAppDocuments2, 1222 PaceSimplifyCollections2 (large-sized chunks of it anyhow: the 1223 notions of Entry and Generic resources, the section 4 language on the 1224 Protocol Model, 4.1 through 4.5.2, the notion of a Collection 1225 document, as in Section 5 through 5.3, Section 7 "Collection 1226 resources", Selection resources (modified from pace which talked 1227 about search); results in major mods to Collection Documents, Section 1228 9.2 "Title: Header" and brokeout para to section 9.1 Editing Generic 1229 Resources). Added XML namespace and language section. Some cleanup 1230 of front matter. Added Language Sensitivity to some attributes. 1231 Removed resource descriptions from terminology. Some juggling of 1232 sections. See: 1233 http://www.imc.org/atom-protocol/mail-archive/msg01812.html. 1235 draft-ietf-atompub-protocol-04 - Add ladder diagrams, reorganize, add 1236 SOAP interactions 1238 draft-ietf-atompub-protocol-03 - Incorporates PaceSliceAndDice3 and 1239 PaceIntrospection. 1241 draft-ietf-atompub-protocol-02 - Incorporates Pace409Response, 1242 PacePostLocationMust, and PaceSimpleResourcePosting. 1244 draft-ietf-atompub-protocol-01 - Added in sections on Responses for 1245 the EditURI. Allow 2xx for response to EditURI PUTs. Elided all 1246 mentions of WSSE. Started adding in some normative references. 1247 Added the section "Securing the Atom Protocol". Clarified that it is 1248 possible that the PostURI and FeedURI could be the same URI. Cleaned 1249 up descriptions for Response codes 400 and 500. 1251 Rev draft-ietf-atompub-protocol-00 - 5Jul2004 - Renamed the file and 1252 re-titled the document to conform to IETF submission guidelines. 1253 Changed MIME type to match the one selected for the Atom format. 1254 Numerous typographical fixes. We used to have two 'Introduction' 1255 sections. One of them was moved into the Abstract the other absorbed 1256 the Scope section. IPR and copyright notifications were added. 1258 Rev 09 - 10Dec2003 - Added the section on SOAP enabled clients and 1259 servers. 1261 Rev 08 - 01Dec2003 - Refactored the specification, merging the 1262 Introspection file into the feed format. Also dropped the 1263 distinction between the type of URI used to create new entries and 1264 the kind used to create comments. Dropped user preferences. 1266 Rev 07 - 06Aug2003 - Removed the use of the RSD file for auto- 1267 discovery. Changed copyright until a final standards body is chosen. 1268 Changed query parameters for the search facet to all begin with atom- 1269 to avoid name collisions. Updated all the Entries to follow the 0.2 1270 version. Changed the format of the search results and template file 1271 to a pure element based syntax. 1273 Rev 06 - 24Jul2003 - Moved to PUT for updating Entries. Changed all 1274 the mime-types to application/x.atom+xml. Added template editing. 1275 Changed 'edit-entry' to 'create-entry' in the Introspection file to 1276 more accurately reflect its purpose. 1278 Rev 05 - 17Jul2003 - Renamed everything Echo into Atom. Added 1279 version numbers in the Revision history. Changed all the mime-types 1280 to application/atom+xml. 1282 Rev 04 - 15Jul2003 - Updated the RSD version used from 0.7 to 1.0. 1283 Change the method of deleting an Entry from POSTing to 1284 using the HTTP DELETE verb. Also changed the query interface to GET 1285 instead of POST. Moved Introspection Discovery to be up under 1286 Introspection. Introduced the term 'facet' for the services listed 1287 in the Introspection file. 1289 Rev 03 - 10Jul2003 - Added a link to the Wiki near the front of the 1290 document. Added a section on finding an Entry. Retrieving an Entry 1291 now broken out into its own section. Changed the HTTP status code 1292 for a successful editing of an Entry to 205. 1294 Rev 02 - 7Jul2003 - Entries are no longer returned from POSTs, 1295 instead they are retrieved via GET. Cleaned up figure titles, as 1296 they are rendered poorly in HTML. All content-types have been 1297 changed to application/atom+xml. 1299 Rev 01 - 5Jul2003 - Renamed from EchoAPI.html to follow the more 1300 commonly used format: draft-gregorio-NN.html. Renamed all references 1301 to URL to URI. Broke out introspection into its own section. Added 1302 the Revision History section. Added more to the warning that the 1303 example URIs are not normative. 1305 Intellectual Property Statement 1307 The IETF takes no position regarding the validity or scope of any 1308 Intellectual Property Rights or other rights that might be claimed to 1309 pertain to the implementation or use of the technology described in 1310 this document or the extent to which any license under such rights 1311 might or might not be available; nor does it represent that it has 1312 made any independent effort to identify any such rights. Information 1313 on the procedures with respect to rights in RFC documents can be 1314 found in BCP 78 and BCP 79. 1316 Copies of IPR disclosures made to the IETF Secretariat and any 1317 assurances of licenses to be made available, or the result of an 1318 attempt made to obtain a general license or permission for the use of 1319 such proprietary rights by implementers or users of this 1320 specification can be obtained from the IETF on-line IPR repository at 1321 http://www.ietf.org/ipr. 1323 The IETF invites any interested party to bring to its attention any 1324 copyrights, patents or patent applications, or other proprietary 1325 rights that may cover technology that may be required to implement 1326 this standard. Please address the information to the IETF at 1327 ietf-ipr@ietf.org. 1329 The IETF has been notified of intellectual property rights claimed in 1330 regard to some or all of the specification contained in this 1331 document. For more information consult the online list of claimed 1332 rights. 1334 Disclaimer of Validity 1336 This document and the information contained herein are provided on an 1337 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1338 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1339 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1340 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1341 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1342 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1344 Copyright Statement 1346 Copyright (C) The Internet Society (2005). This document is subject 1347 to the rights, licenses and restrictions contained in BCP 78, and 1348 except as set forth therein, the authors retain all their rights. 1350 Acknowledgment 1352 Funding for the RFC Editor function is currently provided by the 1353 Internet Society.