draft-ietf-atompub-protocol-14.txt   draft-ietf-atompub-protocol-15.txt 
Network Working Group J. Gregorio, Ed. Network Working Group J. Gregorio, Ed.
Internet-Draft IBM Internet-Draft IBM
Intended status: Standards Track B. de hOra, Ed. Intended status: Standards Track B. de hOra, Ed.
Expires: September 5, 2007 Propylon Ltd. Expires: November 23, 2007 Propylon Ltd.
March 4, 2007 May 22, 2007
The Atom Publishing Protocol The Atom Publishing Protocol
draft-ietf-atompub-protocol-14.txt draft-ietf-atompub-protocol-15.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 September 5, 2007. This Internet-Draft will expire on November 23, 2007.
Copyright Notice Copyright Notice
Copyright (C) The IETF Trust (2007). Copyright (C) The IETF Trust (2007).
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 transfer of Atom-formatted representations. The Atom format is HTTP transfer of Atom-formatted representations. The Atom format is
documented in the Atom Syndication Format [RFC4287]. documented in the Atom Syndication Format.
Editorial Note Editorial Note
[[anchor1: Remove this section upon publication]]
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 . . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 6
2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 6 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 7
2.1. XML-related Conventions . . . . . . . . . . . . . . . . . 6 2.1. XML-related Conventions . . . . . . . . . . . . . . . . . 7
2.1.1. Referring to Information Items . . . . . . . . . . . . 6 2.1.1. Referring to Information Items . . . . . . . . . . . . 7
2.1.2. RELAX NG Schema . . . . . . . . . . . . . . . . . . . 6 2.1.2. RELAX NG Schema . . . . . . . . . . . . . . . . . . . 7
2.1.3. Use of xml:base and xml:lang . . . . . . . . . . . . . 6 2.1.3. Use of xml:base and xml:lang . . . . . . . . . . . . . 7
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 7 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8
4. Protocol Model . . . . . . . . . . . . . . . . . . . . . . . . 8 4. Protocol Model . . . . . . . . . . . . . . . . . . . . . . . . 10
4.1. Client Implementation Considerations . . . . . . . . . . . 9 4.1. Identity and Naming . . . . . . . . . . . . . . . . . . . 10
5. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 11 4.2. Documents and Resource classification . . . . . . . . . . 10
5.1. Retrieving a Service Document . . . . . . . . . . . . . . 11 4.3. Control and Publishing . . . . . . . . . . . . . . . . . . 12
5.2. Listing Collection Members . . . . . . . . . . . . . . . . 11 4.4. Client Implementation Considerations . . . . . . . . . . . 12
5.3. Creating a Resource . . . . . . . . . . . . . . . . . . . 12 5. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 14
5.4. Editing a Resource . . . . . . . . . . . . . . . . . . . . 12 5.1. Retrieving a Service Document . . . . . . . . . . . . . . 14
5.4.1. Retrieving a Resource . . . . . . . . . . . . . . . . 12 5.2. Listing Collection Members . . . . . . . . . . . . . . . . 14
5.4.2. Updating a Resource . . . . . . . . . . . . . . . . . 13 5.3. Creating a Resource . . . . . . . . . . . . . . . . . . . 15
5.4.3. Deleting a Resource . . . . . . . . . . . . . . . . . 13 5.4. Editing a Resource . . . . . . . . . . . . . . . . . . . . 15
5.5. Use of HTTP Response codes . . . . . . . . . . . . . . . . 13 5.4.1. Retrieving a Resource . . . . . . . . . . . . . . . . 15
6. Atom Publishing Protocol Documents . . . . . . . . . . . . . . 14 5.4.2. Editing a Resource . . . . . . . . . . . . . . . . . . 16
6.1. Document Types . . . . . . . . . . . . . . . . . . . . . . 14 5.4.3. Deleting a Resource . . . . . . . . . . . . . . . . . 16
6.2. Document Extensibility . . . . . . . . . . . . . . . . . . 14 5.5. Use of HTTP Response codes . . . . . . . . . . . . . . . . 16
7. Category Documents . . . . . . . . . . . . . . . . . . . . . . 16 6. Protocol Documents . . . . . . . . . . . . . . . . . . . . . . 18
7.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 16 6.1. Document Types . . . . . . . . . . . . . . . . . . . . . . 18
7.2. Element Definitions . . . . . . . . . . . . . . . . . . . 16 6.2. Document Extensibility . . . . . . . . . . . . . . . . . . 18
7.2.1. The "app:categories" element . . . . . . . . . . . . . 16 7. Category Documents . . . . . . . . . . . . . . . . . . . . . . 20
8. Service Documents . . . . . . . . . . . . . . . . . . . . . . 18 7.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 20
8.1. Workspaces . . . . . . . . . . . . . . . . . . . . . . . . 18 7.2. Element Definitions . . . . . . . . . . . . . . . . . . . 20
8.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 19 7.2.1. The "app:categories" element . . . . . . . . . . . . . 20
8.3. Element Definitions . . . . . . . . . . . . . . . . . . . 20 8. Service Documents . . . . . . . . . . . . . . . . . . . . . . 22
8.3.1. The "app:service" Element . . . . . . . . . . . . . . 20 8.1. Workspaces . . . . . . . . . . . . . . . . . . . . . . . . 22
8.3.2. The "app:workspace" Element . . . . . . . . . . . . . 20 8.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 23
8.3.3. The "app:collection" Element . . . . . . . . . . . . . 21 8.3. Element Definitions . . . . . . . . . . . . . . . . . . . 24
8.3.4. The "app:accept" Element . . . . . . . . . . . . . . . 21 8.3.1. The "app:service" Element . . . . . . . . . . . . . . 24
8.3.5. The "app:categories" Element . . . . . . . . . . . . . 22 8.3.2. The "app:workspace" Element . . . . . . . . . . . . . 24
9. Creating and Editing Resources . . . . . . . . . . . . . . . . 24 8.3.3. The "app:collection" Element . . . . . . . . . . . . . 25
9.1. Member URIs . . . . . . . . . . . . . . . . . . . . . . . 24 8.3.4. The "app:accept" Element . . . . . . . . . . . . . . . 26
9.2. Creating resources with POST . . . . . . . . . . . . . . . 24 8.3.5. Usage in Atom Feed Documents . . . . . . . . . . . . . 26
9.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 25 8.3.6. The "app:categories" Element . . . . . . . . . . . . . 26
9.3. Updating Resources with PUT . . . . . . . . . . . . . . . 26 9. Creating and Editing Resources . . . . . . . . . . . . . . . . 28
9.4. Deleting Resources with DELETE . . . . . . . . . . . . . . 26 9.1. Member URIs . . . . . . . . . . . . . . . . . . . . . . . 28
9.5. Caching and entity tags . . . . . . . . . . . . . . . . . 26 9.2. Creating Resources with POST . . . . . . . . . . . . . . . 28
9.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 26 9.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 29
9.6. Media Resources and Media Link Entries . . . . . . . . . . 28 9.3. Editing Resources with PUT . . . . . . . . . . . . . . . . 30
9.6.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 29 9.4. Deleting Resources with DELETE . . . . . . . . . . . . . . 30
9.7. The Slug: Header . . . . . . . . . . . . . . . . . . . . . 35 9.5. Caching and entity tags . . . . . . . . . . . . . . . . . 30
9.7.1. Slug: Header syntax . . . . . . . . . . . . . . . . . 36 9.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 30
9.7.2. Example . . . . . . . . . . . . . . . . . . . . . . . 36 9.6. Media Resources and Media Link Entries . . . . . . . . . . 32
10. Listing Collections . . . . . . . . . . . . . . . . . . . . . 37 9.6.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 33
10.1. Collection partial lists . . . . . . . . . . . . . . . . . 37 9.7. The Slug: Header . . . . . . . . . . . . . . . . . . . . . 39
10.2. The "app:edited" Element . . . . . . . . . . . . . . . . . 38 9.7.1. Slug: Header syntax . . . . . . . . . . . . . . . . . 40
11. Atom Format Link Relation Extensions . . . . . . . . . . . . . 40 9.7.2. Example . . . . . . . . . . . . . . . . . . . . . . . 40
11.1. The "edit" Link Relation . . . . . . . . . . . . . . . . . 40 10. Listing Collections . . . . . . . . . . . . . . . . . . . . . 41
11.2. The "edit-media" Link Relation . . . . . . . . . . . . . . 40 10.1. Collection partial lists . . . . . . . . . . . . . . . . . 41
12. The Atom Format Type Parameter . . . . . . . . . . . . . . . . 41 10.2. The "app:edited" Element . . . . . . . . . . . . . . . . . 42
12.1. The 'type' parameter . . . . . . . . . . . . . . . . . . . 41 11. Atom Format Link Relation Extensions . . . . . . . . . . . . . 43
12.1.1. Conformance . . . . . . . . . . . . . . . . . . . . . 41 11.1. The "edit" Link Relation . . . . . . . . . . . . . . . . . 43
13. Atom Publishing Controls . . . . . . . . . . . . . . . . . . . 42 11.2. The "edit-media" Link Relation . . . . . . . . . . . . . . 43
13.1. The "app:control" Element . . . . . . . . . . . . . . . . 42 12. The Atom Format Type Parameter . . . . . . . . . . . . . . . . 44
13.1.1. The "app:draft" Element . . . . . . . . . . . . . . . 42 12.1. The 'type' parameter . . . . . . . . . . . . . . . . . . . 44
14. Securing the Atom Publishing Protocol . . . . . . . . . . . . 43 12.1.1. Conformance . . . . . . . . . . . . . . . . . . . . . 44
15. Security Considerations . . . . . . . . . . . . . . . . . . . 44 13. Atom Publishing Controls . . . . . . . . . . . . . . . . . . . 45
15.1. Denial of Service . . . . . . . . . . . . . . . . . . . . 44 13.1. The "app:control" Element . . . . . . . . . . . . . . . . 45
15.2. Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 44 13.1.1. The "app:draft" Element . . . . . . . . . . . . . . . 45
15.3. Spoofing Attacks . . . . . . . . . . . . . . . . . . . . . 44 14. Securing the Atom Publishing Protocol . . . . . . . . . . . . 46
15.4. Linked Resources . . . . . . . . . . . . . . . . . . . . . 44 15. Security Considerations . . . . . . . . . . . . . . . . . . . 47
15.5. Digital Signatures and Encryption . . . . . . . . . . . . 44 15.1. Denial of Service . . . . . . . . . . . . . . . . . . . . 47
15.6. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 44 15.2. Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 47
16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 15.3. Spoofing Attacks . . . . . . . . . . . . . . . . . . . . . 47
16.1. Content-type registration for 15.4. Linked Resources . . . . . . . . . . . . . . . . . . . . . 47
'application/atomserv+xml' . . . . . . . . . . . . . . . . 45 15.5. Digital Signatures and Encryption . . . . . . . . . . . . 47
16.2. Content-type registration for 'application/atomcat+xml' . 46 15.6. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 47
16.3. Header field registration for 'SLUG' . . . . . . . . . . . 47 15.7. Code Injection and Cross Site Scripting . . . . . . . . . 48
16.4. The Link Relation registration "edit" . . . . . . . . . . 48 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49
16.5. The Link Relation registration "edit-media" . . . . . . . 48 16.1. Content-type registration for 'application/atomcat+xml' . 49
16.6. The Atom Format Media Type Parameter . . . . . . . . . . . 48 16.2. Content-type registration for 'application/atomsvc+xml' . 50
17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49 16.3. Header field registration for 'SLUG' . . . . . . . . . . . 51
17.1. Normative References . . . . . . . . . . . . . . . . . . . 49 16.4. The Link Relation registration "edit" . . . . . . . . . . 52
17.2. Informative References . . . . . . . . . . . . . . . . . . 50 16.5. The Link Relation registration "edit-media" . . . . . . . 52
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 52 16.6. The Atom Format Media Type Parameter . . . . . . . . . . . 52
Appendix B. RELAX NG Compact Schema . . . . . . . . . . . . . . . 53 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Appendix C. Revision History . . . . . . . . . . . . . . . . . . 59 17.1. Normative References . . . . . . . . . . . . . . . . . . . 53
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 63 17.2. Informative References . . . . . . . . . . . . . . . . . . 54
Intellectual Property and Copyright Statements . . . . . . . . . . 64 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 56
Appendix B. RELAX NG Compact Schema . . . . . . . . . . . . . . . 57
Appendix C. Revision History . . . . . . . . . . . . . . . . . . 63
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 67
Intellectual Property and Copyright Statements . . . . . . . . . . 68
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]. The protocol supports the creation of Web resources [REC-xml]. The protocol supports the creation of Web Resources and
and provides facilities for: provides facilities for:
o Collections: Sets of resources, which can be retrieved in whole or o Collections: Sets of Resources, which can be retrieved in whole or
in part. in part.
o Services: Discovery and description of Collections. o Services: Discovery and description of Collections.
o Editing: Creating, updating and deleting resources. o Editing: Creating, editing, and deleting Resources.
The Atom Publishing Protocol is different from many contemporary The Atom Publishing Protocol is different from many contemporary
protocols in that the server is given wide latitude in processing protocols in that the server is given wide latitude in processing
requests from clients. See Section 4 for more details. requests from clients. See Section 4.4 for more details.
2. Notational Conventions 2. 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].
2.1. XML-related Conventions 2.1. XML-related Conventions
2.1.1. Referring to Information Items 2.1.1. Referring to Information Items
Atom Protocol Document formats are specified in terms of the XML Atom Protocol Document formats are specified in terms of the XML
Information Set [W3C.REC-xml-infoset], serialized as XML 1.0 Information Set [REC-xml-infoset], serialized as XML 1.0 [REC-xml].
[W3C.REC-xml].
The Infoset terms "Element Information Item" and "Attribute The Infoset terms "Element Information Item" and "Attribute
Information Item" are shortened to "element" and "attribute" Information Item" are shortened to "element" and "attribute"
respectively. Therefore, when this specification uses the term respectively. Therefore, when this specification uses the term
"element", it is referring to an Element Information Item, and when "element", it is referring to an Element Information Item, and when
it uses the term "attribute", it is referring to an Attribute it uses the term "attribute", it is referring to an Attribute
Information Item. Information Item.
2.1.2. RELAX NG Schema 2.1.2. RELAX NG Schema
Some sections of this specification are illustrated with fragments of Some sections of this specification are illustrated with fragments of
a non-normative RELAX NG Compact schema [RNC]. However, the text of a non-normative RELAX NG Compact schema [RNC]. However, the text of
this specification provides the definition of conformance. Complete this specification provides the definition of conformance. Complete
schemas appear in Appendix B. schemas appear in Appendix B.
2.1.3. Use of xml:base and xml:lang 2.1.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 [REC-xmlbase]. When xml:base is used, it serves the
serves the function described in Section 5.1.1 of URI Generic Syntax function described in Section 5.1.1 of URI Generic Syntax [RFC3986],
[RFC3986], by establishing the base URI (or IRI) for resolving by establishing the base URI (or IRI) for resolving relative
relative references found within the scope of the xml:base attribute. references found within the scope of the xml:base 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. Requirements regarding the content and element and its descendents. Requirements regarding the content and
interpretation of xml:lang are specified in Section 2.12 of XML 1.0 interpretation of xml:lang are specified in Section 2.12 of XML 1.0
[W3C.REC-xml]. [REC-xml].
3. Terminology 3. Terminology
For convenience, this protocol can be referred to as the "Atom For convenience, this protocol can be referred to as the "Atom
Protocol" or "APP". Protocol" or "APP". The following terminology is used by this
specification:
URI/IRI - A Uniform Resource Identifier and Internationalized
Resource Identifier. These terms and the distinction between them
are defined in [RFC3986] and [RFC3987]. Before an IRI found in a
document is used by HTTP, the IRI is first converted to a URI (see
Section 4).
In this specification the phrase "the URI of a document" is shorthand o URI - A Uniform Resource Identifier as defined in [RFC3986]. In
this specification the phrase "the URI of a document" is shorthand
for "a URI which, when dereferenced, is expected to produce that for "a URI which, when dereferenced, is expected to produce that
document as a representation". document as a representation".
Resource - A network-accessible data object or service identified by o IRI - An Internationalized Resource Identifier as defined in
an IRI, as defined in [RFC2616]. See [W3C.REC-webarch-20041215] for [RFC3987]. Before an IRI found in a document is used by HTTP, the
further discussion on resources. IRI is first converted to a URI. See Section 4.1.
Representation - An entity included with a request or response as o Resource - A network-accessible data object or service identified
by an IRI, as defined in [RFC2616]. See [REC-webarch] for further
discussion on Resources.
o relation (or "relation of") - Refers to the "rel" attribute value
of an atom:link element.
o 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 Entries. See o Collection - A Resource that contains a set of Member Resources.
Section 9. Collections are represented as Atom Feeds. See Section 9.
Member - A resource whose IRI is listed in a Collection by a link o Member (or Member Resource) - A Resource whose IRI is listed in a
element with a relation of "edit" or "edit-media". See Section 9.1. Collection by an atom:link element with a relation of "edit" or
The protocol defines two kinds of Members - Entry and Media "edit-media". See Section 9.1. The protocol defines two kinds of
resources. Members:
Entry Resource - Member Resources of a Collection that are * Entry Resource - Members of a Collection that are represented
represented using the "application/atom+xml" media type. as Atom Entry Documents, as defined in [RFC4287].
Media Resource -Member Resources of a Collection that are represented * Media Resource - Members of a Collection that have
with a media type other than "application/atom+xml". representations other than Atom Entry Documents.
Media Link Entry - an Entry Resource that contains metadata about a o Media Link Entry - an Entry Resource that contains metadata about
Media Resource. a Media Resource. See Section 9.6.
Workspace - A named group of Collections. See Section 8.1. o Workspace - A named group of Collections. See Section 8.1.
Service Document - A document that describes the location and o Service Document - A document that describes the location and
capabilities of one or more Collections. See Section 8. capabilities of one or more Collections, grouped into Workspaces.
See Section 8.
Category Document - A document that describes the categories allowed o Category Document - A document that describes the categories
in a Collection. See Section 7. allowed in a Collection. See Section 7.
4. Protocol Model 4. Protocol Model
The Atom Publishing Protocol uses HTTP methods to author Member The Atom Protocol specifies operations for publishing and editing
Resources as follows: Resources using HTTP. It uses Atom-formatted representations to
describe the state and metadata of those Resources. It defines how
Collections of Resources can be organized, and specifies formats to
support their discovery, grouping and categorization.
o GET is used to retrieve a representation of a known resource. 4.1. Identity and Naming
o POST is used to create a new, dynamically-named, resource. When Atom Protocol documents allow the use of IRIs [RFC3987], as well as
the client submits non-Atom-Entry representations to a Collection URIs [RFC3986] to identify Resources. Before an IRI in a document is
for creation, two resources are always created - a Media Entry for used by HTTP, the IRI is first converted to a URI according to the
the requested resource, and a Media Link Entry for metadata (in procedure defined in Section 3.1 of [RFC3987]. In accordance with
Atom Entry format) about the resource. that specification, the conversion SHOULD be applied as late as
possible. Conversion does not imply Resource creation - the IRI and
the URI into which it is converted identify the same Resource.
o PUT is used to update a known resource. While the Atom Protocol specifies the formats of the representations
that are exchanged and the actions that can be performed on the IRIs
embedded in those representations, it does not constrain the form of
the URIs that are used. HTTP [RFC2616] specifies that the URI space
of each server is controlled by that server, and this protocol
imposes no further constraints on that control.
o DELETE is used to remove a known resource. 4.2. Documents and Resource classification
The Atom Protocol does not specify the form of the URIs that are A Resource whose IRI is listed in a Collection is called a Member
used. HTTP ([RFC2616]) specifies that the URI space of each server Resource. The protocol defines two kinds of Member Resources - Entry
is controlled by that server, and this protocol imposes no further Resources and Media Resources. Entry Resources are represented as
constraints on that control. What is specified here are the formats Atom Entry Documents [RFC4287]. Media Resources can have
of the representations that are exchanged and the actions that can be representations in any media type. A Media Resource is described
performed on the IRIs embedded in those representations. within a Collection using an Entry called a Media Link Entry. This
diagram shows the classification of Resources within the Atom
Protocol:
The Atom Protocol only covers the creation, update and deletion of Member Resources
Entry and Media resources. Other resources could be created, |
updated, and deleted as the result of manipulating a Collection, but -----------------
the number of those resources, their media-types, and effects of Atom | |
Protocol operations on them are outside the scope of this Entry Resources Media Resources
specification. |
Media Link Entry
Since all aspects of client-server interaction are defined in terms The Atom Protocol defines Collection Resources for managing and
of HTTP, [RFC2616] should be consulted for any areas not covered in organizing both kinds of Member Resource. A Collection is
this specification. represented by an Atom Feed Document. A Collection Feed's Entries
contain the IRIs of, and metadata about, the Collection's Member
Resources. A Collection Feed can contain any number of Entries,
which might represent all the Members of the Collection, or an
ordered subset of them (see Section 10.1). In the diagram of a
Collection below, there are two Entries. The first contains the IRI
of an Entry Resource. The second contains the IRIs of both a Media
Resource and a Media Link Entry Resource, which contains the metadata
for that Media Resource:
Along with operations on Member Resources, the Atom Protocol defines Collection
Collection Resources for managing and organizing Member Resources. |
The representation of Collections are Atom Feed documents, and o- Entry
contain the IRIs of, and metadata about the Collection's Member | |
Resources. The Atom Protocol does not make a structural distinction | o- Member Entry IRI (Entry Resource)
between Feeds used for Collections and other Atom Feeds. The only |
mechanism that this specification supplies for indicating a o- Entry
Collection Feed is its appearance in a Service Document. |
o- Member Entry IRI (Media Link Entry)
|
o- Media IRI (Media Resource)
Atom Protocol documents allow the use of IRIs [RFC3987], as well as The Atom Protocol does not make a distinction between Feeds used for
URIs [RFC3986]. Before an IRI found in a document is used by HTTP, Collections and other Atom Feeds. The only mechanism that this
the IRI is first converted to a URI according the procedure defined specification supplies for indicating a Feed is a Collection Feed is
in Section 3.1 of [RFC3987]. In accordance with that specification, the presence of its IRI in a Service Document.
this conversion SHOULD be applied as late as possible. Conversion
does not imply resource creation - the IRI and the URI into which it
is converted identify the same resource.
There are two kinds of Member Resources - Entry Resources and Media Service Documents represent server-defined groups of Collections, and
Resources. Entry Resources are represented as Atom Entries are used to initialize the process of creating and editing Resources.
[RFC4287]. Media Resources can have representations in any media These groups of Collections are called Workspaces. Workspaces have
type. A Media Link Entry is an Entry Resource that contains metadata names, but no IRIs, and no specified processing model. The Service
about a Media Resource. This diagram shows the classification of the Document can indicate which media types, and which categories, a
resources: Collection will accept. In the diagram below, there are two
Workspaces each describing the IRIs, acceptable media types, and
categories for a Collection:
Member Resource Service
-> Entry Resource o- Workspace
-> Media Link Entry | |
-> Media Resource | o- Collection
| |
| o- IRI, categories, mediatypes
|
o- Workspace
|
o- Collection
|
o- IRI, categories, mediatypes
A Collection Feed's Atom Entries contain the Entry and Media Resource 4.3. Control and Publishing
IRIs of the Collection. A Collection Feed can contain any number of
Entries for either kind, or an ordered subset of the Entries (see
Section 10.1). In the diagram of a Collection below, there are two
Entries. The first contains the IRI of an Entry Resource. The
second contains the IRIs of both a Media Resource and a Media Link
Entry Resource, which contains the metadata for that Media Resource:
Collection The Atom Publishing Protocol uses HTTP methods to author Member
Entry Resources as follows:
Member Entry IRI -> Entry Resource
Entry
Member Entry IRI -> Media Link Entry
Media IRI -> Media Resource
Service Documents represent server-defined groups of Collections, and o GET is used to retrieve a representation of a known Resource.
are used to initialize the process of creating and editing resources.
4.1. Client Implementation Considerations o POST is used to create a new, dynamically-named, Resource. When
the client submits non-Atom-Entry representations to a Collection
for creation, two Resources are always created - a Media Entry for
the requested Resource, and a Media Link Entry for metadata about
the Resource that will appear in the Collection.
o PUT is used to edit a known Resource. It is not used for Resource
creation.
o DELETE is used to remove a known Resource.
The Atom Protocol only covers the creating, editing, and deleting of
Entry and Media Resources. Other Resources could be created, edited
and deleted as the result of manipulating a Collection, but the
number of those Resources, their media-types, and effects of Atom
Protocol operations on them are outside the scope of this
specification.
Since all aspects of client-server interaction are defined in terms
of HTTP, [RFC2616] should be consulted for any areas not covered in
this specification.
4.4. Client Implementation Considerations
The Atom Protocol imposes few restrictions on the actions of servers. The Atom Protocol imposes few restrictions on the actions of servers.
Unless a constraint is specified here, servers can be expected to Unless a constraint is specified here, servers can be expected to
vary in behavior, in particular around the manipulation of Atom vary in behavior, in particular around the manipulation of Atom
Entries sent by clients. For example, although this specification Entries sent by clients. For example, although this specification
only defines the expected behavior of Collections with respect to GET only defines the expected behavior of Collections with respect to GET
and POST, this does not imply that PUT, DELETE, PROPPATCH and others and POST, this does not imply that PUT, DELETE, PROPPATCH and others
are forbidden on Collection resources - only that this specification are forbidden on Collection Resources - only that this specification
does not define what the server's response would be to those methods. does not define what the server's response would be to those methods.
Similarly while some HTTP status codes are mentioned explicitly, Similarly while some HTTP status codes are mentioned explicitly,
clients ought to be prepared to handle any status code from a server. clients ought to be prepared to handle any status code from a server.
Servers can choose to accept, reject, delay, moderate, censor, Servers can choose to accept, reject, delay, moderate, censor,
reformat, translate, relocate or recategorize the content submitted reformat, translate, relocate or re-categorize the content submitted
to them. Only some of these choices are immediately relayed back to to them. Only some of these choices are immediately relayed back to
the client in responses to client requests; other choices may only the client in responses to client requests; other choices may only
become apparent later, in the feed or published entries. The same become apparent later, in the feed or published entries. The same
series of requests to two different publishing sites can result in a series of requests to two different publishing sites can result in a
different series of HTTP responses, different resulting feeds or different series of HTTP responses, different resulting feeds or
different entry contents. different entry contents.
As a result, client software has to be written flexibly to accept As a result, client software has to be written flexibly to accept
what the server decides are the results of its submissions. Any what the server decides are the results of its submissions. Any
server response or server content modification not explicitly server response or server content modification not explicitly
forbidden by this specification or HTTP ([RFC2616]) is therefore forbidden by this specification or HTTP [RFC2616] is therefore
allowed. allowed.
5. Protocol Operations 5. Protocol Operations
While specific HTTP status codes are shown in the interaction
diagrams below, an APP client should be prepared to handle any status
code. For example, a PUT to a Member URI could result in the return
of a "204 No Content" status code, which still indicates success.
5.1. Retrieving a Service Document 5.1. Retrieving a Service Document
Client Server Client Server
| | | |
| 1.) GET to Service Document | | 1.) GET to Service Document URI |
|------------------------------------------>| |------------------------------------------>|
| | | |
| 2.) Service Document | | 2.) 200 Ok |
| Service Document |
|<------------------------------------------| |<------------------------------------------|
| | | |
1. The client sends a GET request using the URI of the Service 1. The client sends a GET request to the URI of the Service
Document. Document.
2. The server responds with the document enumerating the IRIs of a 2. The server responds with a Service Document enumerating the IRIs
group of Collections and the capabilities of those Collections of a group of Collections and the capabilities of those
supported by the server. The content of this document can vary Collections supported by the server. The content of this
based on aspects of the client request, including, but not document can vary based on aspects of the client request,
limited to, authentication credentials. including, but not limited to, authentication credentials.
5.2. Listing Collection Members 5.2. Listing Collection Members
To list the members of a Collection, the client sends a GET request To list the members of a Collection, the client sends a GET request
to the URI of a Collection. An Atom Feed Document is returned whose to the URI of a Collection. An Atom Feed Document is returned whose
Entries contain the IRIs of Member Resources. The returned Feed may Entries contain the IRIs of Member Resources. The returned Feed may
describe all, or only a partial list of the Members in a Collection describe all, or only a partial list, of the Members in a Collection
(see Section 10). (see Section 10).
Client Server Client Server
| | | |
| 1.) GET to Collection URI | | 1.) GET to Collection URI |
|------------------------------->| |------------------------------->|
| | | |
| 2.) Atom Feed Doc | | 2.) 200 Ok |
| Atom Feed |
|<-------------------------------| |<-------------------------------|
| | | |
1. The client sends a GET request to the URI of the Collection. 1. The client sends a GET request to the URI of the Collection.
2. The server responds with an Atom Feed Document containing the 2. The server responds with an Atom Feed Document containing the
IRIs of the Collection members. IRIs of the Collection Members.
5.3. Creating a Resource 5.3. Creating a Resource
Client Server Client Server
| | | |
<