draft-ietf-atompub-protocol-06.txt   draft-ietf-atompub-protocol-07.txt 
Network Working Group J. Gregorio, Ed. Network Working Group J. Gregorio, Ed.
Internet-Draft BitWorking, Inc Internet-Draft BitWorking, Inc
Expires: April 30, 2006 B. de hOra, Ed. Expires: July 5, 2006 B. de hOra, Ed.
Propylon Ltd. Propylon Ltd.
October 27, 2005 January 01, 2006
The Atom Publishing Protocol The Atom Publishing Protocol
draft-ietf-atompub-protocol-06.txt draft-ietf-atompub-protocol-07.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 35 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 April 30, 2006. This Internet-Draft will expire on July 5, 2006.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2005). Copyright (C) The Internet Society (2006).
Abstract Abstract
The Atom Publishing Protocol (APP) is an application-level protocol The Atom Publishing Protocol (APP) is an application-level protocol
for publishing and editing Web resources. The protocol is based on for publishing and editing Web resources. The protocol is based on
HTTP transport of Atom-formatted representations. The Atom format is HTTP transport of Atom-formatted representations. The Atom format is
documented in the Atom Syndication Format documented in the Atom Syndication Format (RFC4287).
(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 . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Notational Conventions . . . . . . . . . . . . . . . . . . . 5 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 5
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 6
4. Protocol Model . . . . . . . . . . . . . . . . . . . . . . . 7 4. Protocol Model . . . . . . . . . . . . . . . . . . . . . . . 7
5. Protocol Operations . . . . . . . . . . . . . . . . . . . . 8 5. Protocol Operations . . . . . . . . . . . . . . . . . . . . 8
5.1 Retrieving an Introspection Document . . . . . . . . . . . 8 5.1 Retrieving an Introspection Document . . . . . . . . . . . 8
5.2 Creating a Resource . . . . . . . . . . . . . . . . . . . 8 5.2 Creating a Resource . . . . . . . . . . . . . . . . . . . 8
5.3 Editing a Resource . . . . . . . . . . . . . . . . . . . . 8 5.3 Editing a Resource . . . . . . . . . . . . . . . . . . . . 8
5.3.1 Retrieving a Resource . . . . . . . . . . . . . . . . 9 5.3.1 Retrieving a Resource . . . . . . . . . . . . . . . . 9
5.3.2 Updating a Resource . . . . . . . . . . . . . . . . . 9 5.3.2 Updating a Resource . . . . . . . . . . . . . . . . . 9
5.3.3 Deleting a Resource . . . . . . . . . . . . . . . . . 9 5.3.3 Deleting a Resource . . . . . . . . . . . . . . . . . 9
5.4 Listing Collections . . . . . . . . . . . . . . . . . . . 10 5.4 Listing Collection Members . . . . . . . . . . . . . . . . 10
5.5 Success and Failure . . . . . . . . . . . . . . . . . . . 10 5.5 Use of HTTP Response codes . . . . . . . . . . . . . . . . 10
6. XML-related Conventions . . . . . . . . . . . . . . . . . . 11 6. XML-related Conventions . . . . . . . . . . . . . . . . . . 11
6.1 Referring to Information Items . . . . . . . . . . . . . . 11 6.1 Referring to Information Items . . . . . . . . . . . . . . 11
6.2 XML Namespace Usage . . . . . . . . . . . . . . . . . . . 11 6.2 XML Namespace Usage . . . . . . . . . . . . . . . . . . . 11
6.3 RELAX NG Schema . . . . . . . . . . . . . . . . . . . . . 11 6.3 Use of xml:base and xml:lang . . . . . . . . . . . . . . . 11
6.4 Use of xml:base and xml:lang . . . . . . . . . . . . . . . 11 6.4 RELAX NG Schema . . . . . . . . . . . . . . . . . . . . . 12
7. Introspection Documents . . . . . . . . . . . . . . . . . . 13 7. Introspection Documents . . . . . . . . . . . . . . . . . . 13
7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . 13 7.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . 13
7.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . 13 7.2 Element Definitions . . . . . . . . . . . . . . . . . . . 14
7.3 Element Definitions . . . . . . . . . . . . . . . . . . . 14 7.2.1 The "app:service" Element . . . . . . . . . . . . . . 14
7.3.1 The 'app:service' Element . . . . . . . . . . . . . . 14 7.2.2 The "app:workspace" Element . . . . . . . . . . . . . 14
7.3.2 The 'app:workspace' Element . . . . . . . . . . . . . 14 7.2.3 The "app:collection" Element . . . . . . . . . . . . . 15
7.3.3 The 'app:collection' Element . . . . . . . . . . . . . 15 7.2.4 The "app:member-type" Element . . . . . . . . . . . . 15
7.3.4 The 'app:member-type' Element . . . . . . . . . . . . 15 8. Collections . . . . . . . . . . . . . . . . . . . . . . . . 17
7.3.5 The 'app:list-template' Element . . . . . . . . . . . 16 8.1 Creating resources with POST . . . . . . . . . . . . . . . 17
8. Collections . . . . . . . . . . . . . . . . . . . . . . . . 18 8.1.1 Example . . . . . . . . . . . . . . . . . . . . . . . 17
8.1 Creating resources with POST . . . . . . . . . . . . . . . 18 8.1.2 Title: Header . . . . . . . . . . . . . . . . . . . . 17
8.1.1 Title: Header . . . . . . . . . . . . . . . . . . . . 18 8.2 Entry Collections . . . . . . . . . . . . . . . . . . . . 18
8.2 Entry Collections . . . . . . . . . . . . . . . . . . . . 19 8.3 Media Collections . . . . . . . . . . . . . . . . . . . . 18
8.2.1 Role of Atom Entry Elements During Editing . . . . . . 19 8.3.1 Editing Media Resources . . . . . . . . . . . . . . . 18
8.3 Media Collections . . . . . . . . . . . . . . . . . . . . 20 9. Listing Collections . . . . . . . . . . . . . . . . . . . . 19
8.3.1 Editing Media Resources . . . . . . . . . . . . . . . 20 9.1 Collection Paging . . . . . . . . . . . . . . . . . . . . 19
9. Listing Collections . . . . . . . . . . . . . . . . . . . . 21 10. Atom Format Link Relation Extensions . . . . . . . . . . . . 21
10. Atom Entry Extensions . . . . . . . . . . . . . . . . . . . 23 10.1 The "edit" Link Relation . . . . . . . . . . . . . . . . 21
10.1 The 'edit' Link Relation . . . . . . . . . . . . . . . . 23 11. Atom Publishing Control Extensions . . . . . . . . . . . . . 22
10.2 Publishing Control . . . . . . . . . . . . . . . . . . . 23 11.1 The Atom Publishing Control Namespace . . . . . . . . . 22
10.2.1 The app:draft Element . . . . . . . . . . . . . . . 24 11.2 The "pub:control" Element . . . . . . . . . . . . . . . 22
11. Example . . . . . . . . . . . . . . . . . . . . . . . . . . 25 11.2.1 The "pub:draft" Element . . . . . . . . . . . . . . 22
12. Securing the Atom Protocol . . . . . . . . . . . . . . . . . 27 12. Atom Publishing Protocol Example . . . . . . . . . . . . . . 23
13. Security Considerations . . . . . . . . . . . . . . . . . . 28 13. Securing the Atom Protocol . . . . . . . . . . . . . . . . . 25
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . 29 14. Security Considerations . . . . . . . . . . . . . . . . . . 26
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . 27
15.1 Normative References . . . . . . . . . . . . . . . . . . 31 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 29
15.2 Informative References . . . . . . . . . . . . . . . . . 32 16.1 Normative References . . . . . . . . . . . . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 33 16.2 Informative References . . . . . . . . . . . . . . . . . 30
A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 34 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 31
B. RELAX NG Compact Schema . . . . . . . . . . . . . . . . . . 35 A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 32
C. Revision History . . . . . . . . . . . . . . . . . . . . . . 38 B. RELAX NG Compact Schema . . . . . . . . . . . . . . . . . . 33
Intellectual Property and Copyright Statements . . . . . . . 40 C. Revision History . . . . . . . . . . . . . . . . . . . . . . 36
Intellectual Property and Copyright Statements . . . . . . . 39
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]. The protocol supports the creation of [W3C.REC-xml-20040204]. The protocol supports the creation of
arbitrary web resources and provides facilities for: arbitrary web resources and provides facilities for:
o Collections: Sets of resources, which may be retrieved in whole or o Collections: Sets of resources, which may be retrieved in whole or
in part. in part.
skipping to change at page 6, line 7 skipping to change at page 6, line 7
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
Note: The Introspection Document allows the use of IRIs [RFC3987], as Note: The Introspection Document allows the use of IRIs [RFC3987], as
well as URIs [RFC3986]. Every URI is an IRI, so any URI can be used well as URIs [RFC3986]. Every URI is an IRI, so any URI can be used
where an IRI is needed. How to map an IRI to a URI is specified in where an IRI is needed. How to map an IRI to a URI is specified in
Section 3.1 of Internationalized Resource Identifiers (IRIs) Section 3.1 of Internationalized Resource Identifiers (IRIs)
[RFC3987]. [RFC3987].
3. Terminology 3. Terminology
For convenience, this protocol may be referred to as "Atom Protocol" For convenience, this protocol may be referred to as the "Atom
or "APP". Protocol" or "APP".
URI/IRI - A Uniform Resource Identifier and Internationalized
Resource Identifier. These terms and the distinction between them
are defined in [RFC3986] and [RFC3987].
Resource - A network-accessible data object or service identified by
an IRI, as defined in [RFC2616]. See [W3C.REC-webarch-20041215] for
further discussion on resources.
The phrase "the IRI of a document" in this specification is shorthand The phrase "the IRI of a document" in this specification is shorthand
for "an IRI which, when dereferenced, is expected to produce that for "an IRI which, when dereferenced, is expected to produce that
document as a representation". document as a representation".
URI/IRI - A Uniform Resource Identifier and Internationalized Representation - An entity included with a request or response as
Resource Identifier, respectively. These terms (and the distinction
between them) are defined in [RFC3986] and [RFC3987].
resource - A network data object or service that can be identified
by a IRI, as defined in [RFC2616]. See [W3C.REC-webarch-20041215]
for further discussion on resources.
representation - An entity included with a request or response as
defined in [RFC2616]. defined in [RFC2616].
collection - A resource that contains a set of member IRIs, as Collection - A resource that contains a set of member IRIs. See
described in Section 8 of this specification. Section 8.
member - A resource whose IRI is listed in a collection.
IRI template - A parameterized string that becomes a IRI when the
parameters are filled in. See Section 9.
introspection document - A document that describes the location and
capabilities of one or more collections. See Section 7
client writable element - An element of an Atom Entry whose value is Member - A resource whose IRI is listed in a Collection.
editable by the client and not enforced by the server.
server-controlled element - An element of an Atom Entry whose value Introspection Document - A document that describes the location and
is enforced by the server and not editable by the client. capabilities of one or more Collections. See Section 7.
4. Protocol Model 4. Protocol Model
The Atom Publishing Protocol uses HTTP to edit resources on the web. The Atom Publishing Protocol uses HTTP to edit and author web
It provides a list based mechanism for managing collections of resources. The Atom Protocol uses the following HTTP methods:
editable resources called member resources. Collections contain the
IRIs and metadata describing member resources. The APP uses these
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 query. a query.
o POST is used to create a new, dynamically-named resource. o POST is used to create a new, dynamically-named resource.
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.
This diagram shows the APP model: Along with operations on resources, the Atom Protocol provides list-
based structures, called Collections, for managing and organising
+---------------+ resources, called Members. Collections contain the IRIs of, and
| Introspection | +------------+ metadata about, their Member resources. For authoring and editing of
| |-->| Collection | resources to commence, an Atom Protocol client can examine server-
+---------------+ | | defined groups of Collections, called Introspection Documents.
| | +--------+
| |-->| Member |
| | +--------+
| |
| | .
| | .
| | .
| |
| | +--------+
| |-->| Member |
| | +--------+
| |
+------------+
The introspection document contains the IRIs of one or more
collections. A collection contains IRIs and metadata describing
member resources. The protocol allows editing of resources with
representations of any media-type. Some types of collections are
specialized and restrict the resource representations of their
members.
5. Protocol Operations 5. Protocol Operations
5.1 Retrieving an Introspection Document 5.1 Retrieving an Introspection Document
Client Server Client Server
| | | |
| 1.) GET to IRI of Introspection Document | | 1.) GET to IRI of Introspection Document |
|------------------------------------------>| |------------------------------------------>|
| | | |
| 2.) Introspection Document | | 2.) Introspection Document |
|<------------------------------------------| |<------------------------------------------|
| | | |
1. The client sends a GET request to the IRI of the introspection 1. The client sends a GET request to the IRI of the Introspection
document. Document.
2. The server responds with the introspection document which 2. The server responds with the document which enumerates the IRIs
enumerates the IRIs of all the collections, and the capabilities of all the Collections and the capabilities of those Collections
of those collections, that the service supports. supported by the server. The content of this document can vary
based on aspects of the client request, including, but not
limited to, authentication credentials.
5.2 Creating a Resource 5.2 Creating a Resource
Client Server Client Server
| | | |
| 1.) POST to IRI of Collection | | 1.) POST to IRI of Collection |
|------------------------------------------>| |------------------------------------------>|
| | | |
| 2.) 201 Created | | 2.) 201 Created |
|<------------------------------------------| |<------------------------------------------|
| | | |
1. The client POSTs a representation to the IRI of the collection. 1. The client POSTs a representation of the Member to the IRI of the
collection.
2. If the member resource was created successfully the server 2. If the Member resource was created successfully, the server
responds with a status code of 201 and a Location: header that responds with a status code of 201 and a Location: header that
contains the IRI of the newly created member resource. contains the IRI of the newly created resource.
5.3 Editing a Resource 5.3 Editing a Resource
Once a resource has been created and its IRI is known, that IRI may Once a resource has been created and its IRI is known, that IRI may
be used to retrieve, update, and delete it. be used to retrieve, update, and delete the resource.
5.3.1 Retrieving a Resource 5.3.1 Retrieving a Resource
Client Server Client Server
| | | |
| 1.) GET to Member IRI | | 1.) GET to Member IRI |
|------------------------------------------>| |------------------------------------------>|
| | | |
| 2.) Member Representation | | 2.) Member Representation |
|<------------------------------------------| |<------------------------------------------|
| | | |
1. The client sends a GET request to the member's IRI to retrieve 1. The client sends a GET request to the Member's IRI to retrieve
its representation . its representation .
2. The server responds with the representation of the resource. 2. The server responds with the representation of the resource.
5.3.2 Updating a Resource 5.3.2 Updating a Resource
Client Server Client Server
| | | |
| 1.) PUT to Member IRI | | 1.) PUT to Member IRI |
|------------------------------------------>| |------------------------------------------>|
| | | |
| 2.) 200 OK | | 2.) 200 OK |
|<------------------------------------------| |<------------------------------------------|
1. The client PUTs an updated representation to the member's IRI. 1. The client PUTs an updated representation to the Member's IRI.
2. Upon a successful update of the resource the server responds with 2. Upon a successful update of the resource the server responds with
a status code of 200. a status code of 200.
5.3.3 Deleting a Resource 5.3.3 Deleting a Resource
Client Server Client Server
| | | |
| 1.) DELETE to Member Resource IRI | | 1.) DELETE to Member Resource IRI |
|------------------------------------------>| |------------------------------------------>|
| | | |
| 2.) 200 Ok | | 2.) 200 Ok |
|<------------------------------------------| |<------------------------------------------|
| | | |
1. The client sends a DELETE request to the member's IRI. 1. The client sends a DELETE request to the Member's IRI.
2. Upon the successful deletion of the resource the server responds 2. Upon the successful deletion of the resource the server responds
with a status code of 200. with a status code of 200.
Note: deleting a member also removes it from all the collections to 5.4 Listing Collection Members
which it belongs.
5.4 Listing Collections
To enumerate the members of a collection the client sends a GET to To list the members of a Collection the client sends a GET request to
its IRI. This IRI is constructed from information in the the Collection's IRI. An Atom Feed Document is returned containing
introspection document. An Atom Feed Document is returned with one one Atom Entry for each member resource. See Section 9 and
Atom Entry for each member resource that matches the selection Section 10 for a description of the feed contents.
criteria in the IRI. See Section 9 and Section 10 for a description
of the feed contents.
Client Server Client Server
| | | |
| 1.) GET to List IRI | | 1.) GET to List IRI |
|------------------------------->| |------------------------------->|
| | | |
| 2.) 200 OK, Atom Feed Doc | | 2.) 200 OK, Atom Feed Doc |
|<-------------------------------| |<-------------------------------|
| | | |
1. The client sends a GET request to the membership list IRI. 1. The client sends a GET request to the Collection's IRI.
2. The server responds with an Atom Feed Document containing the 2. The server responds with an Atom Feed Document containing the
IRIs of all the collection members that match the selection IRIs of all the collection members that match the selection
criteria. criteria.
5.5 Success and Failure 5.5 Use of HTTP Response codes
The Atom Protocol uses HTTP status codes to signal the results of The Atom Protocol uses the response status codes defined in HTTP to
protocol operations. Status codes of the form 2xx signal that a indicate the success or failure of an operation. Consult the HTTP
request was successful. HTTP status codes of the form 4xx or 5xx specification [RFC2616] for detailed definitions of each status code.
signal that an error has occurred. Consult the HTTP specification It is strongly recommended that entities contained within HTTP 4xx
[RFC2616] for the definitions of HTTP status codes. and 5xx responses include a human readable, natural language
explanation of the error.
6. XML-related Conventions 6. XML-related Conventions
The data format in this specification is specified in terms of the The data format in this specification is specified in terms of the
XML Information Set, serialised as XML 1.0 [W3C.REC-xml-20040204]. XML Information Set, serialised as XML 1.0 [W3C.REC-xml-20040204].
Atom Publishing Protocol Documents MUST be well-formed XML. This Atom Publishing Protocol Documents MUST be well-formed XML. This
specification does not define any DTDs for Atom Protocol, and hence specification does not define any DTDs for Atom Protocol, and hence
does not require them to be valid (in the sense used by XML). does not require them to be "valid" in the sense used by XML.
6.1 Referring to Information Items 6.1 Referring to Information Items
This specification uses a shorthand for two common terms: the phrase This specification uses a shorthand for two common terms: the phrase
"Information Item" is omitted when naming Element Information Items "Information Item" is omitted when discussing Element Information
and Attribute Information Items. Therefore, when this specification Items and Attribute Information Items. Therefore, when this
uses the term "element," it is referring to an Element Information specification uses the term "element," it is referring to an Element
Item in Infoset terms. Likewise, when it uses the term "attribute," Information Item in Infoset terms. Likewise, when it uses the term
it is referring to an Attribute Information Item. "attribute," it is referring to an Attribute Information Item.
6.2 XML Namespace Usage 6.2 XML Namespace Usage
The Namespace URI [W3C.REC-xml-names-19990114] for the data format The namespace name [W3C.REC-xml-names-19990114] for the XML format
described in this specification is: described in this specification is:
http://purl.org/atom/app# http://purl.org/atom/app#
This specification uses the prefix "app:" for the Namespace URI. The This specification uses the prefix "app:" for the namespace name.
choice of namespace prefix is not semantically significant. The choice of namespace prefix is not semantically significant.
This specification also uses the prefix "atom:" for the Namespace URI
identified in [AtomFormat].
6.3 RELAX NG Schema
Some sections of this specification are illustrated with fragments of This specification also uses the prefix "atom:" for
a non-normative RELAX NG Compact schema [RNC]. However, the text of "http://www.w3.org/2005/Atom", the namespace name of the Atom
this specification provides the definition of conformance. A Publishing Format [RFC4287].
complete schema appears in Appendix B.
6.4 Use of xml:base and xml:lang 6.3 Use of xml:base and xml:lang
XML elements defined by this specification MAY have an xml:base XML elements defined by this specification MAY have an xml:base
attribute [W3C.REC-xmlbase-20010627]. When xml:base is used, it attribute [W3C.REC-xmlbase-20010627]. When xml:base is used, it
serves the function described in section 5.1.1 of [RFC3986], serves the function described in section 5.1.1 of [RFC3986],
establishing the base URI (or IRI) for resolving any relative establishing the base URI (or IRI) for resolving any relative
references found within the effective scope of the xml:base references found within the effective scope of the xml:base
attribute. attribute.
Any element defined by this specification MAY have an xml:lang Any element defined by this specification MAY have an xml:lang
attribute, whose content indicates the natural language for the attribute, whose content indicates the natural language for the
element and its descendents. The language context is only element and its descendents. The language context is only
significant for elements and attributes declared to be "Language- significant for elements and attributes declared to be "Language-
Sensitive" by this specification. Requirements regarding the content Sensitive" by this specification. Requirements regarding the content
and interpretation of xml:lang are specified in Section 2.12 of XML and interpretation of xml:lang are specified in Section 2.12 of XML
1.0 [W3C.REC-xml-20040204], . 1.0 [W3C.REC-xml-20040204].
appCommonAttributes = appCommonAttributes =
attribute xml:base { atomUri }?, attribute xml:base { atomUri }?,
attribute xml:lang { atomLanguageTag }?, attribute xml:lang { atomLanguageTag }?,
undefinedAttribute* undefinedAttribute*
7. Introspection Documents 6.4 RELAX NG Schema
7.1 Introduction Some sections of this specification are illustrated with fragments of
a non-normative RELAX NG Compact schema [RNC]. A complete schema
appears in Appendix B. However, the text of this specification
provides the definition of conformance.
7. Introspection Documents
For authoring to commence, a client needs to first discover the For authoring to commence, a client needs to first discover the
capabilities and locations of collections offered. This is done capabilities and locations of collections offered. This is done
using Introspection Documents. An Introspection Document describes using Introspection Documents. An Introspection Document describes
workspaces, which are server-defined groupings of collections. workspaces, which are server-defined groupings of collections.
7.2 Example Introspection documents are identified with the "application/
atomserv+xml" media type (see Section 15).
While an introspection document allows multiple workspaces, there is
no requirement that a service support multiple workspaces. In
addition, a collection MAY appear in more than one workspace.
7.1 Example
<?xml version="1.0" encoding='utf-8'?> <?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://purl.org/atom/app#"> <service xmlns="http://purl.org/atom/app#">
<workspace title="Main Site" > <workspace title="Main Site" >
<collection <collection
title="My Blog Entries" title="My Blog Entries"
href="http://example.org/reilly/main" > href="http://example.org/reilly/main" >
<member-type>entry</member-type> <member-type>entry</member-type>
<list-template>http://example.org/{index}</list-template> <list-template>http://example.org/{index}</list-template>
</collection> </collection>
skipping to change at page 13, line 42 skipping to change at page 13, line 47
<workspace title="Side Bar Blog"> <workspace title="Side Bar Blog">
<collection title="Remaindered Links" <collection title="Remaindered Links"
href="http://example.org/reilly/list" > href="http://example.org/reilly/list" >
<member-type>entry</member-type> <member-type>entry</member-type>
<list-template>http://example.org/l/{index}</list-template> <list-template>http://example.org/l/{index}</list-template>
</collection> </collection>
</workspace> </workspace>
</service> </service>
This Introspection Document describes two workspaces. The first, This Introspection Document describes two workspaces. The first,
called 'Main Site', has two collections called 'My Blog Entries' and called "Main Site", has two collections called "My Blog Entries" and
'Pictures' whose IRIs are 'http://example.org/reilly/main' and "Pictures" whose IRIs are "http://example.org/reilly/main" and
'http://example.org/reilly/pic' respectively. 'My Blog Entries' is "http://example.org/reilly/pic" respectively. "My Blog Entries" is
an Entry collection and 'Pictures' is a Media collection. Entry and an Entry collection and "Pictures" is a Media collection. Entry and
Media collections are discussed in Section 7.3.4. Media collections are discussed in Section 7.2.4.
The second workspace is called 'Side Bar Blog' and has a single The second workspace is called "Side Bar Blog" and has a single
collection called 'Remaindered Links' whose collection IRI is collection called "Remaindered Links" whose collection IRI is
'http://example.org/reilly/list'. 'Remaindered Links' is an Entry "http://example.org/reilly/list". "Remaindered Links" is an Entry
collection. collection.
Introspection documents are identified with the "application/ 7.2 Element Definitions
atomserv+xml" media type (see Section 14).
While an introspection document allows multiple workspaces, there is
no requirement that a service support multiple workspaces. In
addition, a collection MAY appear in more than one workspace.
7.3 Element Definitions
7.3.1 The 'app:service' Element 7.2.1 The "app:service" Element
The root of an introspection document is the app:service element. The root of an introspection document is the "app:service" element.
namespace app = "http://purl.org/atom/app#" namespace app = "http://purl.org/atom/app#"
start = appService start = appService
The "app:service" element is the container for introspection The "app:service" element is the container for introspection
information associated with one or more workspaces. An app:service information associated with one or more workspaces. An app:service
element MUST contain one or more app:workspace elements. element MUST contain one or more app:workspace elements.
appService = appService =
element app:service { element app:service {
appCommonAttributes, appCommonAttributes,
( appWorkspace+ ( appWorkspace+
& extensionElement* ) & extensionElement* )
} }
7.3.2 The 'app:workspace' Element 7.2.2 The "app:workspace" Element
The 'app:workspace' element contains information elements about the The "app:workspace" element contains information elements about the
collections of resources available for editing. The app:workspace collections of resources available for editing. The app:workspace
element MUST contain one or more app:collection elements. element MUST contain one or more app:collection elements.
appWorkspace = appWorkspace =
element app:workspace { element app:workspace {
appCommonAttributes, appCommonAttributes,
attribute title { text }, attribute title { text },
( appCollection+ ( appCollection+
& extensionElement* ) & extensionElement* )
} }
7.3.2.1 The 'title' Attribute In an app:workspace element, the first app:collection element SHOULD
refer to the preferred or primary collection. In the following
example, the "Entries" collection would be considered the "preferred"
or "primary" collection of the workspace:
The app:workspace element MUST contain a 'title' attribute, which <service>
conveys a human-readable name for the workspace. This attribute is <workspace title="My Blog">
<collection title="Entries" ... >
<collection title="Photos" ... >
</workspace>
</service>
7.2.2.1 The "title" Attribute
The app:workspace element MUST contain a "title" attribute, which
gives a human-readable name for the workspace. This attribute is
Language-Sensitive. Language-Sensitive.
7.3.3 The 'app:collection' Element 7.2.3 The "app:collection" Element
The app:collection contains information elements that describe the The "app:collection" describes a collection. This specification
location and capabilities of a collection. defines one child element: app:member-type.
appCollection = appCollection =
element app:collection { element app:collection {
appCommonAttributes, appCommonAttributes,
attribute title { text }, attribute title { text },
attribute href { text }, attribute href { text },
( appMemberType ( appMemberType
& appListTemplate & appListTemplate
& extensionElement* ) & extensionElement* )
} }
7.3.3.1 The 'title' Attribute 7.2.3.1 The "title" Attribute
The app:collection element MUST contain a 'title' attribute, whose
value conveys a human-readable name for the collection. This
attribute is Language-Sensitive.
7.3.3.2 The 'href' Attribute
The app:collection element MUST contain an 'href' attribute, whose
value conveys the IRI of the collection.
This specification defines two child elements for app:collection: The app:collection element MUST contain a "title" attribute, whose
value gives a human-readable name for the collection. This attribute
is Language-Sensitive.
o app:member-type: a single element that contains the type of 7.2.3.2 The "href" Attribute
members that the collection can contain.
o app:list-template: a single element that contains a IRI template The app:collection element MUST contain a "href" attribute, whose
of a membership list. (See Section 9). value gives the IRI of the collection.
7.3.4 The 'app:member-type' Element 7.2.4 The "app:member-type" Element
The app:collection element MUST contain one 'app:member-type' The app:collection element MUST contain one "app:member-type"
element. The app:member-type element value specifies the types of element. The app:member-type element value specifies the types of
members that can appear in the collection. members that can appear in the collection.
appMemberType = appMemberType =
element app:member-type { element app:member-type {
appCommonAttributes, appCommonAttributes,
( appTypeValue ) ( appTypeValue )
} }
appTypeValue = "entry" | "media" appTypeValue = "entry" | "media"
An Entry POSTed to a collection MUST meet the constraints of the app: An Entry POSTed to a collection MUST meet the constraints of the app:
member-type element. member-type element.
This specification defines two initial values for the app:member-type This specification defines two values for the app:member-type
IANA registry: element:
o "entry" - The collection contains only member resources whose o "entry" - The collection contains only member resources whose
representation MUST be an Atom Entry. Further constraints on the representation MUST be an Atom Entry. Further constraints on the
representations of members in a collection of type "entry" are representations of members in a collection of type "entry" are
listed in Section 8.2. listed in Section 8.2.
o "media" - The collection contains member resources whose o "media" - The collection contains member resources whose
representation can be of any media type. Additional constraints representation can be of any media type. Additional constraints
are listed in Section 8.3. are listed in Section 8.3.
In general the value of 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 Link
Relations Section 14, and thus the IRI that would be obtained by
appending the value of the rel attribute to the string
"http://www.iana.org/assignments/member-type/".
7.3.5 The 'app:list-template' Element
The app:collection element MUST contain one 'app:list-template'
elements. The element content of app:list-template is an IRI
template (Section 9) for a collection.
appListTemplate =
element app:list-template {
appCommonAttributes,
( appUriTemplate )
}
appUriTemplate = xsd:string { pattern = ".+\{.+\}.*" }
8. Collections 8. Collections
8.1 Creating resources with POST 8.1 Creating resources with POST
Every collection accepts POST requests to create resources - the To add members to a collection, clients send POST requests to the
client POSTs a representation of the desired resource to the IRI of collection's URI. Collections MAY impose constraints on the media-
the collection. Collections MAY impose constraints on the media-
types that are created in a collection and MAY generate a response types that are created in a collection and MAY generate a response
with a status code of 415 ("Unsupported Media Type"). with a status code of 415 ("Unsupported Media Type"). On successful
creation, the response to the POST request MUST return a Location:
The status code returned for a successful creation POST MUST be 201 header with the URI of the newly created resource.
("Created").
A successful creation POST MUST return a Location: header with the
URI of the newly created resource.
Clients MAY POST invalid Atom for initial resource creation - 8.1.1 Example
specifically the id and link elements MAY be omitted.
Below, the client requests to create a resource in a collection: Below, the client requests to create a resource with an Atom Entry
representation in a collection:
POST /edit HTTP/1.1 POST /edit HTTP/1.1
Host: example.org Host: example.org
User-Agent: Thingio/1.0 User-Agent: Thingio/1.0
Content-Type: application/atom+xml Content-Type: application/atom+xml
Content-Length: nnn Content-Length: nnn
<entry xmlns="http://www.w3.org/2005/Atom"> <entry xmlns="http://www.w3.org/2005/Atom">
<title>Atom-Powered Robots Run Amok</title> <title>Atom-Powered Robots Run Amok</title>
<link href="http://example.org/2003/12/13/atom03"/>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2003-12-13T18:30:02Z</updated> <updated>2003-12-13T18:30:02Z</updated>
<summary>Some text.</summary> <summary>Some text.</summary>
</entry> </entry>
The resource is created by sending an Atom Entry as the entity body. The resource is created by sending an Atom Entry as the entity body.
Successful creation is indicated by a 201 created response and Successful creation is indicated by a 201 created response and
includes a Location: header. includes a Location: header:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT Date: Fri, 7 Oct 2005 17:17:11 GMT
Content-Length: 0 Content-Length: 0
Location: http://example.org/edit/first-post.atom Location: http://example.org/edit/first-post.atom
8.1.1 Title: Header 8.1.2 Title: Header
The POST to a collection MAY contain a Title: header that indicates A POST to a collection creating a resource MAY contain a Title:
the client's suggested title for the resource. The server MAY ignore header that indicates the client's suggested title for the resource.
the Title: header or modify the requested title. The Title header is primarily for use with Media collections and is
RECOMMENDED for use with such collections. The server MAY ignore the
content of the Title: header or modify the suggested title.
Title = "Title" ":" [text] Title = "Title" ":" [text]
The syntax of this header MUST conform to the augmented BNF grammar The syntax of this header MUST conform to the augmented BNF grammar
in section 2.1 of the HTTP/1.1 specification [RFC2616]. in section 2.1 of the HTTP/1.1 specification [RFC2616].
8.2 Entry Collections 8.2 Entry Collections
Entry Collections are collections that restrict their membership to Entry Collections are collections that restrict their membership to
Atom Entries. They are identified by having an app:member-type of Atom Entries. They are identified by having an app:member-type of
"entry". Every member representation MUST contain an atom:link "entry". Every member representation MUST contain an atom:link
element with a relation of rel="edit" that contains the IRI of the element with a link relation of "edit" that contains the IRI of the
member resource. Member representations MAY contain an app:control member resource. Member representations MAY contain an app:control
element (Section 10.2). element (Section 11).
8.2.1 Role of Atom Entry Elements During Editing
The elements of an Atom Entry Document are either a client writable
or server controlled.
Client Writable - An element of an Atom Entry whose value is editable
by the client. Servers MAY modify the content of client writable
elements. Some reasons that a server may change client writable
content include length limits, obscenity filters or the addition of
boilerplate text.
Server Controlled - An element of an Atom Entry whose value is
enforced by the server and not editable by the client. Clients
SHOULD NOT change the value of server controlled elements. Servers
MUST NOT rely on clients preserving the values of server controlled
elements.
+--------------------+--------------------+
| Atom Entry Element | Property |
+--------------------+--------------------+
| atom:author | Client Writable |
| | |
| atom:category | Client Writable |
| | |
| atom:content | Client Writable |
| | |
| atom:contributor | Client Writable |
| | |
| atom:id | Server Controlled |
| | |
| atom:link | Client Writable |
| | |
| atom:published | Client Writable |
| | |
| atom:source | Client Writable |
| | |
| atom:summary | Client Writable |
| | |
| atom:title | Client Writable |
| | |
| atom:updated | Server Controlled |
| | |
| app:control | Client Writable |
+--------------------+--------------------+
Table 1
8.3 Media Collections 8.3 Media Collections
Media Collections are collections whose member representations are Media Collections are collections whose member representations are
not constrained. They are identified by having an app:member-type of not constrained. They are identified by having an app:member-type of
"media". "media".
8.3.1 Editing Media Resources 8.3.1 Editing Media Resources
When a membership list resource returns an Atom Feed enumerating the When a membership list resource returns an Atom Feed enumerating the
contents of a Media Collection, all the Entries MUST have an atom: contents of a Media Collection, all the Entries MUST have an atom:
content element with a 'src' attribute. When creating a public, content element with a "src" attribute. When creating a public,
read-only reference to the member resource, a client SHOULD use the read-only reference to the member resource, a client SHOULD use the
"atom:content/@src" attribute value. "atom:content/@src" attribute value.
9. Listing Collections 9. Listing Collections
Collections, as identified in an Introspection Document, are Collections, as identified in an Introspection Document, are
resources that MUST provide representations in the form of Atom Feed resources that MUST provide representations in the form of Atom Feed
documents. The entries in the returned Feed MUST be ordered by their documents when dereferencing the collection IRI. The entries in the
'atom:updated' property, with the most recently updated entries returned Feed MUST be ordered by their 'atom:updated' property, with
coming first in the document order. Every entry in the Feed Document the most recently updated entries coming first in the document order.
MUST have an atom:link element with a relation of "edit" (See Every entry in the Feed Document MUST have an atom:link element with
Section 10.1). Clients MUST NOT assume that an Atom Entry returned a relation of "edit" (See Section 10.1). Clients MUST NOT assume
in the Feed is a full representation of a member resource. The value that an Atom Entry returned in the Feed is a full representation of a
of atom:updated is only changed when the change to a member resource member resource. The value of atom:updated is only changed when the
is considered significant. Insignificant changes do not result in change to a member resource is considered significant. Insignificant
changes to the atom:updated value and thus do not change the position changes do not result in changes to the atom:updated value and thus
of the corresponding entry in a membership list. Clients SHOULD be do not change the position of the corresponding entry in a membership
constructed with this in mind and SHOULD perform a GET on the member list. Clients SHOULD be constructed with this in mind and SHOULD
resource before editing. perform a GET on the member resource before editing.
Collections can contain extremely large numbers of resources. A Collections can contain large numbers of resources. A naive client
naive client such as a web spider or web browser would be overwhelmed such as a web spider or web browser could be overwhelmed if the
if the response to a GET contained every entry in the feed, and the response to a GET contained every entry in the collection, and the
server would waste large amounts of bandwidth and processing time on server would waste large amounts of bandwidth and processing time on
clients unable to handle the response. clients unable to handle the response. For this reason, servers MAY
return a partial listing containing the most recently updated member
resources. Such partial feed documents MUST have an atom:link with a
"next" relation whose "href" value is the IRI of the next partial
listing of the collection (the least recently updated member
resources) where it exists. This is called "collection paging".
For this reason, Introspection documents refer to collections not 9.1 Collection Paging
with IRIs but with IRI Templates, contained in the "app:member-type"
child of "app:collection". An IRI Template is a string containing
the embedded token "{index}".
To produce an IRI that can be used to retrieve part or all of the Atom Protocol servers MUST provide representations of collections as
collection, software replaces the "{index}" with a pair of positive Atom feed documents whose entries represent the collection's members.
integer indices separated by a dash character. An IRI template MUST, The returned Atom feed MAY NOT contain entries for all the
after such substitution has been performed, constitute a collection's members. Instead, the Atom feed document MAY contain
syntactically valid IRI. link elements with "rel" attribute values of "next", "previous",
"start" and "end" that can be used to navigate through the complete
set of matching entries.
One or other index MAY be omitted, in which case the range is For instance, suppose the client is supplied this IRI
understood as stretching to 0 or infinity. The index values are 0 http://example.org/entries/go
based and select members from the collection based on the member's
index, with all of the members ordered by their 'atom:updated'
property. 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. If a membership list is returned
with a number of entries that is less than the number of entries
requested than the client MAY assume that it has made a request that
exceeds the last index of the members.
For example, suppose the client is supplied this IRI template: Supposing the collection contains member entries and the server as a
matter of policy wishes to avoid generating feed documents with more
than 10 entries, then the resulting Atom feed document represents the
first page in a linked set of 10 feed documents. Within each feed
document served, "next" and "prev" link elements reference the
preceding and subsequent feed documents in the set. The "start" link
element references the first feed document in the set. The "end"
link element references the final feed document in the set.
http://example.org/blog/edit/{index} <feed xmlns="http://www.w3.org/2005/Atom">
If the client wants the first 15 entries in the collection it would ...
substitute the brace-delimited parameter {index}, with the value <link rel="start"
0-14, giving: href="http://example.org/entries/go" />
<link rel="next"
href="http://example.org/entries/2" />
<link rel="last"
href="http://example.org/entries/10" />
</feed>
http://example.org/blog/edit/0-14 The 'next' and 'prev' link elements for the feed located at
http://example.org/entries/2 would look like this:
10. Atom Entry Extensions <feed xmlns="http://www.w3.org/2005/Atom">
...
<link rel="start"
href="http://example.org/entries/go" />
<link rel="previous"
href="http://example.org/entries/go" />
<link rel="next"
href="http://example.org/entries/3" />
<link rel="last"
href="http://example.org/entries/10" />
</feed>
This specification adds one new value to the Registry of Link 10. Atom Format Link Relation Extensions
Relations and also adds a new element to Atom Entries called "app:
control" for controlling publishing. These new links and app: 10.1 The "edit" Link Relation
control elements MAY appear in both membership lists and in member
The Atom Protocol adds the value "edit" to the Atom Registry of Link
Relations (see section 7.1 of [RFC4287]). The value of "edit"
specifies that the IRI in the value of the href attribute is the IRI
of the member resource, and is intended to be used to update and
delete resources as described in this specification. This link
relation MAY appear in both membership lists and in member
representations. representations.
10.1 The 'edit' Link Relation 11. Atom Publishing Control Extensions
This specification adds the value "edit" to the Registry of Link 11.1 The Atom Publishing Control Namespace
Relations. The value of "edit" signifies that the IRI in the value
of the href attribute is the IRI of the member resource, and is
intended to be used to update and delete resources as described in
this specification.
10.2 Publishing Control This specification defines an Atom Format extension for publishing
control called Atom Publishing Control. The namespace name for the
Atom Publishing Control's XML vocabulary is
"http://example.net/appns/". This specification uses "pub:" for the
namespace prefix. The choice of namespace prefix is not semantically
significant.
This specification also adds a new element to Atom Entries for 11.2 The "pub:control" Element
controlling publishing.
namespace pub = "http://example.net/appns/"
pubControl = pubControl =
element app:control { element pub:control {
atomCommonAttributes, atomCommonAttributes,
pubDraft? pubDraft?
& extensionElement & extensionElement
} }
pubDraft = pubDraft =
element app:draft { "yes" | "no" } element pub:draft { "yes" | "no" }
The "app:control" element MAY appear as a child of an "atom:entry" The "pub:control" element MAY appear as a child of an "atom:entry"
which is being created or updated via the Atom Publishing Protocol. which is being created or updated via the Atom Publishing Protocol.
The "app:control" element, if it does appear in an entry, MUST only The "pub:control" element, if it does appear in an entry, MUST only
appear at most one time. appear at most one time. The "pub:control" element is considered
foreign markup as defined in Section 6 of [RFC4287].
The "app:control" element and its children elements MAY be included
in Atom Feed or Entry Documents. The "app:control" element is
considered "foreign markup" as defined in Section 6 of the Atom
Syndication Format.
The "app:control" element MAY contain exactly one app:draft element The "pub:control" element and its child elements MAY be included in
and MAY contain zero or more extension elements as outlined in the Atom Feed or Entry Documents.
Atom Syndication Format, Section 6. Both clients and servers MUST
ignore foreign markup present in the app:control element that they do
not know.
10.2.1 The app:draft Element The "pub:control" element MAY contain exactly one "pub:draft" element
as defined here, and MAY contain zero or more extension elements as
outlined in Section 6 of [RFC4287]. Both clients and servers MUST
ignore foreign markup present in the pub:control element.
This specification defines only one child element for "app:control", 11.2.1 The "pub:draft" Element
"app:draft".
The number of "app:draft" elements in "app:control" MUST be zero or The number of "pub:draft" elements in "pub:control" MUST be zero or
one. Its content MUST be one of the values "yes" or "no". A value one. Its value MUST be one of "yes" or "no". A value of "no" means
of "no" means that the entry MAY be made publicly visible. If the that the entry may be made publicly visible. If the "pub:draft"
"app:draft" element is missing then the value is understood to be element is missing then the value is understood to be "no". If "pub:
"no". That is, if "app:control" and/or the "app:draft" elements are control" and/or the "pub:draft" elements are missing from an entry
missing from an entry then the entry is considered not a draft and then the entry is not considered a draft and can be made publicly
can be made publicly visible. Clients MUST understand "app:draft" visible.
elements and MUST NOT drop them from Atom Entries during editing.
Clients MUST NOT operate on the expectation that a server will honor
the value of an "app:draft" element. Servers MAY ignore "app:draft"
elements and drop them from Atom Entries.
11. Example 12. Atom Publishing Protocol Example
This is an example of a client creating a new entry with an image. This is an example of a client creating a new entry with an image.
The client has an image to publish and an entry that includes an HTML The client has an image to publish and an entry that includes an HTML
'img' element that uses that image. In this scenario we consider a "img" element that uses that image. In this scenario we consider a
client that has IRIs of two collections, an entry collection and a client that has IRIs of two collections, an entry collection and a
media collection, both of which were discovered through an media collection, both of which were discovered through an
introspection document. The IRI of the entry collection is: introspection document. The IRI of the entry collection is:
http://example.net/blog/edit/ http://example.net/blog/edit/
The IRI of the media collection is: The IRI of the media collection is:
http://example.net/binary/edit http://example.net/binary/edit
skipping to change at page 26, line 18 skipping to change at page 24, line 18
POST /blog/edit/ HTTP/1.1 POST /blog/edit/ HTTP/1.1
Host: example.net Host: example.net
User-Agent: Thingio/1.0 User-Agent: Thingio/1.0
Content-Type: application/atom+xml Content-Type: application/atom+xml
Content-Length: nnnn Content-Length: nnnn
<?xml version="1.0" encoding="utf-8"?> <?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"> <entry xmlns="http://www.w3.org/2005/Atom">
<title>What I did on my summer vacation</title> <title>What I did on my summer vacation</title>
<link href="http://example.org/atom05"/>
<id>urn:uuid:1225c695-ffb8-4ebb-aaaa-80da354efa6a</id>
<updated>2005-09-02T10:30:00Z</updated> <updated>2005-09-02T10:30:00Z</updated>
<summary>Beach!</summary> <summary>Beach!</summary>
<content type="xhtml" xml:lang="en"> <content type="xhtml" xml:lang="en">
<div xmlns="http://www.w3.org/1999/xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">
<p>We went to the beach for summer vacation. <p>We went to the beach for summer vacation.
Here is a picture of the waves rolling in: Here is a picture of the waves rolling in:
<img <img
src="http://example.net/binary/readonly/129.png" src="http://example.net/binary/readonly/129.png"
alt="A picture of the beach." alt="A picture of the beach."
/> />
</p> </p>
</div> </div>
</content> </content>
</entry> </entry>
12. Securing the Atom Protocol 13. Securing the Atom Protocol
All instances of publishing Atom entries SHOULD be protected by All instances of publishing Atom Format entries SHOULD be protected
authentication to prevent posting or editing by unknown sources. by authentication to prevent posting or editing by unknown sources.
Atom servers and clients MUST support one of the following Atom Protocol 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 CGI Authentication
Atom servers and clients MAY support encryption of the session using Atom Protocol servers and clients MAY support encryption of the
TLS (see [RFC2246]). session using TLS (see [RFC2246]).
There are cases where an authentication mechanism is not be required, There are cases where an authentication mechanism is not be required,
such as a publicly editable Wiki, or when using POST to send comments such as a publicly editable Wiki, or when using POST to send comments
to a site that does not require authentication from a commenter. to a site that does not require authentication from a commenter.
12.1 [@@TBD@@ CGI Authentication] 13.1 CGI Authentication
This authentication method is included as part of the protocol to [[anchor26: This section is incomplete; cgi-authentication is
allow Atom servers and clients that cannot use HTTP Digest described but is unspecified.]] This authentication method is
Authentication but where the user can both insert its own HTTP included as part of the protocol to allow Atom Protocol servers and
headers and create a CGI program to authenticate entries to the clients that cannot use HTTP Digest Authentication but where the user
server. This scenario is common in environments where the user can both insert its own HTTP headers and create a CGI program to
cannot control what services the server employs, but the user can authenticate entries to the server. This scenario is common in
write their own HTTP services. environments where the user cannot control what services the server
employs, but the user can write their own HTTP services.
13. Security Considerations 14. Security Considerations
The security of Atom is based on HTTP Digest Authentication and/or The security of the Atom Protocol is based on HTTP Digest
[@@TBD@@ CGI Authentication]. Any weaknesses in either of these Authentication and/or CGI Authentication [[anchor28: refers to
incomplete section]]. Any weaknesses in either of these
authentication schemes will 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 CGI Authentication [[anchor29:
susceptible to dictionary-based attacks on the shared secret. If the refers to incomplete section]] are susceptible to dictionary-based
shared secret is a password (instead of a random string with attacks on the shared secret. If the shared secret is a password
sufficient entropy), an attacker can determine the secret by (instead of a random string with sufficient entropy), an attacker can
exhaustively comparing the authenticating string with hashed results determine the secret by exhaustively comparing the authenticating
of the public string and dictionary entries. string with hashed results of the public string and dictionary
entries.
See [RFC2617] for the description of the security properties of HTTP See [RFC2617] for the description of the security properties of HTTP
Digest Authentication. Digest Authentication.
@@TBD@@ Talk here about using HTTP basic and digest authentication. [[anchor30: expand on HTTP basic and digest authentication, or
refer.]]
@@TBD@@ Talk here about denial of service attacks using large XML [[anchor31: talk here about denial of service attacks using large XML
files, or the billion laughs DTD attack. files, or the billion laughs DTD attack.]]
14. IANA Considerations 15. IANA Considerations
An Atom Introspection Document, when serialized as XML 1.0, can be An Atom Publishing Protocol Introspection Document, when serialized
identified with the following media type: as XML 1.0, can be identified with the following media type:
MIME media type name: application MIME media type name: application
MIME subtype name: atomserv+xml MIME subtype name: atomserv+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.
[[anchor22: update upon publication]] [[anchor32: 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. [[anchor23: update upon Published specification: This specification. [[anchor33: 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 30, line 14 skipping to change at page 28, line 14
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). [[anchor24: Author/Change controller: This specification's author(s). [[anchor34:
update upon publication]] update upon publication]]
15. References 16. References
15.1 Normative References
[AtomFormat] 16.1 Normative References
Nottingham, M. and R. Sayre, "The Atom Syndication
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 31, line 38 skipping to change at page 29, line 34
[RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media
Types", RFC 3023, January 2001. Types", RFC 3023, January 2001.
[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.
[RFC4287] Nottingham, M. and R. Sayre, "The Atom Syndication
Format", RFC 4287, December 2005.
[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.
[W3C.REC-xml-names-19990114] [W3C.REC-xml-names-19990114]
Hollander, D., Bray, T., and A. Layman, "Namespaces in Hollander, D., Bray, T., and A. Layman, "Namespaces in
XML", W3C REC REC-xml-names-19990114, January 1999. XML", W3C REC REC-xml-names-19990114, January 1999.
[W3C.REC-xmlbase-20010627] [W3C.REC-xmlbase-20010627]
Marsh, J., "XML Base", W3C REC W3C.REC-xmlbase-20010627, Marsh, J., "XML Base", W3C REC W3C.REC-xmlbase-20010627,
June 2001. June 2001.
15.2 Informative References 16.2 Informative References
[RNC] Clark, J., "RELAX NG Compact Syntax", December 2001. [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
skipping to change at page 35, line 9 skipping to change at page 33, line 9
Appendix A. Contributors Appendix A. Contributors
The content and concepts within are a product of the Atom community The content and concepts within are a product of the Atom community
and the Atompub Working Group. and the Atompub Working Group.
Appendix B. RELAX NG Compact Schema Appendix B. RELAX NG Compact Schema
This appendix is informative. This appendix is informative.
The Relax NG schema explicitly excludes elements in the APP namespace The Relax NG schema explicitly excludes elements in the Atom Protocol
which are not defined in this revision of the specification. namespace which are not defined in this revision of the
Requirements for APP Processors encountering such markup are given in specification. Requirements for Atom Protocol processors
Section 6.2 and Section 6.3 of [AtomFormat]. encountering such markup are given in Section 6.2 and Section 6.3 of
[RFC4287].
# -*- rnc -*- # -*- rnc -*-
# RELAX NG Compact Syntax Grammar for the Atom Protocol # RELAX NG Compact Syntax Grammar for the Atom Protocol
namespace app = "http://purl.org/atom/app#" namespace app = "http://purl.org/atom/app#"
namespace local = "" namespace local = ""
start = appService start = appService
# common:attrs # common:attrs
skipping to change at page 38, line 7 skipping to change at page 36, line 7
element * { element * {
(attribute * { text } (attribute * { text }
| text | text
| anyElement)* | anyElement)*
} }
# EOF # EOF
Appendix C. Revision History Appendix C. Revision History
draft-ietf-atompub-protocol-07: updated Atom refs to RFC4287;
incorporated PaceBetterHttpResponseCode;
PaceClarifyCollectionAndDeleteMethodByWritingLessInsteadOfMore;
PaceRemoveAcceptPostText; PaceRemoveListTemplate2;
PaceRemoveRegistry; PaceRemoveWhoWritesWhat;
PaceSimplifyClarifyBetterfyRemoveBogusValidityText;
PaceCollectionOrderSignificance; PaceFixLostIntrospectionText;
PaceListPaging; PaceCollectionControl; element typo in Listing
collections para3 (was app:member-type, not app:list-template);
changed post atom entry example to be valid. Dropped inline use of
'APP'. Removed nested diagram from section 4. Added ed notes in the
security section.
draft-ietf-atompub-protocol-06 - Removed: Robert Sayre from the draft-ietf-atompub-protocol-06 - Removed: Robert Sayre from the
contributors section per his request. Added in contributors section per his request. Added in
PaceCollectionControl. Fixed all the {daterange} verbage and PaceCollectionControl. Fixed all the {daterange} verbage and
examples so they all use a dash. Added full rnc schema. Collapsed examples so they all use a dash. Added full rnc schema. Collapsed
Introspection and Collection documents into a single document. Introspection and Collection documents into a single document.
Removed {dateRange} queries. Renamed search to list. Moved Removed {dateRange} queries. Renamed search to list. Moved
discussion of media and entry collection until later in the document discussion of media and entry collection until later in the document
and tied the discussion to the Introspection element app:member-type. and tied the discussion to the Introspection element app:member-type.
draft-ietf-atompub-protocol-05 - Added: Contributors section. Added: draft-ietf-atompub-protocol-05 - Added: Contributors section. Added:
skipping to change at page 40, line 46 skipping to change at page 39, line 46
This document and the information contained herein are provided on an This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Copyright Statement Copyright Statement
Copyright (C) The Internet Society (2005). This document is subject Copyright (C) The Internet Society (2006). This document is subject
to the rights, licenses and restrictions contained in BCP 78, and to the rights, licenses and restrictions contained in BCP 78, and
except as set forth therein, the authors retain all their rights. except as set forth therein, the authors retain all their rights.
Acknowledgment Acknowledgment
Funding for the RFC Editor function is currently provided by the Funding for the RFC Editor function is currently provided by the
Internet Society. Internet Society.
 End of changes. 

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