draft-ietf-atompub-protocol-04.txt   draft-ietf-atompub-protocol-05.txt 
Network Working Group J. Gregorio, Ed. Network Working Group J. Gregorio, Ed.
Internet-Draft BitWorking, Inc Internet-Draft BitWorking, Inc
Expires: November 10, 2005 R. Sayre, Ed. Expires: April 14, 2006 B. de hOra, Ed.
May 9, 2005 Propylon Ltd.
October 11, 2005
The Atom Publishing Protocol The Atom Publishing Protocol
draft-ietf-atompub-protocol-04.txt draft-ietf-atompub-protocol-05.txt
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware 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 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. aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
skipping to change at page 1, line 34 skipping to change at page 1, line 35
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. 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 Notice
Copyright (C) The Internet Society (2005). Copyright (C) The Internet Society (2005).
Abstract Abstract
This memo presents a protocol for using XML (Extensible Markup This memo presents a protocol for using XML (Extensible Markup
Language) and HTTP (HyperText Transport Protocol) to edit content. Language) and HTTP (HyperText Transport Protocol) to edit content.
The Atom Publishing Protocol is an application-level protocol for The Atom Publishing Protocol (APP) is an application-level protocol
publishing and editing Web resources belonging to periodically for publishing and editing Web resources. The protocol at its core
updated websites. The protocol at its core is the HTTP transport of is the HTTP transport of Atom-formatted representations. The Atom
Atom-formatted representations. The Atom format is documented in the format is documented in the Atom Syndication Format
Atom Syndication Format (draft-ietf-atompub-format-06.txt). (draft-ietf-atompub-format-11.txt).
Editorial Note Editorial Note
To provide feedback on this Internet-Draft, join the atom-protocol To provide feedback on this Internet-Draft, join the atom-protocol
mailing list (http://www.imc.org/atom-protocol/index.html) [1]. mailing list (http://www.imc.org/atom-protocol/index.html) [1].
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 4 2. XML Namespace and Language . . . . . . . . . . . . . . . . . 5
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Notational Conventions . . . . . . . . . . . . . . . . . . . 6
4. The Atom Publishing Protocol Model . . . . . . . . . . . . . . 6 4. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 7
4.1 Collections . . . . . . . . . . . . . . . . . . . . . . . 6 5. The Atom Publishing Protocol Model . . . . . . . . . . . . . 8
4.2 Discovery . . . . . . . . . . . . . . . . . . . . . . . . 6 5.1 Collections . . . . . . . . . . . . . . . . . . . . . . . 8
4.3 Listing . . . . . . . . . . . . . . . . . . . . . . . . . 7 5.2 Editable Resources . . . . . . . . . . . . . . . . . . . . 9
4.4 Authoring . . . . . . . . . . . . . . . . . . . . . . . . 7 5.2.1 Read . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.4.1 Create . . . . . . . . . . . . . . . . . . . . . . . . 7 5.2.2 Update . . . . . . . . . . . . . . . . . . . . . . . . 10
4.4.2 Read . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.2.3 Delete . . . . . . . . . . . . . . . . . . . . . . . . 10
4.4.3 Update . . . . . . . . . . . . . . . . . . . . . . . . 8 5.3 Capabilities Discovery . . . . . . . . . . . . . . . . . . 11
4.4.4 Delete . . . . . . . . . . . . . . . . . . . . . . . . 8 5.4 Listing . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.5 Success and Failure . . . . . . . . . . . . . . . . . . . 9 5.5 Success and Failure . . . . . . . . . . . . . . . . . . . 12
5. Collections . . . . . . . . . . . . . . . . . . . . . . . . . 10 6. Atom Publishing Protocol Documents . . . . . . . . . . . . . 13
5.1 Collection Documents . . . . . . . . . . . . . . . . . . . 10 6.1 Use of xml:base xml:lang . . . . . . . . . . . . . . . . . 13
5.1.1 Element Definitions . . . . . . . . . . . . . . . . . 10 6.2 Collection Documents . . . . . . . . . . . . . . . . . . . 14
5.2 Collection Resource . . . . . . . . . . . . . . . . . . . 12 6.2.1 Element Definitions . . . . . . . . . . . . . . . . . 14
5.2.2 POST . . . . . . . . . . . . . . . . . . . . . . . . . 14 6.3 Introspection Documents . . . . . . . . . . . . . . . . . 16
5.2.3 Usage Scenarios . . . . . . . . . . . . . . . . . . . 15 6.3.1 Element Definitions . . . . . . . . . . . . . . . . . 17
5.2.4 Range: Header . . . . . . . . . . . . . . . . . . . . 16 7. Introspection Resource . . . . . . . . . . . . . . . . . . . 20
5.2.5 Accept-Ranges: Header . . . . . . . . . . . . . . . . 16 7.1 Discovery . . . . . . . . . . . . . . . . . . . . . . . . 20
5.2.6 Name: Header . . . . . . . . . . . . . . . . . . . . . 17 8. Collection Resources . . . . . . . . . . . . . . . . . . . . 21
6. Entry Collection . . . . . . . . . . . . . . . . . . . . . . . 18 8.1 GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
6.1 Editing Entry Resources . . . . . . . . . . . . . . . . . 18 8.2 POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
6.2 Role of Atom Entry Elements During Editing . . . . . . . . 18 8.3 Title: Header . . . . . . . . . . . . . . . . . . . . . . 22
7. Generic Collection . . . . . . . . . . . . . . . . . . . . . . 20 9. Entry Collections . . . . . . . . . . . . . . . . . . . . . 23
7.1 Editing Generic Resources . . . . . . . . . . . . . . . . 20 9.1 Editing Entry Resources . . . . . . . . . . . . . . . . . 23
8. Introspection . . . . . . . . . . . . . . . . . . . . . . . . 21 9.2 Role of Atom Entry Elements During Editing . . . . . . . . 23
8.1 Introspection Document . . . . . . . . . . . . . . . . . . 21 10. Generic Collections . . . . . . . . . . . . . . . . . . . . 25
8.1.1 Element Definitions . . . . . . . . . . . . . . . . . 21 10.1 Editing Generic Resources . . . . . . . . . . . . . . . 25
8.2 Introspection Resource . . . . . . . . . . . . . . . . . . 23 10.2 Title: Header . . . . . . . . . . . . . . . . . . . . . 25
8.2.1 Discovery . . . . . . . . . . . . . . . . . . . . . . 24 11. List Resources . . . . . . . . . . . . . . . . . . . . . . . 26
9. Securing the Atom Protocol . . . . . . . . . . . . . . . . . . 25 11.1 URI Templates . . . . . . . . . . . . . . . . . . . . . 26
10. Security Considerations . . . . . . . . . . . . . . . . . . 26 11.2 URI Template Parameters . . . . . . . . . . . . . . . . 27
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . 27 11.2.1 \{index\} URI template variable . . . . . . . . . . 27
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 11.2.2 \{daterange\} URI template variable . . . . . . . . 27
12.1 Normative References . . . . . . . . . . . . . . . . . . . 30 11.2.3 Other URI Template parameters . . . . . . . . . . . 28
12.2 Informative References . . . . . . . . . . . . . . . . . . 31 12. Atom Entry Extensions . . . . . . . . . . . . . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 32 13. Securing the Atom Protocol . . . . . . . . . . . . . . . . . 30
A. Revision History . . . . . . . . . . . . . . . . . . . . . . . 33 14. Security Considerations . . . . . . . . . . . . . . . . . . 31
Intellectual Property and Copyright Statements . . . . . . . . 35 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 1. Introduction
The Atom Publishing Protocol is an application-level protocol for The Atom Publishing Protocol is an application-level protocol for
publishing and editing Web resources using HTTP [RFC2616] and XML 1.0 publishing and editing Web resources using HTTP [RFC2616] and XML 1.0
[W3C.REC-xml-20040204]. [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", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. 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 URI/IRI - A Uniform Resource Identifier and Internationalized
Resource Identifier, respectively. These terms (and the distinction Resource Identifier, respectively. These terms (and the distinction
between them) are defined in [RFC3986] and [RFC3987]. between them) are defined in [RFC3986] and [RFC3987].
Resource - an item identified by a URI [W3C.REC-webarch-20041215]. Resource - A network data object or service that can be identified
by a URI, as defined in [RFC2616].
Collection Resource - A resource that contains a listing of Member
Resources and meets the requirements in Section 5 of this
specification.
Member Resource - A resource whose URI is listed by a Collection Representation - An entity included with a request or response as
Resource. defined in [RFC2616].
4. The Atom Publishing Protocol Model 5. The Atom Publishing Protocol Model
The Atom Publishing Protocol operates on collections of Web The Atom Publishing Protocol is a subset of HTTP that is used to edit
resources. All collections support the same basic interactions, as resources on the web. The APP operates on collections of Web
do the resources within the collections. The patterns of interaction resources. Collections are HTTP resources, as are the members of the
are based on the common HTTP verbs. 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 o GET is used to retrieve a representation of a resource or perform
a read-only query. 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 PUT is used to update a known resource.
o DELETE is used to remove a 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 APP groups resources into "Collections", which are analogous to
the "folders" or "directories" found in many file systems. folders or directories found in a file system. In the figure we have
member resources in a collection.
4.2 Discovery
To discover the location of the collections exposed by an APP +-------------------------+
service, the client must locate and request an Introspection Document | Collection |
(Section 8). | |
| +----------------+ |
| | 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 You'll note that up until now we haven't said what kinds of
Resource. 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 5.2 Editable Resources
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.
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 5.2.1 Read
request a listing of the collection's membership. However,
collections might be extremely large, so servers are likely to list a To retrieve a representation of the resource, you send a GET to the
small subset of the collection by default. URI of the Editable Resource. Remember that for members of Entry
Collections, the served representation will be an Atom Entry.
Client Server 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. 1. The client sends a GET request to the member's URI.
2. The server responds with an Atom Feed Document containing a full
or partial listing of the collection's membership.
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 5.2.2 Update
request to the collection; other changes are accomplished by sending
HTTP requests to its member resources.
4.4.1 Create To update an Editable Resource the client will PUT an updated
representation to the URI of the resource.
Client Server Client Server
| | | |
| 1.) POST to Collection URI | | 1.) PUT to Editable Resource URI |
|------------------------------->| |------------------------------------------>|
| |
| 2.) 201 Created @ Location |
|<-------------------------------|
| | | |
| 2.) 200 OK |
|<------------------------------------------|
1. The client sends a representation of a member to the server via 1. The client PUTs an updated representation to the member's URI.
HTTP POST. The Request URI is that of the Collection.
2. The server responds with a response of "201 Created" and a 2. The server MAY respond with an updated representation of the
"Location" header containing the URI of the newly-created member's new state.
resource.
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 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 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 2. The server responds with a Collection Document containing a
state. 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 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 HTTP defines different classes of response, which are used by the
signal that a request was successful. HTTP status codes of the form Atom Protocol. HTTP status codes of the form 2xx signal that a
4xx or 5xx signal that an error has occurred, and the request has request was successful. HTTP status codes of the form 4xx or 5xx
failed. Consult the HTTP specification for more detailed definitions signal that an error has occurred, and the request has failed.
of each status code. 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 This specification describes two kinds of Atom Publishing Protocol
collection have an "updated" property, and the collection is Documents: Atom Collections Documents and Atom Introspection
considered to be ordered by this property. 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:
<?xml version="1.0" encoding='utf-8'?> <?xml version="1.0" encoding='utf-8'?>
<collection xmlns="http://purl.org/atom/app#"> <app:collection xmlns:app="http://purl.org/atom/app#">
<member href="http://example.org/1" <app:member-type>entry</pub:member-type>
hrefreadonly="http://example.com/1/bar" <app:uri-template>http://example.org/{index}</pub:uri-template>
title="Sample 1" <app:uri-template>http://example.org/{daterange}</pub:uri-template>
updated="2003-12-13T18:30:02Z" /> </app:collection>
<member href="http://example.org/2"
hrefreadonly="http://example.com/2/bar"
title="Sample 2"
updated="2003-12-13T18:30:02Z" />
<member href="http://example.org/3"
hrefreadonly="http://example.com/3/bar"
title="Sample 3"
updated="2003-12-13T18:30:02Z" />
<member href="http://example.org/4"
title="Sample 4"
updated="2003-12-13T18:30:02Z" />
</collection>
Atom Collection Documents have the media-type 'application/ This example says the Collection contains Atom Entry documents, and
atomcoll+xml', see Section 11. 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 The app:collection is the document element of a Collection Document.
collection document does not necessarily list every member of the
collection.
appCollection = appCollection =
element app:collection { element app:collection {
attribute next { text } ?, appCommonAttributes,
appMember* ( 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 This specification defines two child elements for app:collection:
identifies a collection document containing member elements
updated earlier in time.
The members listed in a collection document MUST constitute a o app:member-type: any number of elements listing the types of
consecutive sequence of the collection's members, ordered by their Entries that the Collection may contain.
"updated" properties. That is, a collection document MUST contain a
contiguous subset of the members of the collection ordered by their
'updated' property.
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
The app:member-type element contains information elements about the
types of Entries that the Collection may contain.
appMember = appMember =
element app:member { element app:member-type {
attribute title { text }, appCommonAttributes,
attribute href { text }, appTypeValue
attribute hrefreadonly { text } ?,
attribute updated { text }
} }
o 'app:member' elements MUST include an 'href' attribute, whose The element content of an app:member-type MUST be a string that is
value conveys the URI used to edit the member source 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 The content of an app:member-type specifies constraints on the
(Section 5.1.1.3)" attribute. 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 This specification defines two initial values for app:member-type
value is a human-readable name or description for the item. IANA registry:
o 'app:member' elements MUST include an 'updated' attribute, whose o "entry" - The Collection is an Entry Collection as defined in
value is the 'updated' property of the collection member. Its Section 9.
format MUST conform to the date-time production in [RFC3339].
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, 6.2.1.3 The 'app:uri-template' Element
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.
Clients SHOULD use the "href" value to manipulate the resource within The element content of an app:uri-template is a URI Template for a
the context of the APP itself. Clients SHOULD prefer the List Resource (See Section 11). Every List resource, whose URI is
"hrefreadonly" value in any other context. For example, if the determined by filling in the parameters in a URI Template, MUST
resource is an image, a client may replace the image data using a PUT return an Atom feed document as its representation. This Atom feed
on the "href" value, and may even display a preview of the image by document MUST NOT contain entries which do not match the selection
fetching the "href" URI. But when creating a public, read-only criteria.
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.
[[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 The Introspection Document describes "workspaces", which are server-
resources: GET and POST. 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 Here's an example document:
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.
In addition, the client MAY send a 'Range' header with a range type <?xml version="1.0" encoding='utf-8'?>
of 'udpated', indicating the subset of the collection to be returned. <app:service xmlns:app="http://purl.org/atom/app#">
The 'Range' header is described in Section 5.2.4. <app:workspace title="Main Site" >
<app:collection contents="entries"
title="My Blog Entries"
href="http://example.org/reilly/feed" />
<app:collection contents="generic"
title="Documents"
href="http://example.org/reilly/pic" />
</app:workspace>
<app:workspace title="Side Bar Blog">
<app:collection contents="entries" title="Entries"
href="http://example.org/reilly/feed" />
<app:collection contents="http://example.net/booklist"
title="Books"
href="http://example.org/reilly/books" />
</app:workspace>
</app:service>
This specification defines two serializations for Atom Collections. This example says there are two workspaces, each consisting of two
Servers MUST provide both, but MAY also provide additional collections. The first workspace is called 'Mail', and has two
serializations. 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), 6.3.1 Element Definitions
Section 5.1.
2. Atom Collection Documents wrapped by a SOAP envelope 6.3.1.1 The 'app:service' Element
(application/soap+xml), .
Clients use the HTTP 'Accept' request header to indicate their The "app:service" element is the document element of a Introspection
preference. 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 6.3.1.2 The 'app:workspace' Element
Host: example.org
User-Agent: Agent/1.0
Accept: application/atomcoll+xml
Here, the server could return any subset of the collection as an Atom The 'workspace' element contains information elements about the
Collection Document. 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 6.3.1.2.1 The 'title' Attribute
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"
<?xml version="1.0" encoding="utf-8"?> The app:workspace element MUST contain a 'title' attribute, which
<collection xmlns="http://purl.org/atom/app#"> conveys a human-readable name for the workspace. This attribute is
... Language-Sensitive.
<member href="http://example.org/1"
hrefreadonly="http://example.com/1/bar"
title="Example 1"
updated="2003-12-13T18:30:02Z" />
...
</collection>
Example Request, with SOAP Accept header 6.3.1.3 The 'app:collection' Element
GET /collection HTTP/1.1 The 'app:collection' element describes collections and their member
Host: example.org resources.
User-Agent: Cosimo/1.0
Accept: application/soap+xml
Here, the server could return any subset of the collection as an Atom appCollection =
Feed Document wrapped by a SOAP envelope. 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 The app:collection element MUST contain a 'title' attribute, whose
Date: Fri, 25 Mar 2005 17:15:33 GMT value conveys a human-readable name for the workspace. This
Last-Modified: Mon, 04 Oct 2004 18:31:45 GMT attribute is Language-Sensitive.
ETag: "2b3f6-a4-5b572640-89"
Accept-Ranges: bytes
Content-Length: nnnn
Content-Type: application/soap+xml; charset="utf-8"
<?xml version="1.0" encoding="utf-8"?> 6.3.1.3.2 The 'href' Attribute
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header />
<env:Body>
<collection xmlns="http://purl.org/atom/app#">
...
<member href="http://example.org/1"
hrefreadonly="http://example.com/1/bar"
title="Example 1"
updated="2003-12-13T18:30:02Z" />
...
</collection>
</env:Body>
</env:Envelope>
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. 6.3.1.3.3 The 'contents' Attribute
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").
In the case of a successful creation, the status code MUST be 201 The app:collection element MAY contain a 'contents' attribute. The
("Created"). '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 Host: example.org
User-Agent: Cosimo/1.0 User-Agent: Cosimo/1.0
Accept: application/atomcoll+xml Accept: application/atomserv+xml
Content-Type: image/png
Content-Length: nnnn
Name: trip-to-beach.png
...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 HTTP/1.1 200 OK
Name: header indicates the client's desired name for the resource, Date: Mon, 21 Mar 2005 19:20:19 GMT
see Section 5.2.6. 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. <?xml version="1.0" encoding='utf-8'?>
<app:service xmlns:app="http://purl.org/atom/app#">
...
</app:service>
HTTP/1.1 201 Created 7.1 Discovery
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
<?xml version="1.0" encoding="UTF-8"?> [[anchor18: Add in desc of an HTML link element that points to the
<collection xmlns="http://purl.org/atom/app#"> Introspection Resource, or add it to the autodisco draft]]
<member href="http://example.org/images/trip-to-beach.png"
hrefreadonly="http://example.com/ed/im/trip-01.png"
title="trip-to-beach.png"
updated="2005-03-25T17:17:09Z" />
</collection>
5.2.3 Usage Scenarios 8. Collection Resources
These scenarios illustrate common idioms for interactin with An Atom Collection is a set of related resources. All members of a
Collections. 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 This specification defines two HTTP methods for use with collection
case the client encounters a Collection for the first time and is resources: GET and POST.
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.
In the second case the client has already done an initial sync, and 8.1 GET
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.
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 8.2 POST
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.
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, In the case of a successful creation, the status code MUST be 201
separated by a slash character; either date may be optionally ("Created").
omitted, in which case the range is understood as stretching to
infinity on that end.
ranges-specifier = updated-ranges-specifier Every successful POST MUST return a Location: header with the URI of
updated-ranges-specifier = updated-unit "=" updated-range the newly created resource.
updated-unit = "updated"
updated-range = [iso-date] "/" [iso-date]
The response to a collection request MUST be a collection document, Here's an example. Below, the client requests to create a resource
all of whose 'member' elements fall within the requested range. The in a Collection:
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.
The inclusion of the Range: header in a request changes the request POST /edit HTTP/1.1
to a "partial GET" [RFC2616]. 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 <atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
<atom:title>Mars Attacks!</atom:title>
<atom:summary type="html">
Why cant we all just... get along?
</atom:summary>
<atom:author>
<atom:name>The President</atom:name>
<atom:uri>http://www.example.org/blog</atom:uri>
</atom:author>
<atom:content type="html" xml:lang="en"
xml:base="http://www.example.org/blog/">
<p>
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?
</p>
</atom:content>
</atom:entry>
The response to a non-partial GET request MUST include an Accept- The resource is created by sending an Atom Entry as the entity body.
Ranges header that indicates that the server accepts 'updated' range
requests.
Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges Assuming the server created the resource successfully, it sends back
acceptable-ranges = updated-unit ( 1#range-unit ) 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 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. local conventions.
Name = "Name" ":" relative-part Title = "Title" ":" [text]
The relative-part production is defined in [RFC3986].
6. Entry Collection 9. Entry Collections
Entry Collections are Collections that restrict their membership to Entry Collections are Collections that restrict their membership to
Atom entries. This specification defines two serializations for Atom Atom entries.
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.
6.1 Editing Entry Resources 9.1 Editing Entry Resources
Atom entries are edited by sending HTTP requests to an individual Atom entries are edited by sending HTTP requests to an individual
entry's URI. Servers can determine the processing necessary to entry's URI. Servers can determine the processing necessary to
interpret a request by examining the request's HTTP method and interpret a request by examining the request's HTTP method and
'Content-Type' header. '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 Processing Client Requests
+----------------------------------+------+--------+--------+--------+ +-----------+------+--------+--------+------+
| | GET | PUT | DELETE | POST | | | GET | PUT | DELETE | POST |
+----------------------------------+------+--------+--------+--------+ +-----------+------+--------+--------+------+
| No Body | Read | x | Delete | x | | No Body | Read | x | Delete | x |
| | | | | | | | | | | |
| Atom Body | x | Update | x | 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 The elements of an Atom Entry Document are either a 'Writable
Element' or a 'Round Trip Element'. Element' or a 'Round Trip Element'.
Writable Element - An element of an Atom Entry whose value is Writable Element - An element of an Atom Entry whose value is
editable by the client and not enforced by the server. editable by the client and not enforced by the server.
Round Trip Element - An element of an Atom Entry whose value is Round Trip Element - An element of an Atom Entry whose value is
enforced by the server and not editable by the client. enforced by the server and not editable by the client.
skipping to change at page 20, line 5 skipping to change at page 25, line 5
| | | | | |
| atom:summary | Writable | | atom:summary | Writable |
| | | | | |
| atom:title | Writable | | atom:title | Writable |
| | | | | |
| atom:updated | Round Trip | | atom:updated | Round Trip |
+--------------------+------------+ +--------------------+------------+
Table 2 Table 2
7. Generic Collection 10. Generic Collections
Generic Collections are Collections that do not have uniform Generic Collections are Collections that do not have uniform
restrictions on the representations of the member resources. 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 Member resources are edited by sending HTTP requests to an individual
resource's URI. Servers can determine the processing necessary to resource's URI. Servers can determine the processing necessary to
interpret a request by examining the request's HTTP method and interpret a request by examining the request's HTTP method and
'Content-Type' header. 'Content-Type' header.
Processing Client Requests Processing Client Requests
+----------+------+--------+--------+------+ +----------+------+--------+--------+------+
| | GET | PUT | DELETE | POST | | | GET | PUT | DELETE | POST |
+----------+------+--------+--------+------+ +----------+------+--------+--------+------+
| No Body | Read | x | Delete | x | | No Body | Read | x | Delete | x |
| | | | | | | | | | | |
| Any Body | x | Update | x | 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 10.2 Title: Header
capabilities and locations of collections offered.
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- Title = "Title" ":" [text]
defined groupings of collections. There is no requirement that
servers support multiple workspaces, and a collection may appear in
more than one workspace.
The Introspection Document has the media-type 'application/ 11. List Resources
atomserv+xml', see Section 11
<?xml version="1.0" encoding='utf-8'?> List resources are resources which are identified by URI templates
<service xmlns="http://purl.org/atom/app#"> indicating selection criteria. They can be used where clients
<workspace title="Main Site" > require fine control over the range or size of a server's response.
<collection contents="entries" title="My Blog Entries" A list resource MUST return an Atom feed document as its
href="http://example.org/reilly/feed" /> representation. The entries in the returned document MUST be ordered
<collection contents="generic" title="Documents" by their 'atom:updated' property, with the most recently updated
href="http://example.org/reilly/pic" /> entries coming first in the document order. Clients MUST NOT assume
</workspace> that the entry returned in the feed is a full representation of a
<workspace title="Side Bar Blog"> member resource. If the entry is an Editable Resource then the
<collection contents="entries" title="Entries" client should perform a GET on the member resource before editing.
href="http://example.org/reilly/feed" />
<collection contents="http://example.net/booklist" title="Books"
href="http://example.org/reilly/books" />
</workspace>
</service>
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, URI Templates are a mechanism for declaring criteria against a list
acting as a container for service data associated with one or more resource. By itself a URI Template is not a valid URI. Instead
workspaces. 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 = Each URI template has one or more parameters that MUST be substituted
element app:service { with values to construct a valid URI. The substitution MUST ensure
( appWorkspace* that the resulting value is also properly percent-encoded utf-8.
& anyElement* )
}
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 http://example.org/blog/edit/{index}
elements. 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 http://example.org/blog/edit/{daterange}
the collections of resources available for editing. http://example.org/blog/edit/daterange=\
2003-12-13T18:30:02Z-2003-12-13T18:30:02Z
appWorkspace = http://example.org/blog/edit?dr={daterange}/bar/
element app:workspace { http://example.org/blog/edit?dr=\
attribute title { text }, 2003-12-13T18:30:02Z,2003-12-13T18:30:02Z/bar/
( appCollection*
& anyElement* )
}
The following attributes and child elements are defined by this Note that the parameters MAY appear at any place in the URI template.
specification:
o app:workspace elements MUST contain a 'title' attribute, which 11.2 URI Template Parameters
conveys a human-readable name for the workspace
o app:workspace elements MAY contain any number of app:collection This specification defines two parameters for use in URI Templates:
elements.
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 o daterange: allows selection into a collection's resources based on
resources. their 'atom:updated' property
[[anchor19: We have a collection element that's different than the In both cases, the response to the selection request MUST be an Atom
root element of the collection document. Messy. --R. Sayre]] 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 = A Collection Document MUST contain at least two app:uri-template
element app:collection { elements - one for the {index} parameter template and the other for
attribute title { text }, the {daterange} parameter template. The two parameters are not
attribute contents { text }, mutually exclusive and MAY appear together in a single Template URI.
attribute href { text },
anyElement*
}
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 The value of the {index} criterion MUST be a pair of non-negative
value conveys a human-readable name for the workspace 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 index-specifier = [index] "-" [index]
(Section 8.1.1.3.1). If it is not present, it's value is
considered to be 'generic'.
o app:collection elements MUST contain an 'href' attribute, whose For example, suppose the client is supplied this {index} URI
value conveys the URI of the collection. 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 If the client wants the first 15 entries in the Collection it would
resources. This specification defines two initial values for the substitute the brace-delimited parameter {index}, with the value
'contents' attribute: 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 A URI Template with the variable 'daterange' allows querying for Atom
atom:link]]. 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 daterange-specifier = [iso-date] "," [iso-date]
Collection is an Entry Collection (Section 6).
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 For example, suppose the client is supplied this {daterange} URI
Collection is a Generic Collection (Section 7). Template:
8.2 Introspection Resource http://example.org/blog/edit/{daterange}
To retrieve an Introspection Document, the client sends a GET request If the client wants the entries in the collection between January and
to its URI. February 2006 it would substitute the brace-delimited parameter
{daterange} with the desired selection value, giving this URI:
GET /service-desc HTTP/1.1 http://example.org/blog/edit/2006-01-01T00:00:00Z,\
Host: example.org 2006-02-01T00:00:00Z
User-Agent: Cosimo/1.0
Accept: application/atomserv+xml
The server responds to a GET request by returning an Introspection 11.2.3 Other URI Template parameters
Document in the message body.
HTTP/1.1 200 OK Other specifications MAY define new parameters for use in URI
Date: Mon, 21 Mar 2005 19:20:19 GMT templates and declared in the app:uri-template element.
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
<?xml version="1.0" encoding='utf-8'?> 12. Atom Entry Extensions
<service xmlns="http://purl.org/atom/app#">
...
</service>
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 The value of 'collection' signifies that the IRI in the value of the
Introspection Resource, or add it to the autodisco draft]] 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 All instances of publishing Atom entries SHOULD be protected by
authentication to prevent posting or editing by unknown sources. authentication to prevent posting or editing by unknown sources.
Atom servers and clients MUST support one of the following Atom servers and clients MUST support one of the following
authentication mechanisms, and SHOULD support both. authentication mechanisms, and SHOULD support both.
o HTTP Digest Authentication [RFC2617] o HTTP Digest Authentication [RFC2617]
o [@@TBD@@ CGI Authentication ref] o [@@TBD@@ CGI Authentication ref]
Atom servers and clients MAY support encryption of the Atom session Atom servers and clients MAY support encryption of the Atom session
using TLS [RFC2246]. using TLS [RFC2246].
There are cases where an authentication mechanism may not be There are cases where an authentication mechanism may not be
required, such as a publicly editable Wiki, or when using the PostURI required, such as a publicly editable Wiki, or when using the PostURI
to post comments to a site that does not require authentication to to post comments to a site that does not require authentication to
create comments. create comments.
9.1 [@@TBD@@ CGI Authentication] 13.1 [@@TBD@@ CGI Authentication]
This authentication method is included as part of the protocol to This authentication method is included as part of the protocol to
allow Atom servers and clients that cannot use HTTP Digest allow Atom servers and clients that cannot use HTTP Digest
Authentication but where the user can both insert its own HTTP Authentication but where the user can both insert its own HTTP
headers and create a CGI program to authenticate entries to the headers and create a CGI program to authenticate entries to the
server. This scenario is common in environments where the user server. This scenario is common in environments where the user
cannot control what services the server employs, but the user can cannot control what services the server employs, but the user can
write their own HTTP services. write their own HTTP services.
10. Security Considerations 14. Security Considerations
Because Atom is a publishing protocol, it is important that only Because Atom is a publishing protocol, it is important that only
authorized users can create and edit entries. authorized users can create and edit entries.
The security of Atom is based on HTTP Digest Authentication and/or The security of Atom is based on HTTP Digest Authentication and/or
[@@TBD@@ CGI Authentication]. Any weaknesses in either of these [@@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. Publishing Protocol.
Both HTTP Digest Authentication and [@@TBD@@ CGI Authentication] are Both HTTP Digest Authentication and [@@TBD@@ CGI Authentication] are
susceptible to dictionary-based attacks on the shared secret. If the susceptible to dictionary-based attacks on the shared secret. If the
shared secret is a password (instead of a random string with shared secret is a password (instead of a random string with
sufficient entropy), an attacker can determine the secret by sufficient entropy), an attacker can determine the secret by
exhaustively comparing the authenticating string with hashed results exhaustively comparing the authenticating string with hashed results
of the public string and dictionary entries. of the public string and dictionary entries.
See RFC 2617 for more detailed description of the security properties See RFC 2617 for more detailed description of the security properties
of HTTP Digest Authentication. of HTTP Digest Authentication.
@@TBD@@ Talk here about using HTTP basic and digest authentication. @@TBD@@ Talk here about using HTTP basic and digest authentication.
@@TBD@@ Talk here about denial of service attacks using large XML @@TBD@@ Talk here about denial of service attacks using large XML
files, or the billion laughs DTD attack. 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 A Atom Collection Document, when serialized as XML 1.0, can be
identified with the following media type: identified with the following media type:
MIME media type name: application MIME media type name: application
MIME subtype name: atomcoll+xml MIME subtype name: atomcoll+xml
Mandatory parameters: None. Mandatory parameters: None.
Optional parameters: Optional parameters:
"charset": This parameter has identical semantics to the charset "charset": This parameter has identical semantics to the charset
parameter of the "application/xml" media type as specified in parameter of the "application/xml" media type as specified in
[RFC3023]. [RFC3023].
Encoding considerations: Identical to those of "application/xml" as Encoding considerations: Identical to those of "application/xml" as
described in [RFC3023], section 3.2. described in [RFC3023], section 3.2.
Security considerations: As defined in this specification. 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 In addition, as this media type uses the "+xml" convention, it
shares the same security considerations as described in [RFC3023], shares the same security considerations as described in [RFC3023],
section 10. section 10.
Interoperability considerations: There are no known interoperability Interoperability considerations: There are no known interoperability
issues. issues.
Published specification: This specification. [[anchor29: update upon Published specification: This specification. [[anchor32: update upon
publication]] publication]]
Applications that use this media type: No known applications Applications that use this media type: No known applications
currently use this media type. currently use this media type.
Additional information: Additional information:
Magic number(s): As specified for "application/xml" in [RFC3023], Magic number(s): As specified for "application/xml" in [RFC3023],
section 3.2. section 3.2.
skipping to change at page 28, line 35 skipping to change at page 33, line 35
Optional parameters: Optional parameters:
"charset": This parameter has identical semantics to the charset "charset": This parameter has identical semantics to the charset
parameter of the "application/xml" media type as specified in parameter of the "application/xml" media type as specified in
[RFC3023]. [RFC3023].
Encoding considerations: Identical to those of "application/xml" as Encoding considerations: Identical to those of "application/xml" as
described in [RFC3023], section 3.2. described in [RFC3023], section 3.2.
Security considerations: As defined in this specification. 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 In addition, as this media type uses the "+xml" convention, it
shares the same security considerations as described in [RFC3023], shares the same security considerations as described in [RFC3023],
section 10. section 10.
Interoperability considerations: There are no known interoperability Interoperability considerations: There are no known interoperability
issues. issues.
Published specification: This specification. [[anchor31: update upon Published specification: This specification. [[anchor34: update upon
publication]] publication]]
Applications that use this media type: No known applications Applications that use this media type: No known applications
currently use this media type. currently use this media type.
Additional information: Additional information:
Magic number(s): As specified for "application/xml" in [RFC3023], Magic number(s): As specified for "application/xml" in [RFC3023],
section 3.2. section 3.2.
skipping to change at page 29, line 22 skipping to change at page 34, line 22
Base URI: As specified in [RFC3023], section 6. Base URI: As specified in [RFC3023], section 6.
Macintosh File Type code: TEXT Macintosh File Type code: TEXT
Person and email address to contact for further information: Joe Person and email address to contact for further information: Joe
Gregorio <joe@bitworking.org> Gregorio <joe@bitworking.org>
Intended usage: COMMON Intended usage: COMMON
Author/Change controller: This specification's author(s). [[anchor32: Author/Change controller: This specification's author(s). [[anchor35:
update upon publication]] update upon publication]]
12. References 16. References
12.1 Normative References 16.1 Normative References
[AtomFormat] [AtomFormat]
Nottingham, M. and R. Sayre, "The Atom Syndication 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 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
RFC 2246, January 1999. RFC 2246, January 1999.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
skipping to change at page 30, line 41 skipping to change at page 35, line 41
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, July 2002. Timestamps", RFC 3339, July 2002.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
Identifiers (IRIs)", RFC 3987, January 2005. 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] [W3C.REC-xml-20040204]
Yergeau, F., Paoli, J., Sperberg-McQueen, C., Bray, T., Yergeau, F., Paoli, J., Sperberg-McQueen, C., Bray, T.,
and E. Maler, "Extensible Markup Language (XML) 1.0 (Third and E. Maler, "Extensible Markup Language (XML) 1.0 (Third
Edition)", W3C REC REC-xml-20040204, February 2004. 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] [W3C.REC-webarch-20041215]
Walsh, N. and I. Jacobs, "Architecture of the World Wide Walsh, N. and I. Jacobs, "Architecture of the World Wide
Web, Volume One", W3C REC REC-webarch-20041215, Web, Volume One", W3C REC REC-webarch-20041215,
December 2004. December 2004.
URIs URIs
[1] <http://www.imc.org/atom-protocol/index.html> [1] <http://www.imc.org/atom-protocol/index.html>
skipping to change at page 32, line 21 skipping to change at page 37, line 21
Joe Gregorio (editor) Joe Gregorio (editor)
BitWorking, Inc BitWorking, Inc
1002 Heathwood Dairy Rd. 1002 Heathwood Dairy Rd.
Apex, NC 27502 Apex, NC 27502
US US
Phone: +1 919 272 3764 Phone: +1 919 272 3764
Email: joe@bitworking.com Email: joe@bitworking.com
URI: http://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 Phone: +353-1-4927444
URI: http://boswijck.com 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 draft-ietf-atompub-protocol-04 - Add ladder diagrams, reorganize, add
SOAP interactions SOAP interactions
draft-ietf-atompub-protocol-03 - Incorporates PaceSliceAndDice3 and draft-ietf-atompub-protocol-03 - Incorporates PaceSliceAndDice3 and
PaceIntrospection. PaceIntrospection.
draft-ietf-atompub-protocol-02 - Incorporates Pace409Response, draft-ietf-atompub-protocol-02 - Incorporates Pace409Response,
PacePostLocationMust, and PaceSimpleResourcePosting. PacePostLocationMust, and PaceSimpleResourcePosting.
 End of changes. 

This html diff was produced by rfcdiff 1.12, available from http://www.levkowetz.com/ietf/tools/rfcdiff/