--- 1/draft-ietf-atompub-protocol-04.txt 2006-02-04 17:24:28.000000000 +0100 +++ 2/draft-ietf-atompub-protocol-05.txt 2006-02-04 17:24:28.000000000 +0100 @@ -1,17 +1,19 @@ + Network Working Group J. Gregorio, Ed. Internet-Draft BitWorking, Inc -Expires: November 10, 2005 R. Sayre, Ed. - May 9, 2005 +Expires: April 14, 2006 B. de hOra, Ed. + Propylon Ltd. + October 11, 2005 The Atom Publishing Protocol - draft-ietf-atompub-protocol-04.txt + draft-ietf-atompub-protocol-05.txt Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that @@ -22,626 +24,764 @@ and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. - This Internet-Draft will expire on November 10, 2005. + This Internet-Draft will expire on April 14, 2006. Copyright Notice Copyright (C) The Internet Society (2005). Abstract This memo presents a protocol for using XML (Extensible Markup Language) and HTTP (HyperText Transport Protocol) to edit content. - The Atom Publishing Protocol is an application-level protocol for - publishing and editing Web resources belonging to periodically - updated websites. The protocol at its core is the HTTP transport of - Atom-formatted representations. The Atom format is documented in the - Atom Syndication Format (draft-ietf-atompub-format-06.txt). + The Atom Publishing Protocol (APP) is an application-level protocol + for publishing and editing Web resources. The protocol at its core + is the HTTP transport of Atom-formatted representations. The Atom + format is documented in the Atom Syndication Format + (draft-ietf-atompub-format-11.txt). Editorial Note To provide feedback on this Internet-Draft, join the atom-protocol mailing list (http://www.imc.org/atom-protocol/index.html) [1]. Table of Contents - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 4 - 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 4. The Atom Publishing Protocol Model . . . . . . . . . . . . . . 6 - 4.1 Collections . . . . . . . . . . . . . . . . . . . . . . . 6 - 4.2 Discovery . . . . . . . . . . . . . . . . . . . . . . . . 6 - 4.3 Listing . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 4.4 Authoring . . . . . . . . . . . . . . . . . . . . . . . . 7 - 4.4.1 Create . . . . . . . . . . . . . . . . . . . . . . . . 7 - 4.4.2 Read . . . . . . . . . . . . . . . . . . . . . . . . . 8 - 4.4.3 Update . . . . . . . . . . . . . . . . . . . . . . . . 8 - 4.4.4 Delete . . . . . . . . . . . . . . . . . . . . . . . . 8 - 4.5 Success and Failure . . . . . . . . . . . . . . . . . . . 9 - 5. Collections . . . . . . . . . . . . . . . . . . . . . . . . . 10 - 5.1 Collection Documents . . . . . . . . . . . . . . . . . . . 10 - 5.1.1 Element Definitions . . . . . . . . . . . . . . . . . 10 - 5.2 Collection Resource . . . . . . . . . . . . . . . . . . . 12 - 5.2.2 POST . . . . . . . . . . . . . . . . . . . . . . . . . 14 - 5.2.3 Usage Scenarios . . . . . . . . . . . . . . . . . . . 15 - 5.2.4 Range: Header . . . . . . . . . . . . . . . . . . . . 16 - 5.2.5 Accept-Ranges: Header . . . . . . . . . . . . . . . . 16 - 5.2.6 Name: Header . . . . . . . . . . . . . . . . . . . . . 17 - 6. Entry Collection . . . . . . . . . . . . . . . . . . . . . . . 18 - 6.1 Editing Entry Resources . . . . . . . . . . . . . . . . . 18 - 6.2 Role of Atom Entry Elements During Editing . . . . . . . . 18 - 7. Generic Collection . . . . . . . . . . . . . . . . . . . . . . 20 - 7.1 Editing Generic Resources . . . . . . . . . . . . . . . . 20 - 8. Introspection . . . . . . . . . . . . . . . . . . . . . . . . 21 - 8.1 Introspection Document . . . . . . . . . . . . . . . . . . 21 - 8.1.1 Element Definitions . . . . . . . . . . . . . . . . . 21 - 8.2 Introspection Resource . . . . . . . . . . . . . . . . . . 23 - 8.2.1 Discovery . . . . . . . . . . . . . . . . . . . . . . 24 - 9. Securing the Atom Protocol . . . . . . . . . . . . . . . . . . 25 - 10. Security Considerations . . . . . . . . . . . . . . . . . . 26 - 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . 27 - 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 - 12.1 Normative References . . . . . . . . . . . . . . . . . . . 30 - 12.2 Informative References . . . . . . . . . . . . . . . . . . 31 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 32 - A. Revision History . . . . . . . . . . . . . . . . . . . . . . . 33 - Intellectual Property and Copyright Statements . . . . . . . . 35 + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2. XML Namespace and Language . . . . . . . . . . . . . . . . . 5 + 3. Notational Conventions . . . . . . . . . . . . . . . . . . . 6 + 4. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 7 + 5. The Atom Publishing Protocol Model . . . . . . . . . . . . . 8 + 5.1 Collections . . . . . . . . . . . . . . . . . . . . . . . 8 + 5.2 Editable Resources . . . . . . . . . . . . . . . . . . . . 9 + 5.2.1 Read . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.2.2 Update . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.2.3 Delete . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.3 Capabilities Discovery . . . . . . . . . . . . . . . . . . 11 + 5.4 Listing . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.5 Success and Failure . . . . . . . . . . . . . . . . . . . 12 + 6. Atom Publishing Protocol Documents . . . . . . . . . . . . . 13 + 6.1 Use of xml:base xml:lang . . . . . . . . . . . . . . . . . 13 + 6.2 Collection Documents . . . . . . . . . . . . . . . . . . . 14 + 6.2.1 Element Definitions . . . . . . . . . . . . . . . . . 14 + 6.3 Introspection Documents . . . . . . . . . . . . . . . . . 16 + 6.3.1 Element Definitions . . . . . . . . . . . . . . . . . 17 + 7. Introspection Resource . . . . . . . . . . . . . . . . . . . 20 + 7.1 Discovery . . . . . . . . . . . . . . . . . . . . . . . . 20 + 8. Collection Resources . . . . . . . . . . . . . . . . . . . . 21 + 8.1 GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 + 8.2 POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 + 8.3 Title: Header . . . . . . . . . . . . . . . . . . . . . . 22 + 9. Entry Collections . . . . . . . . . . . . . . . . . . . . . 23 + 9.1 Editing Entry Resources . . . . . . . . . . . . . . . . . 23 + 9.2 Role of Atom Entry Elements During Editing . . . . . . . . 23 + 10. Generic Collections . . . . . . . . . . . . . . . . . . . . 25 + 10.1 Editing Generic Resources . . . . . . . . . . . . . . . 25 + 10.2 Title: Header . . . . . . . . . . . . . . . . . . . . . 25 + 11. List Resources . . . . . . . . . . . . . . . . . . . . . . . 26 + 11.1 URI Templates . . . . . . . . . . . . . . . . . . . . . 26 + 11.2 URI Template Parameters . . . . . . . . . . . . . . . . 27 + 11.2.1 \{index\} URI template variable . . . . . . . . . . 27 + 11.2.2 \{daterange\} URI template variable . . . . . . . . 27 + 11.2.3 Other URI Template parameters . . . . . . . . . . . 28 + 12. Atom Entry Extensions . . . . . . . . . . . . . . . . . . . 29 + 13. Securing the Atom Protocol . . . . . . . . . . . . . . . . . 30 + 14. Security Considerations . . . . . . . . . . . . . . . . . . 31 + 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . 32 + 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 + 16.1 Normative References . . . . . . . . . . . . . . . . . . 35 + 16.2 Informative References . . . . . . . . . . . . . . . . . 36 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 37 + A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 38 + B. Revision History . . . . . . . . . . . . . . . . . . . . . . 39 + Intellectual Property and Copyright Statements . . . . . . . 41 1. Introduction The Atom Publishing Protocol is an application-level protocol for publishing and editing Web resources using HTTP [RFC2616] and XML 1.0 [W3C.REC-xml-20040204]. -2. Notational Conventions +2. XML Namespace and Language + + The XML Namespaces URI [W3C.REC-xml-names-19990114] for the XML data + format described in this specification is: http://purl.org/atom/app# + + XML elements defined by this specification MAY have an xml:lang + attribute, whose content indicates the natural language for the + element (and its descendents). The language context is only + significant for elements and attributes declared to be "Language- + Sensitive" by this specification. Requirements regarding the content + and interpretation of xml:lang are specified in [W3C.REC-xml- + 20040204], Section 2.12. + +3. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. -3. Terminology + Some sections of this specification are illustrated with fragments of + a non-normative RELAX NG Compact schema [RNC]. However, the text of + this specification provides the definition of conformance. + + This specification uses the namespace prefix "app:" for the Namespace + URI identified in Section 2 above. It uses the namespace prefix + "atom:" for the Namespace URI identified in [AtomFormat]. Note that + choices of namespace prefix are arbitrary and not semantically + significant. + +4. Terminology + + For convenience, this protocol may be referred to as "Atom Protocol" + or "APP". This specification uses both internally. URI/IRI - A Uniform Resource Identifier and Internationalized Resource Identifier, respectively. These terms (and the distinction between them) are defined in [RFC3986] and [RFC3987]. - Resource - an item identified by a URI [W3C.REC-webarch-20041215]. - - Collection Resource - A resource that contains a listing of Member - Resources and meets the requirements in Section 5 of this - specification. + Resource - A network data object or service that can be identified + by a URI, as defined in [RFC2616]. - Member Resource - A resource whose URI is listed by a Collection - Resource. + Representation - An entity included with a request or response as + defined in [RFC2616]. -4. The Atom Publishing Protocol Model +5. The Atom Publishing Protocol Model - The Atom Publishing Protocol operates on collections of Web - resources. All collections support the same basic interactions, as - do the resources within the collections. The patterns of interaction - are based on the common HTTP verbs. + The Atom Publishing Protocol is a subset of HTTP that is used to edit + resources on the web. The APP operates on collections of Web + resources. Collections are HTTP resources, as are the members of the + collection. Both Collections and collection member resources support + the same basic interactions. The patterns of interaction are based + on the common HTTP verbs. o GET is used to retrieve a representation of a resource or perform a read-only query. - o POST is used to create a new, dynamically-named resource. + o POST is used to create a new, dynamically-named resource, or to + provide a block of data to a data-handling process. o PUT is used to update a known resource. o DELETE is used to remove a resource. -4.1 Collections +5.1 Collections The APP groups resources into "Collections", which are analogous to - the "folders" or "directories" found in many file systems. - -4.2 Discovery + folders or directories found in a file system. In the figure we have + member resources in a collection. - To discover the location of the collections exposed by an APP - service, the client must locate and request an Introspection Document - (Section 8). + +-------------------------+ + | Collection | + | | + | +----------------+ | + | | Member_A | | + | +----------------+ | + | | + | +----------------+ | + | | Member_B | | + | +----------------+ | + | | + | +----------------+ | + | | Member_C | | + | +----------------+ | + | | + | ... | + | | + | +----------------+ | + | | Member_Oldest | | + | +----------------+ | + | | + +-------------------------+ + To add a new member to a collection an appropriate representation is + POSTed to the URI of the collection resource. Here we show it being + added to the beginnng of the list. The ordering of the members of + collections is in terms of the time at which each resource was last + updated, which includes the act of creating the resource. The + ordering of collection members is covered in more detail in Section 8 + and Section 11. - Client Server + +-------------------------+ + | Collection | | | - | 1.) GET Introspection | - |------------------------------->| + POST | +----------------+ | + --------->| Member_New | | + | +----------------+ | | | - | 2.) Introspection Doc | - |<-------------------------------| + | +----------------+ | + | | Member_A | | + | +----------------+ | + | | + | +----------------+ | + | | Member_B | | + | +----------------+ | | | + | +----------------+ | + | | Member_C | | + | +----------------+ | + | | + | ... | + | | + | +----------------+ | + | | Member_Oldest | | + | +----------------+ | + | | + +-------------------------+ - 1. The client sends a GET request to the Service Description - Resource. + You'll note that up until now we haven't said what kinds of + representations we are expecting at each of the resources. There are + two kinds of collections, Entry and Generic. In Entry Collections + all the members MUST have representations as Atom Entries. For + further restrictions on Entry Collection see Section 9 The other type + of collection is a Generic Collection. Generic Collections make no + restriction on the representations of their member resources. - 2. The server responds with an Introspection Document containing the - locations of collections provided by the service. The content of - this document can vary based on aspects of the client request, - including, but not limited to, authentication credentials. +5.2 Editable Resources -4.3 Listing + All the members of a collection are Editable Resources. An Editable + resource is a resource whose available HTTP methods can be used to + retrieve, update and delete it. - Once the client has discovered the location of a collection, it can - request a listing of the collection's membership. However, - collections might be extremely large, so servers are likely to list a - small subset of the collection by default. +5.2.1 Read + + To retrieve a representation of the resource, you send a GET to the + URI of the Editable Resource. Remember that for members of Entry + Collections, the served representation will be an Atom Entry. Client Server | | - | 1.) GET to Collection URI | - |------------------------------->| + | 1.) GET to Editable Resource URI | + |------------------------------------------>| | | - | 2.) 200 OK, Atom Feed Doc | - |<-------------------------------| + | 2.) 200 OK | + |<------------------------------------------| | | - 1. The client sends a GET request to the Collection's URI. - - 2. The server responds with an Atom Feed Document containing a full - or partial listing of the collection's membership. + 1. The client sends a GET request to the member's URI. -4.4 Authoring + 2. The server responds with the representation of the resource. - After locating a collection, a client can add entries by sending a - request to the collection; other changes are accomplished by sending - HTTP requests to its member resources. +5.2.2 Update -4.4.1 Create + To update an Editable Resource the client will PUT an updated + representation to the URI of the resource. Client Server | | - | 1.) POST to Collection URI | - |------------------------------->| - | | - | 2.) 201 Created @ Location | - |<-------------------------------| + | 1.) PUT to Editable Resource URI | + |------------------------------------------>| | | + | 2.) 200 OK | + |<------------------------------------------| - 1. The client sends a representation of a member to the server via - HTTP POST. The Request URI is that of the Collection. + 1. The client PUTs an updated representation to the member's URI. - 2. The server responds with a response of "201 Created" and a - "Location" header containing the URI of the newly-created - resource. + 2. The server MAY respond with an updated representation of the + member's new state. -4.4.2 Read +5.2.3 Delete + + An Editable Resource is deleted by sending it DELETE. Note that this + also removes it from all the collections that it belonged to. Client Server | | - | 1.) GET or HEAD to Member URI | - |------------------------------->| + | 1.) DELETE to Editable Resource URI | + |------------------------------------------>| | | - | 2.) 200 OK | - |<-------------------------------| + | 2.) 200 Ok | + |<------------------------------------------| | | - 1. The client sends a GET (or HEAD) request to the member's URI. + 1. The client sends a DELETE request to the member's URI. - 2. The server responds with an appropriate representation. + 2. The server responds with successful status code. -4.4.3 Update +5.3 Capabilities Discovery + + Each collection resource responds to GET and can return a Collection + Document as it's representation. The Collection Document enumerates + the capabilities of each collection and the format is described in + Section 6.2. Client Server | | - | 1.) PUT to Member URI | + | 1.) GET to Collection | |------------------------------->| | | - | 2.) 200 OK | + | 2.) Collection Document | |<-------------------------------| + | | - 1. The client PUTs an updated representation to the member's URI. + 1. The client sends a GET request to the Collection Resource. - 2. The server responds with a representation of the member's new - state. + 2. The server responds with a Collection Document containing a + description of the capabilities of the collection. The content + of this document can vary based on aspects of the client request, + including, but not limited to, authentication credentials. -4.4.4 Delete +5.4 Listing + + Clients can request a listing of the Collection's membership. + Listing the Editable Resources that are members of a collection is + done using one of the List Resources in the Introspection Document, + utilizing the 'app:uri-template' element. The List Resource returns + Atom Feed Documents with one Atom Entry for each member resource that + match the selection criteria. This is true whether the collection is + an Entry Collection or a Generic Collection. If an Entry Collection + is being interrogated, the entries returned by a list resource SHOULD + NOT to be considered complete representations of the member + resources. See Section 11 and Section 12 for more details on the + extensions and constraints found on the entries returned from List + Resources. Client Server | | - | 1.) DELETE to Member URI | + | 1.) GET to List Resource | |------------------------------->| | | - | 2.) 204 No Content | + | 2.) 200 OK, Atom Feed Doc | |<-------------------------------| | | - 1. The client sends a DELETE request to the member's URI. + 1. The client sends a GET request to the Collection's URI. - 2. The server responds with successful status code. + 2. The server responds with an Atom Feed Document containing a full + or partial listing of the Collection's membership. -4.5 Success and Failure +5.5 Success and Failure - HTTP defines classes of response. HTTP status codes of the form 2xx - signal that a request was successful. HTTP status codes of the form - 4xx or 5xx signal that an error has occurred, and the request has - failed. Consult the HTTP specification for more detailed definitions - of each status code. + HTTP defines different classes of response, which are used by the + Atom Protocol. HTTP status codes of the form 2xx signal that a + request was successful. HTTP status codes of the form 4xx or 5xx + signal that an error has occurred, and the request has failed. + Consult the HTTP specification [RFC2616] for more detailed + definitions of each status code. -5. Collections +6. Atom Publishing Protocol Documents - An Atom Collection is a set of related resources. All members of a - collection have an "updated" property, and the collection is - considered to be ordered by this property. + This specification describes two kinds of Atom Publishing Protocol + Documents: Atom Collections Documents and Atom Introspection + Documents. -5.1 Collection Documents + An Atom Collection Document is a representation of an Atom + collection, including metadata about the collection, and some or all + of the members associated with it. Its root is the app:collection + element. - An example Collection Document. + An Atom Introspection Document represents one or more workspaces, + which describe server-defined groupings of collections. Its root is + the app:service element. + + namespace app = "..." start = appCollection | appIntrospection + + Both kinds of Atom Publishing Protocol Documents are specified in + terms of the XML Information Set, serialised as XML 1.0 ([W3C.REC- + xml-20040204]). Atom Publishing Protocol Documents MUST be well- + formed XML. This specification does not define a DTD for Atom + Protocol, and hence does not require them to be valid (in the sense + used by XML). + + Atom Collection Documents are identified with the "application/ + atomcoll+xml" media type. + + Atom Introspection Documents are identified with the "application/ + atomserv+xml" media type. + + Atom allows the use of IRIs [RFC3987], as well as URIs [RFC3986]. + Every URI is an IRI, so any URI can be used where an IRI is needed. + While IRIs must, for many protocols, be mapped to URIs prior to + dereferencing, they MUST NOT be so mapped for comparison when used in + atom:id. Section 3.1 of [RFC3987] describes how to map an IRI to a + URI when necessary. + +6.1 Use of xml:base xml:lang + + Any element defined by this specification MAY have an xml:base + attribute [W3C.REC-xmlbase-20010627]. When xml:base is used in an + Atom Publishing Protocol Document, it serves the function described + in section 5.1.1 of [RFC3986], establishing the base URI (or IRI) for + resolving any relative references found within the effective scope of + the xml:base attribute. + + Any element defined by this specification MAY have an xml:lang + attribute, whose content indicates the natural language for the + element and its descendents. The language context is only + significant for elements and attributes declared to be "Language- + Sensitive" by this specification. Requirements regarding the content + and interpretation of xml:lang are specified in XML 1.0 ([W3C.REC- + xml-20040204]), Section 2.12. + + appCommonAttributes = + attribute xml:base { atomUri }?, + attribute xml:lang { atomLanguageTag }?, + undefinedAttribute* + +6.2 Collection Documents + + The Collection Document describes the capabilities of a Collection, + the types of Entries that it will support, the URI Templates it + supports. + + The Collection Document has the media-type 'application/atomcoll+xml' + (see Section 15). + + Here's an example document: - - - - - - + + entry + http://example.org/{index} + http://example.org/{daterange} + - Atom Collection Documents have the media-type 'application/ - atomcoll+xml', see Section 11. + This example says the Collection contains Atom Entry documents, and + that there are two means of selecting entries using what are called + 'URI Templates'; one based on the collection's order, and another + based on dates. See Section 11.1 for more about URI Templates. -5.1.1 Element Definitions +6.2.1 Element Definitions -5.1.1.1 The 'app:collection' Element +6.2.1.1 The 'app:collection' Element - The 'app:collection' element represents an Atom Collection. A - collection document does not necessarily list every member of the - collection. + The app:collection is the document element of a Collection Document. - appCollection element app:collection { - attribute next { text } ?, - appMember* + appCollection = + element app:collection { + appCommonAttributes, + ( appMemberType+ + appSearchTemplate + & anyElement* ) } - o 'app:collection' elements MAY contain any number of 'app:member' - elements. - o 'app:collection' elements MAY contain a 'next' attribute which - identifies a collection document containing member elements - updated earlier in time. + This specification defines two child elements for app:collection: - The members listed in a collection document MUST constitute a - consecutive sequence of the collection's members, ordered by their - "updated" properties. That is, a collection document MUST contain a - contiguous subset of the members of the collection ordered by their - 'updated' property. + o app:member-type: any number of elements listing the types of + Entries that the Collection may contain. -5.1.1.2 The 'app:member' Element + o app:uri-template: any number of URI Templates for a List Resource + (See Section 11). - The 'app:member' represents a single member resource. +6.2.1.2 The 'app:member-type' Element - appMember element app:member { - attribute title { text }, - attribute href { text }, - attribute hrefreadonly { text } ?, - attribute updated { text } + The app:member-type element contains information elements about the + types of Entries that the Collection may contain. + + appMember = + element app:member-type { + appCommonAttributes, + appTypeValue } - o 'app:member' elements MUST include an 'href' attribute, whose - value conveys the URI used to edit the member source + The element content of an app:member-type MUST be a string that is + non-empty, and matches either the "isegment-nz-nc" or the "IRI" + production in [RFC3987]. Note that use of a relative reference other + than a simple name is not allowed. If a name is given, + implementations MUST consider the link relation type to be equivalent + to the same name registered within the IANA Registry of Member Types + (Section 15), and thus the IRI that would be obtained by appending + the value of the rel attribute to the string + "http://www.iana.org/assignments/entrytype/". - o 'app:member' elements MAY include an "hrefreadonly - (Section 5.1.1.3)" attribute. + The content of an app:member-type specifies constraints on the + Entries that may appear in the Collection. The app:collection + element MAY have multiple app:member-type elements. An Entry POSTed + to a Collection MUST meet the constraints of at least one of the app: + member-type constraints. It MAY meet more than one, but the minimum + requirement is at least one. - o 'app:member' elements MUST include a 'title' attribute, whose - value is a human-readable name or description for the item. + This specification defines two initial values for app:member-type + IANA registry: - o 'app:member' elements MUST include an 'updated' attribute, whose - value is the 'updated' property of the collection member. Its - format MUST conform to the date-time production in [RFC3339]. + o "entry" - The Collection is an Entry Collection as defined in + Section 9. -5.1.1.3 The 'hrefreadonly' Attribute + o "generic" - The Collection is a Generic Collection as defined in + Section 10. - This optional attribute identifies a URI which, on a GET request, - responds equivalently to how the "href" URI would respond to the same - request. Clients SHOULD NOT apply to this URI any HTTP methods that - would be expected to modify the state of the resource (e.g. PUT, - POST or DELETE). A PUT or POST request to this URI MAY NOT affect - the underlying resource. If the "hrefreadonly" attribute is not - given, its value defaults to the "href" value. If the "hrefreadonly" - attribute is present, and its value is an empty string, then there is - no URI that can be treated in the way such a value would be treated. +6.2.1.3 The 'app:uri-template' Element - Clients SHOULD use the "href" value to manipulate the resource within - the context of the APP itself. Clients SHOULD prefer the - "hrefreadonly" value in any other context. For example, if the - resource is an image, a client may replace the image data using a PUT - on the "href" value, and may even display a preview of the image by - fetching the "href" URI. But when creating a public, read-only - reference to the same image resource, the client should use the - "hrefreadonly" value. If the "hrefreadonly" value is an empty - string, the client SHOULD NOT make public reference to the "href" - value. + The element content of an app:uri-template is a URI Template for a + List Resource (See Section 11). Every List resource, whose URI is + determined by filling in the parameters in a URI Template, MUST + return an Atom feed document as its representation. This Atom feed + document MUST NOT contain entries which do not match the selection + criteria. - [[anchor10: Define extensibility for Collection Documents.]] +6.3 Introspection Documents -5.2 Collection Resource + In order for authoring to commence, a client must first discover the + capabilities and locations of collections offered. - This specification defines two HTTP methods for use with collection - resources: GET and POST. + The Introspection Document describes "workspaces", which are server- + defined groupings of collections. There is no requirement that + servers support multiple workspaces, and a collection may appear in + more than one workspace. -5.2.1 GET + The Introspection Document has the media-type 'application/ + atomserv+xml', see Section 15 - Collections can contain extremely large numbers of resources. A - naive client such as a web spider or web browser would be overwhelmed - if the response to a GET reflected the full membership of the - collection, and the server would waste large amounts of bandwidth and - processing time on clients unable to handle the response. As a - result, responses to a simple GET request represent a server- - determined subset of the collection's membership. + Here's an example document: - In addition, the client MAY send a 'Range' header with a range type - of 'udpated', indicating the subset of the collection to be returned. - The 'Range' header is described in Section 5.2.4. + + + + + + + + + + + - This specification defines two serializations for Atom Collections. - Servers MUST provide both, but MAY also provide additional - serializations. + This example says there are two workspaces, each consisting of two + collections. The first workspace is called 'Mail', and has two + collections, called 'My Blog Entries' and 'Documents' whose locations + are 'http://example.org/reilly/feed' and + 'http://example.org/reilly/pic'. 'My Blog Entries' contains Atom + Entries and 'Documents' contains Generic Entries. The second + workspace is called 'Side Bar Blog' and also has two collections, + called 'Entries' and 'Books' whose locations are + 'http://example.org/reilly/feed' and + 'http://example.org/reilly/booklist'. 'Entries' contains Atom + Entries and 'Books' contains Generic Entries (since its contents + attribute is not present you MUST assume it is a Generic Collection). - 1. Atom Collection Documents (application/atomcoll+xml), - Section 5.1. +6.3.1 Element Definitions - 2. Atom Collection Documents wrapped by a SOAP envelope - (application/soap+xml), . +6.3.1.1 The 'app:service' Element - Clients use the HTTP 'Accept' request header to indicate their - preference. + The "app:service" element is the document element of a Introspection + Document, acting as a container for service data associated with one + or more workspaces. An app:service elements MAY contain any number + of app:workspace elements. - Example Request, with Accept header + appService = + element app:service { + appCommonAttributes, + ( appWorkspace* + & anyElement* ) + } - GET /collection HTTP/1.1 - Host: example.org - User-Agent: Agent/1.0 - Accept: application/atomcoll+xml +6.3.1.2 The 'app:workspace' Element - Here, the server could return any subset of the collection as an Atom - Collection Document. + The 'workspace' element contains information elements about the + collections of resources available for editing. The app:workspace + elements MAY contain any number of app:collection elements. - Example Response, Atom Collection Document + appWorkspace = + element app:workspace { + appCommonAttributes, + attribute title { text }, + ( appCollection* + & anyElement* ) + } - HTTP/1.1 200 OK - Date: Fri, 25 Mar 2005 17:15:33 GMT - Last-Modified: Mon, 04 Oct 2004 18:31:45 GMT - ETag: "2b3f6-a4-5b572640" - Accept-Ranges: updated - Content-Length: nnnn - Content-Type: application/atomcoll+xml; charset="utf-8" +6.3.1.2.1 The 'title' Attribute - - - ... - - ... - + The app:workspace element MUST contain a 'title' attribute, which + conveys a human-readable name for the workspace. This attribute is + Language-Sensitive. - Example Request, with SOAP Accept header +6.3.1.3 The 'app:collection' Element - GET /collection HTTP/1.1 - Host: example.org - User-Agent: Cosimo/1.0 - Accept: application/soap+xml + The 'app:collection' element describes collections and their member + resources. - Here, the server could return any subset of the collection as an Atom - Feed Document wrapped by a SOAP envelope. + appCollection = + element app:collection { + appCommonAttributes, + attribute title { text }, + attribute href { text }, + attribute contents { text }, + anyElement* + } - Example Response, Atom Feed Document wrapped by a SOAP envelope +6.3.1.3.1 The 'title' Attribute - HTTP/1.1 200 OK - Date: Fri, 25 Mar 2005 17:15:33 GMT - Last-Modified: Mon, 04 Oct 2004 18:31:45 GMT - ETag: "2b3f6-a4-5b572640-89" - Accept-Ranges: bytes - Content-Length: nnnn - Content-Type: application/soap+xml; charset="utf-8" + The app:collection element MUST contain a 'title' attribute, whose + value conveys a human-readable name for the workspace. This + attribute is Language-Sensitive. - - - - - - ... - - ... - - - +6.3.1.3.2 The 'href' Attribute -5.2.2 POST + The app:collection element MUST contain an 'href' attribute, whose + value conveys the IRI of the collection. - In addition to GET, a Collection Resource also accepts POST requests. - The client POSTs a representation of the desired resource to the - Collection Resource. Note that some collections only allow members - of a specific media-type and a POST MAY generate a response with a - status code of 415 ("Unsupported Media Type"). +6.3.1.3.3 The 'contents' Attribute - In the case of a successful creation, the status code MUST be 201 - ("Created"). + The app:collection element MAY contain a 'contents' attribute. The + 'contents' attribute conveys the nature of a collection's member + resources. This specification defines two initial values for the + 'contents' attribute: - Example Request, Create a resource in a collection. + o 'entry': A value of 'entry' for the contents attribute indicates + that the Collection is an Entry Collection (Section 9). - POST /collection HTTP/1.1 + o 'generic': A value of 'generic' for the contents attribute + indicates that the Collection is a Generic Collection + (Section 10). + + If the attribute is not present, its value MUST be considered to be + 'generic'. + +7. Introspection Resource + + To retrieve an Introspection Document, the client sends a GET request + to its URI. + + GET /service-desc HTTP/1.1 Host: example.org User-Agent: Cosimo/1.0 - Accept: application/atomcoll+xml - Content-Type: image/png - Content-Length: nnnn - Name: trip-to-beach.png + Accept: application/atomserv+xml - ...binary data... + The server responds to a GET request by returning an Introspection + Document in the message body. - Here, the client is adding a new image resource to a collection. The - Name: header indicates the client's desired name for the resource, - see Section 5.2.6. + HTTP/1.1 200 OK + Date: Mon, 21 Mar 2005 19:20:19 GMT + Server: CountBasic/2.0 + Last-Modified: Mon, 21 Mar 2005 19:17:26 GMT + ETag: "4c083-268-423f1dc6" + Content-Length: nnnn + Content-Type: application/atomserv+xml - Example Response, resource created successfully. + + + ... + - HTTP/1.1 201 Created - Date: Fri, 25 Mar 2005 17:17:11 GMT - Content-Length: nnnn - Content-Type: application/atomcoll+xml; charset="utf-8" - Location: http://example.org/images/trip-to-the-beach-01.png +7.1 Discovery - - - - + [[anchor18: Add in desc of an HTML link element that points to the + Introspection Resource, or add it to the autodisco draft]] -5.2.3 Usage Scenarios +8. Collection Resources - These scenarios illustrate common idioms for interactin with - Collections. + An Atom Collection is a set of related resources. All members of a + collection have an "app:updated" property, and the Collection is + considered to be ordered by this property. - The Atom Collection can be used by clients in two ways. In the first - case the client encounters a Collection for the first time and is - doing an initial syncronization, that is, retrieving a list of all - the members of the collections and possibly retrieving all the - members of the collection also. The client can perform a non-partial - GET on the collection resource and it will receive a collection - document that either contains all the members of the collection, or - the collection document root element 'collection' will contain a - 'next' attribute pointing to the next collection document. By - repeatedly following the 'next' attribute from document to document - the client can find all the members of the collection. + This specification defines two HTTP methods for use with collection + resources: GET and POST. - In the second case the client has already done an initial sync, and - now needs to re-sync, because the client was just restarted, or some - time has passed since a re-sync, etc. The client does a partial GET - on the collection document, supplying a Range header that begins from - the last time the client sync'd to the current time. The collection - document returned will contain only those members of the collection - that have changed since the last time the client syncronized. +8.1 GET -5.2.4 Range: Header + A GET to a Collection Resource returns a Collection Document, + outlining the Collection. Collection Documents are described in + Section 6.2. - HTTP/1.1 allows a client to request that only part (a range of) the - collection to be included within the response. HTTP/1.1 uses range - units in the Range header field. A collection can be broken down - into subranges according to the members 'updated' property. If a - Range: header is present in the request, its value explictly - identifies the a time interval interval in which all the members - 'updated' property must fall to be included in the response. +8.2 POST - Range = "Range" ":" ranges-specifier + In addition to GET, a Collection Resource also accepts POST requests. + The client POSTs a representation of the desired resource to the + Collection Resource. Note that some collections may impose + constraints on the media-types that are created in a Collection and + MAY generate a response with a status code of 415 ("Unsupported Media + Type"). - The value of the Range: header should be a pair of ISO 8601 dates, - separated by a slash character; either date may be optionally - omitted, in which case the range is understood as stretching to - infinity on that end. + In the case of a successful creation, the status code MUST be 201 + ("Created"). - ranges-specifier = updated-ranges-specifier - updated-ranges-specifier = updated-unit "=" updated-range - updated-unit = "updated" - updated-range = [iso-date] "/" [iso-date] + Every successful POST MUST return a Location: header with the URI of + the newly created resource. - The response to a collection request MUST be a collection document, - all of whose 'member' elements fall within the requested range. The - request range is considered a closed set, that is, if a 'member' - element matches one end of the range exactly it MUST be included in - the response. If no members fall in the requested range, the server - MUST respond with a collection document containing no 'member' - elements. + Here's an example. Below, the client requests to create a resource + in a Collection: - The inclusion of the Range: header in a request changes the request - to a "partial GET" [RFC2616]. + POST /edit HTTP/1.1 + Host: example.org + User-Agent: Cosimo/1.0 + Accept: application/atom+xml + Content-Type: application/atom+xml + Content-Length: 601 -5.2.5 Accept-Ranges: Header + + Mars Attacks! + + Why cant we all just... get along? + + + The President + http://www.example.org/blog + + +

+ Why can't we...work out our differences? + Why can't we...work things out? + Little people...why can't we all just...get along? +

+ + - The response to a non-partial GET request MUST include an Accept- - Ranges header that indicates that the server accepts 'updated' range - requests. + The resource is created by sending an Atom Entry as the entity body. - Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges - acceptable-ranges = updated-unit ( 1#range-unit ) + Assuming the server created the resource successfully, it sends back + a 201 Created response with a Location: header that contains the IRI + of the newly created member as an Editable Resource. -5.2.6 Name: Header + HTTP/1.1 201 Created + Date: Fri, 7 Oct 2005 17:17:11 GMT + Content-Length: 663 + Content-Type: application/atom+xml; charset="utf-8" + Location: http://example.org/edit/first-post.atom - [[anchor13: this is new...]] +8.3 Title: Header - The POST to a Collection Resource MAY contain a Name: header that + The POST to a Collection Resource MAY contain a Title: header that indicates the clients suggested name for the resource. The server - MAY ignore the Name: header or modify the requested name to suit + MAY ignore the Title: header or modify the requested name to suit local conventions. - Name = "Name" ":" relative-part - - The relative-part production is defined in [RFC3986]. + Title = "Title" ":" [text] -6. Entry Collection +9. Entry Collections Entry Collections are Collections that restrict their membership to - Atom entries. This specification defines two serializations for Atom - entries. Servers MUST provide both serializations. - - 1. Atom Entry Documents (application/atom+xml), [AtomFormat]. - - 2. Atom Entry Documents wrapped by a SOAP envelope (application/ - soap+xml), . - - Clients use the HTTP 'Accept' request header to indicate their - preference [RFC2616]. If no 'Accept' header is present in the - request, the server is free to choose any serialization. When an - HTTP request contains a body, clients MUST include a 'Content-Type' - header, and servers MUST accept both application/atom+xml and - application/soap+xml message bodies. + Atom entries. -6.1 Editing Entry Resources +9.1 Editing Entry Resources Atom entries are edited by sending HTTP requests to an individual entry's URI. Servers can determine the processing necessary to interpret a request by examining the request's HTTP method and 'Content-Type' header. - If the request method is POST and the 'Content-Type' is application/ - soap+xml, the SOAP document MUST contain a Web-Method property . - This specifcation defines two values for that property, PUT and - DELETE. - Processing Client Requests - +----------------------------------+------+--------+--------+--------+ + +-----------+------+--------+--------+------+ | | GET | PUT | DELETE | POST | - +----------------------------------+------+--------+--------+--------+ + +-----------+------+--------+--------+------+ | No Body | Read | x | Delete | x | | | | | | | | Atom Body | x | Update | x | x | - | | | | | | - | SOAP Body with Web-Method PUT | x | x | x | Update | - | | | | | | - | SOAP Body with Web-Method DELETE | x | x | x | Delete | - +----------------------------------+------+--------+--------+--------+ + +-----------+------+--------+--------+------+ -6.2 Role of Atom Entry Elements During Editing +9.2 Role of Atom Entry Elements During Editing The elements of an Atom Entry Document are either a 'Writable Element' or a 'Round Trip Element'. Writable Element - An element of an Atom Entry whose value is editable by the client and not enforced by the server. Round Trip Element - An element of an Atom Entry whose value is enforced by the server and not editable by the client. @@ -669,277 +809,300 @@ | | | | atom:summary | Writable | | | | | atom:title | Writable | | | | | atom:updated | Round Trip | +--------------------+------------+ Table 2 -7. Generic Collection +10. Generic Collections Generic Collections are Collections that do not have uniform restrictions on the representations of the member resources. -7.1 Editing Generic Resources +10.1 Editing Generic Resources Member resources are edited by sending HTTP requests to an individual resource's URI. Servers can determine the processing necessary to interpret a request by examining the request's HTTP method and 'Content-Type' header. Processing Client Requests +----------+------+--------+--------+------+ | | GET | PUT | DELETE | POST | +----------+------+--------+--------+------+ | No Body | Read | x | Delete | x | | | | | | | | Any Body | x | Update | x | x | +----------+------+--------+--------+------+ -8. Introspection + When a List resource returns an Atom Feed enumerating the contents of + a Generic Collection, all the Entries MUST have an atom:content + element with a 'src' attribute. - In order for authoring to commence, a client must first discover the - capabilities and locations of collections offered. +10.2 Title: Header -8.1 Introspection Document + The POST to a Generic Collection Resource MAY contain a Title: header + that indicates the clients suggested title for the resource. The + server MAY ignore the Title: header or modify the requested title to + suit local conventions. - The Introspection Document describes "workspaces", which are server- - defined groupings of collections. There is no requirement that - servers support multiple workspaces, and a collection may appear in - more than one workspace. + Title = "Title" ":" [text] - The Introspection Document has the media-type 'application/ - atomserv+xml', see Section 11 +11. List Resources - - - - - - - - - - - + List resources are resources which are identified by URI templates + indicating selection criteria. They can be used where clients + require fine control over the range or size of a server's response. + A list resource MUST return an Atom feed document as its + representation. The entries in the returned document MUST be ordered + by their 'atom:updated' property, with the most recently updated + entries coming first in the document order. Clients MUST NOT assume + that the entry returned in the feed is a full representation of a + member resource. If the entry is an Editable Resource then the + client should perform a GET on the member resource before editing. -8.1.1 Element Definitions + note: in this section some URIs carry across onto the next line; this + is indicated by a '\' -8.1.1.1 The 'app:service' Element +11.1 URI Templates - The "service" element is the document element of a Service Document, - acting as a container for service data associated with one or more - workspaces. + URI Templates are a mechanism for declaring criteria against a list + resource. By itself a URI Template is not a valid URI. Instead + there are multiple parameters embedded in the URI and distinguished + by closing braces which can be populated and used as selection + criteria. The value of each app:uri-template element in a Collection + document is a URI Template. - appService element app:service { - ( appWorkspace* - & anyElement* ) - } + Each URI template has one or more parameters that MUST be substituted + with values to construct a valid URI. The substitution MUST ensure + that the resulting value is also properly percent-encoded utf-8. - The following child elements are defined by this specification: + Here are some examples of template URIs and corresponding populated + values: - o app:service elements MAY contain any number of app:workspace - elements. + http://example.org/blog/edit/{index} + http://example.org/blog/edit/3-9 -8.1.1.2 The 'app:workspace' Element + http://example.org/blog/edit/{index}/foo + http://example.org/blog/edit/0-100/foo - The 'workspace' element element contains information elements about - the collections of resources available for editing. + http://example.org/blog/edit/{daterange} + http://example.org/blog/edit/daterange=\ + 2003-12-13T18:30:02Z-2003-12-13T18:30:02Z - appWorkspace element app:workspace { - attribute title { text }, - ( appCollection* - & anyElement* ) - } + http://example.org/blog/edit?dr={daterange}/bar/ + http://example.org/blog/edit?dr=\ + 2003-12-13T18:30:02Z,2003-12-13T18:30:02Z/bar/ - The following attributes and child elements are defined by this - specification: + Note that the parameters MAY appear at any place in the URI template. - o app:workspace elements MUST contain a 'title' attribute, which - conveys a human-readable name for the workspace +11.2 URI Template Parameters - o app:workspace elements MAY contain any number of app:collection - elements. + This specification defines two parameters for use in URI Templates: -8.1.1.3 The 'app:collection' Element + o index: allows selection into a collection's resources based as + though ordered by their 'atom:updated' property. - The 'app:collection' element describes collections and their member - resources. + o daterange: allows selection into a collection's resources based on + their 'atom:updated' property - [[anchor19: We have a collection element that's different than the - root element of the collection document. Messy. --R. Sayre]] + In both cases, the response to the selection request MUST be an Atom + Feed where all the entries fall within the requested criteria. The + request range is considered a closed set - if an entry matches one + end of the range exactly it MUST be included in the response. If no + members fall in the requested range, the server MUST respond with an + Atom Feed containing no entries. - appCollection element app:collection { - attribute title { text }, - attribute contents { text }, - attribute href { text }, - anyElement* - } + A Collection Document MUST contain at least two app:uri-template + elements - one for the {index} parameter template and the other for + the {daterange} parameter template. The two parameters are not + mutually exclusive and MAY appear together in a single Template URI. - The following attributes are defined by this specification: +11.2.1 \{index\} URI template variable - o app:collection elements MUST contain a 'title' attribute, whose - value conveys a human-readable name for the workspace + The value of the {index} criterion MUST be a pair of non-negative + integer indices separated by a dash character. One or other index + MAY omitted, in which case the range is understood as stretching to + zero, or infinity. - o app:collection elements MAY contain a 'contents' attribute - (Section 8.1.1.3.1). If it is not present, it's value is - considered to be 'generic'. + index-specifier = [index] "-" [index] - o app:collection elements MUST contain an 'href' attribute, whose - value conveys the URI of the collection. + For example, suppose the client is supplied this {index} URI + template: -8.1.1.3.1 The 'contents' Attribute + http://example.org/blog/edit/{index} - The 'contents' attribute conveys the nature of a collection's member - resources. This specification defines two initial values for the - 'contents' attribute: + If the client wants the first 15 entries in the Collection it would + substitute the brace-delimited parameter {index}, with the value + 1-15, giving: - o entry + http://example.org/blog/edit/1-15 - o generic +11.2.2 \{daterange\} URI template variable - Extensibility for 'content' values is handled [[anchor20: Same as - atom:link]]. + A URI Template with the variable 'daterange' allows querying for Atom + Entries in a Collection according to their 'atom:updated' property. -8.1.1.3.1.1 entry + The value of the {daterange} criterion should be a pair of ISO + formatted dates separated by a dash character; either index may be + optionally omitted, in which case the range is understood as + stretching to infinity on that end. - A value of 'entry' for the contents attribute indicates that the - Collection is an Entry Collection (Section 6). + daterange-specifier = [iso-date] "," [iso-date] -8.1.1.3.1.2 generic + The [iso-date] terminal MUST conform to the "date-time" production in + [RFC3339]. In addition, an uppercase "T" character MUST be used to + separate date and time, and an uppercase "Z" character MUST be + present in the absence of a numeric time zone offset. - A value of 'generic' for the contents attribute indicates that the - Collection is a Generic Collection (Section 7). + For example, suppose the client is supplied this {daterange} URI + Template: -8.2 Introspection Resource + http://example.org/blog/edit/{daterange} - To retrieve an Introspection Document, the client sends a GET request - to its URI. + If the client wants the entries in the collection between January and + February 2006 it would substitute the brace-delimited parameter + {daterange} with the desired selection value, giving this URI: - GET /service-desc HTTP/1.1 - Host: example.org - User-Agent: Cosimo/1.0 - Accept: application/atomserv+xml + http://example.org/blog/edit/2006-01-01T00:00:00Z,\ + 2006-02-01T00:00:00Z - The server responds to a GET request by returning an Introspection - Document in the message body. +11.2.3 Other URI Template parameters - HTTP/1.1 200 OK - Date: Mon, 21 Mar 2005 19:20:19 GMT - Server: CountBasic/2.0 - Last-Modified: Mon, 21 Mar 2005 19:17:26 GMT - ETag: "4c083-268-423f1dc6" - Content-Length: nnnn - Content-Type: application/atomserv+xml + Other specifications MAY define new parameters for use in URI + templates and declared in the app:uri-template element. - - - ... - +12. Atom Entry Extensions -8.2.1 Discovery + This specification adds three new values to the Registry of Link + Relations. - [[anchor24: Add in desc of an HTML link element that points to the - Introspection Resource, or add it to the autodisco draft]] + The value of 'collection' signifies that the IRI in the value of the + href is the Collection that this Entry belongs to. Any entry MAY + contain a link with a relation of 'collection'. -9. Securing the Atom Protocol + The value of 'edit' signifies that the IRI in the value of the href + attribute identifies the resource that is used to edit the entry. + That is, it is the URI of the Entry as an Editable Resource. + + The value of 'srcedit' signifies that the IRI in the value of the + href attribute identifies the resource that is used to edit the + resource pointed to by the 'src' attribute of the atom:content + element. That is, it is the IRI of the atom:content@src as an + Editable Resource. If a link element with a relation of "srcedit" is + not given, then it's value defaults to the "src" attribute of the + content element. List Resources for Generic Collections MUST return + entries that have 'srcedit' links or MUST have a atom:content@src + value. + + If the "srcedit" link is present, and it's value is an empty string, + then there is no URI that can be treated in the way such a value + would be treated. + + Clients SHOULD use the "srcedit" value to manipulate the resource + within the context of the APP itself. Clients SHOULD prefer the + "atom:content@src" value in any other context. For example, if the + resource is an image, a client may replace the image data using a PUT + on the "srcedit" value, and may even display a preview of the image + by fetching the "srcedit" URI. But when creating a public, read-only + reference to the same image resource, the client should use the + "atom:content@src" value. + +13. Securing the Atom Protocol All instances of publishing Atom entries SHOULD be protected by authentication to prevent posting or editing by unknown sources. Atom servers and clients MUST support one of the following authentication mechanisms, and SHOULD support both. o HTTP Digest Authentication [RFC2617] o [@@TBD@@ CGI Authentication ref] Atom servers and clients MAY support encryption of the Atom session using TLS [RFC2246]. There are cases where an authentication mechanism may not be required, such as a publicly editable Wiki, or when using the PostURI to post comments to a site that does not require authentication to create comments. -9.1 [@@TBD@@ CGI Authentication] +13.1 [@@TBD@@ CGI Authentication] This authentication method is included as part of the protocol to allow Atom servers and clients that cannot use HTTP Digest Authentication but where the user can both insert its own HTTP headers and create a CGI program to authenticate entries to the server. This scenario is common in environments where the user cannot control what services the server employs, but the user can write their own HTTP services. -10. Security Considerations +14. Security Considerations Because Atom is a publishing protocol, it is important that only authorized users can create and edit entries. The security of Atom is based on HTTP Digest Authentication and/or [@@TBD@@ CGI Authentication]. Any weaknesses in either of these - authentication schemes will obviously affect the security of the Atom + authentication schemes will affect the security of the Atom Publishing Protocol. Both HTTP Digest Authentication and [@@TBD@@ CGI Authentication] are susceptible to dictionary-based attacks on the shared secret. If the shared secret is a password (instead of a random string with sufficient entropy), an attacker can determine the secret by exhaustively comparing the authenticating string with hashed results of the public string and dictionary entries. See RFC 2617 for more detailed description of the security properties of HTTP Digest Authentication. @@TBD@@ Talk here about using HTTP basic and digest authentication. @@TBD@@ Talk here about denial of service attacks using large XML files, or the billion laughs DTD attack. -11. IANA Considerations +15. IANA Considerations A Atom Collection Document, when serialized as XML 1.0, can be identified with the following media type: MIME media type name: application MIME subtype name: atomcoll+xml Mandatory parameters: None. Optional parameters: "charset": This parameter has identical semantics to the charset parameter of the "application/xml" media type as specified in [RFC3023]. Encoding considerations: Identical to those of "application/xml" as described in [RFC3023], section 3.2. Security considerations: As defined in this specification. - [[anchor28: update upon publication]] + [[anchor31: update upon publication]] In addition, as this media type uses the "+xml" convention, it shares the same security considerations as described in [RFC3023], section 10. Interoperability considerations: There are no known interoperability issues. - Published specification: This specification. [[anchor29: update upon + Published specification: This specification. [[anchor32: update upon publication]] Applications that use this media type: No known applications currently use this media type. Additional information: Magic number(s): As specified for "application/xml" in [RFC3023], section 3.2. @@ -971,30 +1134,30 @@ Optional parameters: "charset": This parameter has identical semantics to the charset parameter of the "application/xml" media type as specified in [RFC3023]. Encoding considerations: Identical to those of "application/xml" as described in [RFC3023], section 3.2. Security considerations: As defined in this specification. - [[anchor30: update upon publication]] + [[anchor33: update upon publication]] In addition, as this media type uses the "+xml" convention, it shares the same security considerations as described in [RFC3023], section 10. Interoperability considerations: There are no known interoperability issues. - Published specification: This specification. [[anchor31: update upon + Published specification: This specification. [[anchor34: update upon publication]] Applications that use this media type: No known applications currently use this media type. Additional information: Magic number(s): As specified for "application/xml" in [RFC3023], section 3.2. @@ -1005,30 +1168,30 @@ Base URI: As specified in [RFC3023], section 6. Macintosh File Type code: TEXT Person and email address to contact for further information: Joe Gregorio Intended usage: COMMON - Author/Change controller: This specification's author(s). [[anchor32: + Author/Change controller: This specification's author(s). [[anchor35: update upon publication]] -12. References +16. References -12.1 Normative References +16.1 Normative References [AtomFormat] Nottingham, M. and R. Sayre, "The Atom Syndication - Format", work-in-progress, April 2005. + Format", 1.0, July 2005. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. @@ -1044,36 +1207,32 @@ [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource Identifiers (IRIs)", RFC 3987, January 2005. - [W3C.REC-soap12-part1-20030624] - Nielsen, H., Mendelsohn, N., Gudgin, M., Hadley, M., and - J. Moreau, "SOAP Version 1.2 Part 1: Messaging Framework", - W3C REC REC-soap12-part1-20030624, June 2003. - - [W3C.REC-soap12-part2-20030624] - Nielsen, H., Hadley, M., Moreau, J., Mendelsohn, N., and - M. Gudgin, "SOAP Version 1.2 Part 2: Adjuncts", W3C - REC REC-soap12-part2-20030624, June 2003. - [W3C.REC-xml-20040204] Yergeau, F., Paoli, J., Sperberg-McQueen, C., Bray, T., and E. Maler, "Extensible Markup Language (XML) 1.0 (Third Edition)", W3C REC REC-xml-20040204, February 2004. -12.2 Informative References + [W3C.REC-xml-names-19990114] + Hollander, D., Bray, T., and A. Layman, "Namespaces in + XML", W3C REC REC-xml-names-19990114, January 1999. + +16.2 Informative References + + [RNC] Clark, J., "RELAX NG Compact Syntax", December 2001. [W3C.REC-webarch-20041215] Walsh, N. and I. Jacobs, "Architecture of the World Wide Web, Volume One", W3C REC REC-webarch-20041215, December 2004. URIs [1] @@ -1082,26 +1241,53 @@ Joe Gregorio (editor) BitWorking, Inc 1002 Heathwood Dairy Rd. Apex, NC 27502 US Phone: +1 919 272 3764 Email: joe@bitworking.com URI: http://bitworking.com/ - Robert Sayre (editor) + Bill de hOra (editor) + Propylon Ltd. + 45 Blackbourne Square, Rathfarnham Gate + Dublin, Dublin D14 + IE - Email: rfsayre@boswijck.com - URI: http://boswijck.com + Phone: +353-1-4927444 + Email: bill.dehora@propylon.com + URI: http://www.propylon.com/ -Appendix A. Revision History +Appendix A. Contributors + + The content and concepts within are a product of the Atom community + and the Atompub Working Group. Robert Sayre was an editor for drafts + 00-04. + +Appendix B. Revision History + + draft-ietf-atompub-protocol-05 - Added: Contributors section. Added: + de hOra to editors. Fixed: typos. Added diagrams and description to + model section. Incorporates PaceAppDocuments, PaceAppDocuments2, + PaceSimplifyCollections2 (large-sized chunks of it anyhow: the + notions of Entry and Generic resources, the section 4 language on the + Protocol Model, 4.1 through 4.5.2, the notion of a Collection + document, as in Section 5 through 5.3, Section 7 "Collection + resources", Selection resources (modified from pace which talked + about search); results in major mods to Collection Documents, Section + 9.2 "Title: Header" and brokeout para to section 9.1 Editing Generic + Resources). Added XML namespace and language section. Some cleanup + of front matter. Added Language Sensitivity to some attributes. + Removed resource descriptions from terminology. Some juggling of + sections. See: + http://www.imc.org/atom-protocol/mail-archive/msg01812.html. draft-ietf-atompub-protocol-04 - Add ladder diagrams, reorganize, add SOAP interactions draft-ietf-atompub-protocol-03 - Incorporates PaceSliceAndDice3 and PaceIntrospection. draft-ietf-atompub-protocol-02 - Incorporates Pace409Response, PacePostLocationMust, and PaceSimpleResourcePosting.