draft-ietf-atompub-protocol-12.txt | draft-ietf-atompub-protocol-13.txt | |||
---|---|---|---|---|
Network Working Group J. Gregorio, Ed. | Network Working Group J. Gregorio, Ed. | |||
Internet-Draft IBM | Internet-Draft IBM | |||
Expires: June 13, 2007 B. de hOra, Ed. | Intended status: Standards Track B. de hOra, Ed. | |||
Propylon Ltd. | Expires: August 9, 2007 Propylon Ltd. | |||
December 10, 2006 | February 5, 2007 | |||
The Atom Publishing Protocol | The Atom Publishing Protocol | |||
draft-ietf-atompub-protocol-12.txt | draft-ietf-atompub-protocol-13.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 June 13, 2007. | This Internet-Draft will expire on August 9, 2007. | |||
Copyright Notice | Copyright Notice | |||
Copyright (C) The Internet Society (2006). | 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 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 [RFC4287]. | documented in the Atom Syndication Format [RFC4287]. | |||
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 . . . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
2. Notational Conventions . . . . . . . . . . . . . . . . . . . 5 | 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 6 | |||
2.1 XML-related Conventions . . . . . . . . . . . . . . . . . 5 | 2.1. XML-related Conventions . . . . . . . . . . . . . . . . . 6 | |||
2.1.1 Referring to Information Items . . . . . . . . . . . . 5 | 2.1.1. Referring to Information Items . . . . . . . . . . . . 6 | |||
2.1.2 RELAX NG Schema . . . . . . . . . . . . . . . . . . . 5 | 2.1.2. RELAX NG Schema . . . . . . . . . . . . . . . . . . . 6 | |||
2.1.3 Use of xml:base and xml:lang . . . . . . . . . . . . . 5 | 2.1.3. Use of xml:base and xml:lang . . . . . . . . . . . . . 6 | |||
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 6 | 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 7 | |||
4. Protocol Model . . . . . . . . . . . . . . . . . . . . . . . 7 | 4. Protocol Model . . . . . . . . . . . . . . . . . . . . . . . . 8 | |||
5. Protocol Operations . . . . . . . . . . . . . . . . . . . . 9 | 4.1. Client Implementation Considerations . . . . . . . . . . . 9 | |||
5.1 Retrieving a Service Document . . . . . . . . . . . . . . 9 | 5. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 11 | |||
5.2 Listing Collection Members . . . . . . . . . . . . . . . . 9 | 5.1. Retrieving a Service Document . . . . . . . . . . . . . . 11 | |||
5.3 Creating a Resource . . . . . . . . . . . . . . . . . . . 10 | 5.2. Listing Collection Members . . . . . . . . . . . . . . . . 11 | |||
5.4 Editing a Resource . . . . . . . . . . . . . . . . . . . . 10 | 5.3. Creating a Resource . . . . . . . . . . . . . . . . . . . 12 | |||
5.4.1 Retrieving a Resource . . . . . . . . . . . . . . . . 10 | 5.4. Editing a Resource . . . . . . . . . . . . . . . . . . . . 12 | |||
5.4.2 Updating a Resource . . . . . . . . . . . . . . . . . 11 | 5.4.1. Retrieving a Resource . . . . . . . . . . . . . . . . 12 | |||
5.4.3 Deleting a Resource . . . . . . . . . . . . . . . . . 11 | 5.4.2. Updating a Resource . . . . . . . . . . . . . . . . . 13 | |||
5.5 Use of HTTP Response codes . . . . . . . . . . . . . . . . 11 | 5.4.3. Deleting a Resource . . . . . . . . . . . . . . . . . 13 | |||
6. Atom Publishing Protocol Documents . . . . . . . . . . . . . 12 | 5.5. Use of HTTP Response codes . . . . . . . . . . . . . . . . 13 | |||
6.1 Document Types . . . . . . . . . . . . . . . . . . . . . . 12 | 6. Atom Publishing Protocol Documents . . . . . . . . . . . . . . 14 | |||
6.2 Document Extensibility . . . . . . . . . . . . . . . . . . 12 | 6.1. Document Types . . . . . . . . . . . . . . . . . . . . . . 14 | |||
7. Category Documents . . . . . . . . . . . . . . . . . . . . . 14 | 6.2. Document Extensibility . . . . . . . . . . . . . . . . . . 14 | |||
7.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . 14 | 7. Category Documents . . . . . . . . . . . . . . . . . . . . . . 16 | |||
7.2 Element Definitions . . . . . . . . . . . . . . . . . . . 14 | 7.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 16 | |||
7.2.1 The "app:categories" element . . . . . . . . . . . . . 14 | 7.2. Element Definitions . . . . . . . . . . . . . . . . . . . 16 | |||
8. Service Documents . . . . . . . . . . . . . . . . . . . . . 16 | 7.2.1. The "app:categories" element . . . . . . . . . . . . . 16 | |||
8.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . 17 | 8. Service Documents . . . . . . . . . . . . . . . . . . . . . . 18 | |||
8.2 Element Definitions . . . . . . . . . . . . . . . . . . . 18 | 8.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 19 | |||
8.2.1 The "app:service" Element . . . . . . . . . . . . . . 18 | 8.2. Element Definitions . . . . . . . . . . . . . . . . . . . 20 | |||
8.2.2 The "app:workspace" Element . . . . . . . . . . . . . 18 | 8.2.1. The "app:service" Element . . . . . . . . . . . . . . 20 | |||
8.2.3 The "app:collection" Element . . . . . . . . . . . . . 19 | 8.2.2. The "app:workspace" Element . . . . . . . . . . . . . 20 | |||
8.2.4 The "app:accept" Element . . . . . . . . . . . . . . . 19 | 8.2.3. The "app:collection" Element . . . . . . . . . . . . . 21 | |||
8.2.5 The "app:categories" Element . . . . . . . . . . . . . 20 | 8.2.4. The "app:accept" Element . . . . . . . . . . . . . . . 21 | |||
9. Creating and Editing Resources . . . . . . . . . . . . . . . 22 | 8.2.5. The "app:categories" Element . . . . . . . . . . . . . 22 | |||
9.1 Member URIs . . . . . . . . . . . . . . . . . . . . . . . 22 | 9. Creating and Editing Resources . . . . . . . . . . . . . . . . 24 | |||
9.2 Creating resources with POST . . . . . . . . . . . . . . . 22 | 9.1. Member URIs . . . . . . . . . . . . . . . . . . . . . . . 24 | |||
9.2.1 Example . . . . . . . . . . . . . . . . . . . . . . . 23 | 9.2. Creating resources with POST . . . . . . . . . . . . . . . 24 | |||
9.3 Updating Resources with PUT . . . . . . . . . . . . . . . 24 | 9.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 25 | |||
9.4 Deleting Resources with DELETE . . . . . . . . . . . . . . 24 | 9.3. Updating Resources with PUT . . . . . . . . . . . . . . . 26 | |||
9.5 Media Resources and Media Link Entries . . . . . . . . . . 25 | 9.4. Deleting Resources with DELETE . . . . . . . . . . . . . . 26 | |||
9.5.1 Examples . . . . . . . . . . . . . . . . . . . . . . . 26 | 9.5. Media Resources and Media Link Entries . . . . . . . . . . 26 | |||
9.6 The Slug: Header . . . . . . . . . . . . . . . . . . . . . 31 | 9.5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 27 | |||
9.6.1 Slug: Header syntax . . . . . . . . . . . . . . . . . 32 | 9.6. The Slug: Header . . . . . . . . . . . . . . . . . . . . . 32 | |||
9.6.2 Example . . . . . . . . . . . . . . . . . . . . . . . 32 | 9.6.1. Slug: Header syntax . . . . . . . . . . . . . . . . . 33 | |||
10. Listing Collections . . . . . . . . . . . . . . . . . . . . 33 | 9.6.2. Example . . . . . . . . . . . . . . . . . . . . . . . 33 | |||
10.1 Collection Paging . . . . . . . . . . . . . . . . . . . 33 | 10. Listing Collections . . . . . . . . . . . . . . . . . . . . . 34 | |||
10.2 The "app:edited" Element . . . . . . . . . . . . . . . . 34 | 10.1. Collection Paging . . . . . . . . . . . . . . . . . . . . 34 | |||
11. Atom Format Link Relation Extensions . . . . . . . . . . . . 35 | 10.2. The "app:edited" Element . . . . . . . . . . . . . . . . . 35 | |||
11.1 The "edit" Link Relation . . . . . . . . . . . . . . . . 35 | 11. Atom Format Link Relation Extensions . . . . . . . . . . . . . 36 | |||
11.2 The "edit-media" Link Relation . . . . . . . . . . . . . 35 | 11.1. The "edit" Link Relation . . . . . . . . . . . . . . . . . 36 | |||
12. Atom Publishing Controls . . . . . . . . . . . . . . . . . . 36 | 11.2. The "edit-media" Link Relation . . . . . . . . . . . . . . 36 | |||
12.1 The "app:control" Element . . . . . . . . . . . . . . . 36 | 12. The Atom Format Type Parameter . . . . . . . . . . . . . . . . 37 | |||
12.1.1 The "app:draft" Element . . . . . . . . . . . . . . 36 | 12.1. The 'type' parameter . . . . . . . . . . . . . . . . . . . 37 | |||
13. Securing the Atom Publishing Protocol . . . . . . . . . . . 37 | 12.1.1. Conformance . . . . . . . . . . . . . . . . . . . . . 37 | |||
14. Security Considerations . . . . . . . . . . . . . . . . . . 38 | 13. Atom Publishing Controls . . . . . . . . . . . . . . . . . . . 38 | |||
14.1 Denial of Service . . . . . . . . . . . . . . . . . . . 38 | 13.1. The "app:control" Element . . . . . . . . . . . . . . . . 38 | |||
14.2 Replay Attacks . . . . . . . . . . . . . . . . . . . . . 38 | 13.1.1. The "app:draft" Element . . . . . . . . . . . . . . . 38 | |||
14.3 Spoofing Attacks . . . . . . . . . . . . . . . . . . . . 38 | 14. Securing the Atom Publishing Protocol . . . . . . . . . . . . 39 | |||
14.4 Linked Resources . . . . . . . . . . . . . . . . . . . . 38 | 15. Security Considerations . . . . . . . . . . . . . . . . . . . 40 | |||
14.5 Digital Signatures and Encryption . . . . . . . . . . . 38 | 15.1. Denial of Service . . . . . . . . . . . . . . . . . . . . 40 | |||
14.6 URIs and IRIs . . . . . . . . . . . . . . . . . . . . . 38 | 15.2. Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 40 | |||
15. IANA Considerations . . . . . . . . . . . . . . . . . . . . 39 | 15.3. Spoofing Attacks . . . . . . . . . . . . . . . . . . . . . 40 | |||
15.1 Content-type registration for | 15.4. Linked Resources . . . . . . . . . . . . . . . . . . . . . 40 | |||
'application/atomserv+xml' . . . . . . . . . . . . . . . 39 | 15.5. Digital Signatures and Encryption . . . . . . . . . . . . 40 | |||
15.2 Content-type registration for | 15.6. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 40 | |||
'application/atomcat+xml' . . . . . . . . . . . . . . . 40 | 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 | |||
15.3 Header field registration for 'SLUG' . . . . . . . . . . 41 | 16.1. Content-type registration for | |||
16. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 | 'application/atomserv+xml' . . . . . . . . . . . . . . . . 41 | |||
16.1 Normative References . . . . . . . . . . . . . . . . . . 43 | 16.2. Content-type registration for 'application/atomcat+xml' . 42 | |||
16.2 Informative References . . . . . . . . . . . . . . . . . 44 | 16.3. Header field registration for 'SLUG' . . . . . . . . . . . 43 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 45 | 16.4. The Link Relation registration "edit" . . . . . . . . . . 44 | |||
A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 46 | 16.5. The Link Relation registration "edit-media" . . . . . . . 44 | |||
B. RELAX NG Compact Schema . . . . . . . . . . . . . . . . . . 47 | 16.6. The Atom Format Media Type Parameter . . . . . . . . . . . 44 | |||
C. Revision History . . . . . . . . . . . . . . . . . . . . . . 53 | 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 45 | |||
Intellectual Property and Copyright Statements . . . . . . . 56 | 17.1. Normative References . . . . . . . . . . . . . . . . . . . 45 | |||
17.2. Informative References . . . . . . . . . . . . . . . . . . 46 | ||||
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 48 | ||||
Appendix B. RELAX NG Compact Schema . . . . . . . . . . . . . . . 49 | ||||
Appendix C. Revision History . . . . . . . . . . . . . . . . . . 55 | ||||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 58 | ||||
Intellectual Property and Copyright Statements . . . . . . . . . . 59 | ||||
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-20060816]. The protocol supports the creation of | [W3C.REC-xml]. The protocol supports the creation of Web resources | |||
arbitrary Web resources and provides facilities for: | and 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 Service: Discovering and describing Collections. | o Service: Discovering and describing Collections. | |||
o Editing: Creating, updating and deleting resources. | o Editing: Creating, updating and deleting resources. | |||
The Atom Publishing Protocol is different from many contemporary | ||||
protocols in that the server is given wide latitude in processing | ||||
requests from clients. See Section 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-20040204], serialized as XML 1.0 | Information Set [W3C.REC-xml-infoset], serialized as XML 1.0 | |||
[W3C.REC-xml-20060816]. | [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 [W3C.REC-xmlbase-20010627]. When xml:base is used, it | |||
serves the function described in Section 5.1.1 of URI Generic Syntax | serves the function described in Section 5.1.1 of URI Generic Syntax | |||
[RFC3986], by establishing the base URI (or IRI) for resolving | [RFC3986], by establishing the base URI (or IRI) for resolving | |||
relative references found within the scope of the xml:base attribute. | relative 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. 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-20060816]. | 1.0 [W3C.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". | |||
URI/IRI - A Uniform Resource Identifier and Internationalized | URI/IRI - A Uniform Resource Identifier and Internationalized | |||
Resource Identifier. These terms and the distinction between them | Resource Identifier. These terms and the distinction between them | |||
are defined in [RFC3986] and [RFC3987]. Before an IRI found in a | 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 | document is used by HTTP, the IRI is first converted to a URI (see | |||
skipping to change at page 7, line 22 | skipping to change at page 8, line 22 | |||
o POST is used to create a new, dynamically-named, resource. When | o POST is used to create a new, dynamically-named, resource. When | |||
the client submits non-Atom-Entry representations to a Collection | the client submits non-Atom-Entry representations to a Collection | |||
for creation, two resources are always created - a Media Entry for | for creation, two resources are always created - a Media Entry for | |||
the requested resource, and a Media Link Entry for metadata (in | the requested resource, and a Media Link Entry for metadata (in | |||
Atom Entry format) about the resource. | Atom Entry format) about the 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 known resource. | o DELETE is used to remove a known resource. | |||
The Atom Protocol imposes few restrictions on the actions of servers. | ||||
Unless a constraint is specified here, servers can be expected to | ||||
vary in behavior, in particular around the manipulation of Atom | ||||
Entries sent by clients. For example this specification only defines | ||||
the expected behavior of Collections with respect to GET and POST, | ||||
but this does not imply that PUT, DELETE, PROPPATCH and others are | ||||
forbidden on Collection resources - only that this specification does | ||||
not define what the servers response would be to those methods. | ||||
Similarly while some HTTP status codes are mentioned explicitly, | ||||
clients should be prepared to handle any valid status code from a | ||||
server. | ||||
This document does not specify the form of the URIs that are used. | This document does not specify the form of the URIs that are used. | |||
HTTP ([RFC2616]) specifies that the URI space of each server is | HTTP ([RFC2616]) specifies that the URI space of each server is | |||
controlled by that server and the Atom Protocol imposes no | controlled by that server and the Atom Protocol imposes no | |||
constraints on that control. What this RFC does specify are the | constraints on that control. What this RFC does specify are the | |||
formats of the representations that are exchanged and the actions | formats of the representations that are exchanged and the actions | |||
that can be performed on the IRIs embedded in those documents. | that can be performed on the IRIs embedded in those documents. | |||
This document only covers the creation, update and deletion of Entry | This document only covers the creation, update and deletion of Entry | |||
and Media resources. Other resources can be created, updated, and | and Media resources. Other resources can be created, updated, and | |||
deleted as the result of manipulating a Collection, but the number of | deleted as the result of manipulating a Collection, but the number of | |||
those resources, their mime-types, and effects of Atom Protocol | those resources, their media-types, and effects of Atom Protocol | |||
operations on them are outside the scope of this specification. | operations on them are outside the scope of this specification. | |||
Since all aspects of client-server interaction are defined in terms | Since all aspects of client-server interaction are defined in terms | |||
of HTTP, [RFC2616] should be consulted for any areas not covered in | of HTTP, [RFC2616] should be consulted for any areas not covered in | |||
this specification. | this specification. | |||
Along with operations on Member Resources, the Atom Protocol defines | Along with operations on Member Resources, the Atom Protocol defines | |||
Collection Resources for managing and organizing Member Resources. | Collection Resources for managing and organizing Member Resources. | |||
Collections are represented by Atom Feed documents and contain the | Collections are represented by Atom Feed documents and contain the | |||
IRIs of, and metadata about, their Member Resources. The Atom | IRIs of, and metadata about, their Member Resources. The Atom | |||
Protocol does not make a distinction between Feeds used for | Protocol does not make a structural distinction between Feeds used | |||
Collections and other Atom Feeds. The only mechanism that this | for Collections and other Atom Feeds. The only mechanism that this | |||
specification supplies for distinguishing a Collection Feed is its | specification supplies for distinguishing a Collection Feed is its | |||
appearance in a Service Document. | appearance in a Service Document. | |||
Atom Protocol documents allow the use of IRIs [RFC3987], as well as | Atom Protocol documents allow the use of IRIs [RFC3987], as well as | |||
URIs [RFC3986]. Before an IRI found in a document is used by HTTP, | URIs [RFC3986]. Before an IRI found in a document is used by HTTP, | |||
the IRI is first converted to a URI according the procedure defined | the IRI is first converted to a URI according the procedure defined | |||
in Section 3.1 of [RFC3987]. In accordance with that specification, | in Section 3.1 of [RFC3987]. In accordance with that specification, | |||
this conversion SHOULD be applied as late as possible. The IRI, and | this conversion SHOULD be applied as late as possible. The IRI, and | |||
the URI into which it is converted, identify the same resource. | the URI into which it is converted, identify the same resource. | |||
skipping to change at page 8, line 31 | skipping to change at page 9, line 18 | |||
Entries [RFC4287]. Media Resources can have representations in any | Entries [RFC4287]. Media Resources can have representations in any | |||
media type. A Media Link Entry is a Member Entry that contains | media type. A Media Link Entry is a Member Entry that contains | |||
metadata about a Media Resource. This diagram shows the | metadata about a Media Resource. This diagram shows the | |||
classification of the resources: | classification of the resources: | |||
Member Resource | Member Resource | |||
-> Member Entry Resource | -> Member Entry Resource | |||
-> Media Link Entry Resource | -> Media Link Entry Resource | |||
-> Media Resource | -> Media Resource | |||
Collections, represented by Atom feeds, contain Entries. Those | A Collection's Atom Entries contain the Member Entry and Media | |||
Entries contain the Member Entry and Media Resources IRIs of the | Resources IRIs of the Collection. A Collection can contain any | |||
Collection. A Collection can contain any number of Entries of either | number of Entries for either kind. In the diagram of a Collection | |||
kind. In the diagram of a Collection below, there are two Entries. | below, there are two Entries. The first contains the IRI of a Member | |||
The first contains the IRI of a Member Entry Resource. The second | Entry Resource. The second contains the IRIs of both a Media | |||
contains the IRIs of both a Media Resource and a Media Link Entry | Resource and a Media Link Entry Resource, which contains the metadata | |||
Resource, which contains the metadata for that Media Resource: | for that Media Resource: | |||
Collection | Collection | |||
Entry | Entry | |||
Member Entry IRI -> Member Entry Resource | Member Entry IRI -> Member Entry Resource | |||
Entry | Entry | |||
Member Entry IRI -> Media Link Entry Resource | Member Entry IRI -> Media Link Entry Resource | |||
Media IRI -> Media Resource | Media IRI -> Media Resource | |||
Service Documents represent server-defined groups of Collections, and | Service Documents represent server-defined groups of Collections, and | |||
are used to initialize the process of creating and editing resources. | are used to initialize the process of creating and editing resources. | |||
4.1. Client Implementation Considerations | ||||
The Atom Protocol imposes few restrictions on the actions of servers. | ||||
Unless a constraint is specified here, servers can be expected to | ||||
vary in behavior, in particular around the manipulation of Atom | ||||
Entries sent by clients. For example, although this specification | ||||
only defines the expected behavior of Collections with respect to GET | ||||
and POST, this does not imply that PUT, DELETE, PROPPATCH and others | ||||
are forbidden on Collection resources - only that this specification | ||||
does not define what the servers response would be to those methods. | ||||
Similarly while some HTTP status codes are mentioned explicitly, | ||||
clients should be prepared to handle any status code from a server. | ||||
Servers can choose to accept, reject, delay, moderate, censor, | ||||
reformat, translate, relocate or recategorize the content submitted | ||||
to them. Only some of these choices are immediately relayed back to | ||||
the client in responses to client requests; other choices may only | ||||
become apparent later, in the feed or published entries. The same | ||||
series of requests to two different publishing sites can result in a | ||||
different series of HTTP responses, different resulting feeds or | ||||
different entry contents. | ||||
As a result, client software has to be written flexibly to accept | ||||
what the server decides are the results of its submissions. Any | ||||
server response or server content modification not explicitly | ||||
forbidden by this specification or HTTP ([RFC2616]) is therefore | ||||
allowed. | ||||
5. Protocol Operations | 5. Protocol Operations | |||
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 | | |||
|------------------------------------------>| | |------------------------------------------>| | |||
| | | | | | |||
| 2.) Service Document | | | 2.) Service Document | | |||
|<------------------------------------------| | |<------------------------------------------| | |||
| | | | | | |||
1. The client sends a GET request using the URI of the Service | 1. The client sends a GET request using the URI of the Service | |||
Document. | Document. | |||
2. The server responds with the document enumerating the IRIs of a | 2. The server responds with the document enumerating the IRIs of a | |||
group of Collections and the capabilities of those Collections | group of Collections and the capabilities of those Collections | |||
supported by the server. The content of this document can vary | supported by the server. The content of this document can vary | |||
based on aspects of the client request, including, but not | based on aspects of the client request, including, but not | |||
limited to, authentication credentials. | 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 subset, of the Members in a Collection (see | describe all, or only a subset, of the Members in a Collection (see | |||
Section 10). Section 11 describes extensions to the Atom Syndication | Section 10). Section 11 describes extensions to the Atom Syndication | |||
Format used in the Atom Protocol. | Format used in the Atom Protocol. | |||
Client Server | Client Server | |||
| | | | | | |||
skipping to change at page 10, line 5 | skipping to change at page 12, line 5 | |||
| | | | | | |||
| 2.) Atom Feed Doc | | | 2.) Atom Feed Doc | | |||
|<-------------------------------| | |<-------------------------------| | |||
| | | | | | |||
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 | |||
| | | | | | |||
| 1.) POST to URI of Collection | | | 1.) POST to URI of Collection | | |||
|------------------------------------------>| | |------------------------------------------>| | |||
| | | | | | |||
| 2.) 201 Created | | | 2.) 201 Created | | |||
| Location: Member Entry URI | | | Location: Member Entry URI | | |||
|<------------------------------------------| | |<------------------------------------------| | |||
| | | | | | |||
skipping to change at page 10, line 27 | skipping to change at page 12, line 27 | |||
1. The client POSTs a representation of the Member to the URI of the | 1. The client POSTs a representation of the Member to the URI of the | |||
Collection. | 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 Entry Resource. | contains the IRI of the newly created Member Entry Resource. | |||
Media Resources could have also been created and their IRIs can | Media Resources could have also been created and their IRIs can | |||
be found through the Member Entry Resource. See Section 9.5 for | be found through the Member Entry Resource. See Section 9.5 for | |||
more details. | more details. | |||
5.4 Editing a Resource | 5.4. Editing a Resource | |||
Once a resource has been created and its Member URI is known, that | Once a resource has been created and its Member URI is known, that | |||
URI can be used to retrieve, update, and delete the resource. | URI can be used to retrieve, update, and delete the resource. | |||
5.4.1 Retrieving a Resource | 5.4.1. Retrieving a Resource | |||
Client Server | Client Server | |||
| | | | | | |||
| 1.) GET to Member URI | | | 1.) GET to Member URI | | |||
|------------------------------------------>| | |------------------------------------------>| | |||
| | | | | | |||
| 2.) Member Representation | | | 2.) Member Representation | | |||
|<------------------------------------------| | |<------------------------------------------| | |||
| | | | | | |||
1. The client sends a GET request to the URI of a Member Resource to | 1. The client sends a GET request to the URI of a Member Resource to | |||
retrieve its representation. | retrieve its representation. | |||
2. The server responds with the representation of the resource. | 2. The server responds with the representation of the resource. | |||
5.4.2 Updating a Resource | 5.4.2. Updating a Resource | |||
Client Server | Client Server | |||
| | | | | | |||
| 1.) PUT to Member URI | | | 1.) PUT to Member URI | | |||
|------------------------------------------>| | |------------------------------------------>| | |||
| | | | | | |||
| 2.) 200 OK | | | 2.) 200 OK | | |||
|<------------------------------------------| | |<------------------------------------------| | |||
1. The client PUTs an updated representation to the URI of a Member | 1. The client PUTs an updated representation to the URI of a Member | |||
Resource. | Resource. | |||
2. If the update is successful the server responds with a status | 2. If the update is successful the server responds with a status | |||
code of 200. | code of 200. | |||
5.4.3 Deleting a Resource | 5.4.3. Deleting a Resource | |||
Client Server | Client Server | |||
| | | | | | |||
| 1.) DELETE to Member URI | | | 1.) DELETE to Member URI | | |||
|------------------------------------------>| | |------------------------------------------>| | |||
| | | | | | |||
| 2.) 200 Ok | | | 2.) 200 Ok | | |||
|<------------------------------------------| | |<------------------------------------------| | |||
| | | | | | |||
1. The client sends a DELETE request to the URI of a Member | 1. The client sends a DELETE request to the URI of a Member | |||
Resource. | Resource. | |||
2. If the deletion is successful the server responds with a status | 2. If the deletion is successful the server responds with a status | |||
code of 200. | code of 200. | |||
A different approach is taken for deleting Media Resources, see | A different approach is taken for deleting Media Resources, see | |||
Section 9.5 for details. | Section 9.5 for details. | |||
5.5 Use of HTTP Response codes | 5.5. Use of HTTP Response codes | |||
The Atom Protocol uses the response status codes defined in HTTP to | The Atom Protocol uses the response status codes defined in HTTP to | |||
indicate the success or failure of an operation. Consult the HTTP | indicate the success or failure of an operation. Consult the HTTP | |||
specification [RFC2616] for detailed definitions of each status code. | specification [RFC2616] for detailed definitions of each status code. | |||
Implementers are asked to note that per the HTTP specification, HTTP | Implementers are asked to note that according to the HTTP | |||
4xx and 5xx response entities SHOULD include a human-readable | specification, HTTP 4xx and 5xx response entities SHOULD include a | |||
explanation of the error. | human-readable explanation of the error. | |||
6. Atom Publishing Protocol Documents | 6. Atom Publishing Protocol Documents | |||
6.1 Document Types | 6.1. Document Types | |||
This specification describes two kinds of Documents - Category | This specification describes two kinds of Documents - Category | |||
Documents and Service Documents. | Documents and Service Documents. | |||
A Category Document (Section 7) contain lists of categories specified | A Category Document (Section 7) contains lists of categories | |||
using the "atom:category" element from the Atom Syndication Format. | specified using the "atom:category" element from the Atom Syndication | |||
A Service Document (Section 8) describes Workspaces, which are | Format. A Service Document (Section 8) describes Workspaces, which | |||
server-defined groups of Collections. This specification assigns no | are server-defined groups of Collections. This specification assigns | |||
meaning to Workspaces; that is, a Workspace does not imply any | no meaning to Workspaces; that is, a Workspace does not imply any | |||
specific processing assumptions. Operations on Workspaces | specific processing assumptions. Operations on Workspaces | |||
themselves, such as creation or deletion, are not defined by this | themselves, such as creation or deletion, are not defined by this | |||
specification. | specification. | |||
The namespace name [W3C.REC-xml-names-20060816] for either kind of | The namespace name [W3C.REC-xml-names] for either kind of document | |||
document is: | is: | |||
http://purl.org/atom/app# | http://purl.org/atom/app# | |||
[[anchor8: The namespace name needs to be updated with the final URI | [[anchor8: The namespace name needs to be updated with the final URI | |||
upon publication]] | upon publication]] | |||
This specification uses the prefix "app:" for the namespace name. | This specification uses the prefix "app:" for the namespace name. | |||
The prefix "atom:" is used for "http://www.w3.org/2005/Atom", the | The prefix "atom:" is used for "http://www.w3.org/2005/Atom", the | |||
namespace name of the Atom Syndication Format [RFC4287]. The | namespace name of the Atom Syndication Format [RFC4287]. The | |||
namespace prefixes are not semantically significant. | namespace prefixes are not semantically significant. | |||
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 formats, and | specification does not define any DTDs for Atom Protocol formats, and | |||
hence does not require them to be "valid" in the sense used by XML. | hence does not require them to be "valid" in the sense used by XML. | |||
6.2 Document Extensibility | 6.2. Document Extensibility | |||
Unrecognized markup in an Atom Publishing Protocol document is | Unrecognized markup in an Atom Publishing Protocol document is | |||
considered "foreign markup" as defined in [RFC4287]. Such foreign | considered "foreign markup" as defined in [RFC4287]. Such foreign | |||
markup can be used anywhere within a Category or Service Document | markup can be used anywhere within a Category or Service Document | |||
unless it is explicitly forbidden. Processors that encounter foreign | unless it is explicitly forbidden. Processors that encounter foreign | |||
markup MUST NOT stop processing and MUST NOT signal an error. | markup MUST NOT stop processing and MUST NOT signal an error. | |||
Clients SHOULD preserve foreign markup when transmitting such | Clients SHOULD preserve foreign markup when transmitting such | |||
documents. | documents. | |||
The namespace name "http://purl.org/atom/app#" is reserved for | The namespace name "http://purl.org/atom/app#" is reserved for | |||
forward compatible revisions of the Category and Service Document | forward compatible revisions of the Category and Service Document | |||
types - this does not exclude the addition of elements and attributes | types - this does not exclude the addition of elements and attributes | |||
that might not be recognized by processors conformant to this | that might not be recognized by processors conformant to this | |||
specification. Such unrecognized markup from the | specification. Such unrecognized markup from the | |||
"http://purl.org/atom/app#" namespace MUST be treated as foreign | "http://purl.org/atom/app#" namespace MUST be treated as foreign | |||
markup. | markup. | |||
[[anchor9: The namespace name needs to be updated with the final URI | ||||
upon publication]] | ||||
7. Category Documents | 7. Category Documents | |||
Category Documents contain lists of categories described using the | Category Documents contain lists of categories described using the | |||
"atom:category" element from the Atom Syndication Format [RFC4287]. | "atom:category" element from the Atom Syndication Format [RFC4287]. | |||
Categories can also appear in Service Documents, where they describe | Categories can also appear in Service Documents, where they describe | |||
the categories allowed in a Collection (see Section 8.2.5). | the categories allowed in a Collection (see Section 8.2.5). | |||
Category Documents are identified with the "application/atomcat+xml" | Category Documents are identified with the "application/atomcat+xml" | |||
media type (see Section 15). | media type (see Section 16). | |||
7.1 Example | 7.1. Example | |||
<?xml version="1.0" ?> | <?xml version="1.0" ?> | |||
<app:categories | <app:categories | |||
xmlns:app="http://purl.org/atom/app#" | xmlns:app="http://purl.org/atom/app#" | |||
xmlns="http://www.w3.org/2005/Atom" | xmlns="http://www.w3.org/2005/Atom" | |||
fixed="yes" scheme="http://example.com/cats/big3"> | fixed="yes" scheme="http://example.com/cats/big3"> | |||
<category term="animal" /> | <category term="animal" /> | |||
<category term="vegetable" /> | <category term="vegetable" /> | |||
<category term="mineral" /> | <category term="mineral" /> | |||
</app:categories> | </app:categories> | |||
This Category Document contains three categories, with the terms | This Category Document contains three categories, with the terms | |||
"animal", "vegetable", and "mineral". None of the categories use the | "animal", "vegetable", and "mineral". None of the categories use the | |||
'label' attribute defined in [RFC4287]. They all inherit the | 'label' attribute defined in [RFC4287]. They all inherit the | |||
"http://example.com/cats/big3" 'scheme' attribute declared on the | "http://example.com/cats/big3" 'scheme' attribute declared on the | |||
app:categories element. Therefore if the "mineral" category were to | app:categories element. Therefore if the "mineral" category were to | |||
appear in an Atom Entry or Feed Document, it would appear as: | appear in an Atom Entry or Feed Document, it would appear as: | |||
<category scheme="http://example.com/cats/big3" term="mineral" /> | <category scheme="http://example.com/cats/big3" term="mineral" /> | |||
7.2 Element Definitions | 7.2. Element Definitions | |||
7.2.1 The "app:categories" element | 7.2.1. The "app:categories" element | |||
The root of a Category Document is the "app:categories" element. An | The root of a Category Document is the "app:categories" element. An | |||
app:categories element can contain zero or more "atom:category" | app:categories element can contain zero or more "atom:category" | |||
elements from the Atom namespace ("http://www.w3.org/2005/Atom"). | elements from the Atom namespace ("http://www.w3.org/2005/Atom"). | |||
An app:category child element that has no "scheme" attribute inherits | An app:category child element that has no "scheme" attribute inherits | |||
the attribute from its app:categories parent. An app:category child | the attribute from its app:categories parent. An app:category child | |||
element with an existing "scheme" attribute does not inherit the | element with an existing "scheme" attribute does not inherit the | |||
"scheme" value of its "app:categories" parent element. | "scheme" value of its "app:categories" parent element. | |||
7.2.1.1 Attributes of "app:categories" | 7.2.1.1. Attributes of "app:categories" | |||
The app:categories element can contain a "fixed" attribute, with a | The app:categories element can contain a "fixed" attribute, with a | |||
value of either "yes" or "no", indicating whether the list of | value of either "yes" or "no", indicating whether the list of | |||
categories is a fixed or an open set. Attempts to create or update | categories is a fixed or an open set. Attempts to create or update | |||
members whose categories are not listed in the Collection Document | members whose categories are not listed in the Collection Document | |||
MAY be rejected by the server. Collections that indicate the | MAY be rejected by the server. Collections that indicate the | |||
category set is open SHOULD NOT reject otherwise acceptable members | category set is open SHOULD NOT reject otherwise acceptable members | |||
whose categories are not listed by the Collection. | whose categories are not listed by the Collection. | |||
Alternatively, the app:categories element MAY contain an "href" | Alternatively, the app:categories element MAY contain an "href" | |||
skipping to change at page 16, line 15 | skipping to change at page 18, line 15 | |||
8. Service Documents | 8. Service Documents | |||
For authoring to commence, a client needs to discover the | For authoring to commence, a client needs to discover the | |||
capabilities and locations of the available Collections. Service | capabilities and locations of the available Collections. Service | |||
Documents are designed to support this discovery process. How | Documents are designed to support this discovery process. How | |||
Service Documents are discovered is not defined in this | Service Documents are discovered is not defined in this | |||
specification. | specification. | |||
A Service Document describes Workspaces, which are server-defined | A Service Document describes Workspaces, which are server-defined | |||
groups of Collections. Service Documents are identified with the | groups of Collections. Service Documents are identified with the | |||
"application/atomserv+xml" media type (see Section 15). | "application/atomserv+xml" media type (see Section 16). | |||
There is no requirement that a server support multiple Workspaces. | There is no requirement that a server support multiple Workspaces. | |||
In addition, a Collection MAY appear in more than one Workspace. | In addition, a Collection MAY appear in more than one Workspace. | |||
8.1 Example | 8.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#" | |||
xmlns:atom="http://www.w3.org/2005/Atom"> | xmlns:atom="http://www.w3.org/2005/Atom"> | |||
<workspace> | <workspace> | |||
<atom:title>Main Site</atom:title> | <atom:title>Main Site</atom:title> | |||
<collection | <collection | |||
href="http://example.org/reilly/main" > | href="http://example.org/reilly/main" > | |||
<atom:title>My Blog Entries</atom:title> | <atom:title>My Blog Entries</atom:title> | |||
<categories | <categories | |||
skipping to change at page 18, line 13 | skipping to change at page 20, line 13 | |||
"http://example.org/reilly/list". | "http://example.org/reilly/list". | |||
Within each of the two Entry collections, the categories element | Within each of the two Entry collections, the categories element | |||
provides a list of available categories for Member Entries. In the | provides a list of available categories for Member Entries. In the | |||
"My Blog Entries" Collection, the list of available categories is | "My Blog Entries" Collection, the list of available categories is | |||
obtainable through the "href" attribute. The "Side Bar Blog" | obtainable through the "href" attribute. The "Side Bar Blog" | |||
Collection provides a category list within the Service Document, but | Collection provides a category list within the Service Document, but | |||
states the list is fixed, signaling a request from the server that | states the list is fixed, signaling a request from the server that | |||
Entries be POSTed using only those two categories. | Entries be POSTed using only those two categories. | |||
8.2 Element Definitions | 8.2. Element Definitions | |||
8.2.1 The "app:service" Element | 8.2.1. The "app:service" Element | |||
The root of a Service Document is the "app:service" element. | The root of a Service Document is the "app:service" element. | |||
The "app:service" element is the container for service information | The "app:service" element is the container for service information | |||
associated with one or more Workspaces. An app:service element MUST | associated with one or more Workspaces. An app:service element MUST | |||
contain one or more app:workspace elements. | contain one or more app:workspace elements. | |||
namespace app = "http://purl.org/atom/app#" | namespace app = "http://purl.org/atom/app#" | |||
start = appService | start = appService | |||
appService = | appService = | |||
element app:service { | element app:service { | |||
appCommonAttributes, | appCommonAttributes, | |||
( appWorkspace+ | ( appWorkspace+ | |||
& extensionElement* ) | & extensionElement* ) | |||
} | } | |||
8.2.2 The "app:workspace" Element | 8.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 contains zero or more app:collection elements. | element contains zero or more app:collection elements. | |||
appWorkspace = | appWorkspace = | |||
element app:workspace { | element app:workspace { | |||
appCommonAttributes, | appCommonAttributes, | |||
( atomTitle | ( atomTitle | |||
& appCollection* | & appCollection* | |||
& extensionElement* ) | & extensionSansTitleElement* ) | |||
} | } | |||
atomTitle = element atom:title { atomTextConstruct } | atomTitle = element atom:title { atomTextConstruct } | |||
8.2.2.1 The "atom:title" Element | 8.2.2.1. The "atom:title" Element | |||
The app:workspace element MUST contain one "atom:title" element (as | The app:workspace element MUST contain one "atom:title" element (as | |||
defined in [RFC4287]), giving a human-readable title for the | defined in [RFC4287]), giving a human-readable title for the | |||
Workspace. | Workspace. | |||
8.2.3 The "app:collection" Element | 8.2.3. The "app:collection" Element | |||
The "app:collection" element describes a Collection. The app: | The "app:collection" element describes a Collection. The app: | |||
collection element MAY contain one app:accept element and MAY contain | collection element MAY contain one app:accept element and MAY contain | |||
any number of app:categories elements. The app:collection element | any number of app:categories elements. The app:collection element | |||
MUST NOT contain more than one app:accept element. | MUST NOT contain more than one app:accept element. | |||
appCollection = | appCollection = | |||
element app:collection { | element app:collection { | |||
appCommonAttributes, | appCommonAttributes, | |||
attribute href { atomURI }, | attribute href { atomURI }, | |||
( atomTitle | ( atomTitle | |||
& appAccept? | & appAccept? | |||
& appCategories* | & appCategories* | |||
& extensionElement* ) | & extensionSansTitleElement* ) | |||
} | } | |||
8.2.3.1 Usage in Atom Feed Documents | 8.2.3.1. Usage in Atom Feed Documents | |||
The app:collection element MAY appear as a child of an atom:feed or | The app:collection element MAY appear as a child of an atom:feed or | |||
atom:source element in an Atom Feed Document. Its value identifies a | atom:source element in an Atom Feed Document. Its value identifies a | |||
Collection by which new Entries can be added to appear in the feed. | Collection by which new Entries can be added to appear in the feed. | |||
The app:collection element is considered foreign markup as defined in | The app:collection element is considered foreign markup as defined in | |||
Section 6 of [RFC4287]. | Section 6 of [RFC4287]. | |||
8.2.3.2 The "href" Attribute | 8.2.3.2. The "href" Attribute | |||
The app:collection element MUST contain an "href" attribute, whose | The app:collection element MUST contain an "href" attribute, whose | |||
value gives the IRI of the Collection. | value gives the IRI of the Collection. | |||
8.2.3.3 The "atom:title" Element | 8.2.3.3. The "atom:title" Element | |||
The app:collection Element MUST contain one "atom:title" element (as | The app:collection Element MUST contain one "atom:title" element (as | |||
defined in [RFC4287]), giving a human-readable title for the | defined in [RFC4287]), giving a human-readable title for the | |||
Collection. | Collection. | |||
8.2.4 The "app:accept" Element | 8.2.4. The "app:accept" Element | |||
The "app:accept" element value specifies a comma-separated list of | The "app:accept" element value specifies a comma-separated list of | |||
media-ranges (see [RFC2616]) identifying the types of representations | media-ranges (see [RFC2616]) identifying the types of representations | |||
that can be POSTed to the URI of a Collection. Whitespace around and | that can be POSTed to the URI of a Collection. Whitespace around and | |||
between media-range values is considered insignificant and MUST be | between media-range values is considered insignificant and MUST be | |||
ignored. | ignored. | |||
The app:accept element is similar to the HTTP Accept request-header | The app:accept element is similar to the HTTP Accept request-header | |||
[RFC2616] with the exception that app:accept has no notion of | [RFC2616] with the exception that app:accept has no notion of | |||
preference. As a result, the value syntax of app:accept does not use | preference. As a result, the value syntax of app:accept does not use | |||
skipping to change at page 20, line 39 | skipping to change at page 22, line 38 | |||
appAccept = | appAccept = | |||
element app:accept { | element app:accept { | |||
appCommonAttributes, | appCommonAttributes, | |||
( appTypeValue? ) | ( appTypeValue? ) | |||
} | } | |||
appTypeValue = ( "entry" | media-type |entry-or-media-type ) | appTypeValue = ( "entry" | media-type |entry-or-media-type ) | |||
media-type = xsd:string { pattern = "entry,(.+/.+,?)*" } | media-type = xsd:string { pattern = "entry,(.+/.+,?)*" } | |||
entry-or-media-type = xsd:string { pattern = "(.+/.+,?)*" } | entry-or-media-type = xsd:string { pattern = "(.+/.+,?)*" } | |||
8.2.5 The "app:categories" Element | 8.2.5. The "app:categories" Element | |||
The "app:categories" element provides a listing of the categories | The "app:categories" element provides a listing of the categories | |||
that can be applied to the members of a Collection. | that can be applied to the members of a Collection. The absence of | |||
an "app:categories" element means that the category handling of a | ||||
server is unspecified. | ||||
atomCategory = | atomCategory = | |||
element atom:category { | element atom:category { | |||
atomCommonAttributes, | atomCommonAttributes, | |||
attribute term { text }, | attribute term { text }, | |||
attribute scheme { atomURI }?, | attribute scheme { atomURI }?, | |||
attribute label { text }?, | attribute label { text }?, | |||
undefinedContent | undefinedContent | |||
} | } | |||
skipping to change at page 22, line 7 | skipping to change at page 24, line 7 | |||
NOT reject otherwise acceptable members whose categories are not | NOT reject otherwise acceptable members whose categories are not | |||
present in the provided list. | present in the provided list. | |||
The app:categories element MAY contain an "href" attribute, whose | The app:categories element MAY contain an "href" attribute, whose | |||
value MUST be an IRI reference identifying a Category Document. If | value MUST be an IRI reference identifying a Category Document. If | |||
the "href" attribute is provided, the app:categories element MUST be | the "href" attribute is provided, the app:categories element MUST be | |||
empty and the "fixed" and "scheme" attributes MUST NOT be present. | empty and the "fixed" and "scheme" attributes MUST NOT be present. | |||
9. Creating and Editing Resources | 9. Creating and Editing Resources | |||
9.1 Member URIs | 9.1. Member URIs | |||
The Member URI supports retrieving, updating and deleting the | The Member URI supports retrieving, updating and deleting the | |||
resource using HTTP GET, PUT and DELETE. Retrieval and updating of | resource using HTTP GET, PUT and DELETE. Retrieval and updating of | |||
Member Entry Resources are done by exchanging Atom Entry | Member Entry Resources are done by exchanging Atom Entry | |||
representations. | representations. | |||
Member Entry URIs appear in two places. First, they are returned in | Member Entry URIs appear in two places. First, they are returned in | |||
a Location header after successful resource creation using POST, as | a Location header after successful resource creation using POST, as | |||
described below. Second, they appear in the Entries of a Collection | described below. Second, they appear in the Entries of a Collection | |||
document as atom:link elements with a link relation of "edit". | document as atom:link elements with a link relation of "edit". | |||
Each Member Entry SHOULD contain such an atom:link element providing | Each Member Entry SHOULD contain such an atom:link element providing | |||
its Member Entry URI. | its Member Entry URI. | |||
9.2 Creating resources with POST | 9.2. Creating resources with POST | |||
To add members to a Collection, clients send POST requests to the URI | To add members to a Collection, clients send POST requests to the URI | |||
of a Collection. Successful member creation is normally indicated | of a Collection. Successful member creation is normally indicated | |||
with a 201 ("Created") response code. Collections MAY generate a | with a 201 ("Created") response code. Collections MAY generate a | |||
response with a status code of 415 ("Unsupported Media Type") to | response with a status code of 415 ("Unsupported Media Type") to | |||
indicate that the media-type of the POSTed entity is not allowed or | indicate that the media-type of the POSTed entity is not allowed or | |||
supported by the Collection. | supported by the Collection. | |||
When a Member Resource is created in the Collection which received | When a Member Resource is created in the Collection which received | |||
the POST, its Member Entry URI MUST be returned in an HTTP Location | the POST, its Member Entry URI MUST be returned in an HTTP Location | |||
skipping to change at page 23, line 9 | skipping to change at page 25, line 9 | |||
header that matches the Location header character-for-character, then | header that matches the Location header character-for-character, then | |||
the client is authorized to interpret the response entity as being | the client is authorized to interpret the response entity as being | |||
the representation of the newly created Entry. Without a matching | the representation of the newly created Entry. Without a matching | |||
Content-Location header the client MUST NOT assume the returned | Content-Location header the client MUST NOT assume the returned | |||
entity is a complete representation of the created resource. | entity is a complete representation of the created resource. | |||
The request body sent with the POST need not be an Atom Entry. For | The request body sent with the POST need not be an Atom Entry. For | |||
example, it might be a picture, or a movie. For a discussion of the | example, it might be a picture, or a movie. For a discussion of the | |||
issues in POSTing such content, see Section 9.5. | issues in POSTing such content, see Section 9.5. | |||
9.2.1 Example | 9.2.1. Example | |||
Below, the client sends a POST request containing an Atom Entry | Below, the client sends a POST request containing an Atom Entry | |||
representation to the URI of the Collection: | representation to the URI of the Collection: | |||
POST /myblog/entries HTTP/1.1 | POST /myblog/entries HTTP/1.1 | |||
Host: example.org | Host: example.org | |||
User-Agent: Thingio/1.0 | User-Agent: Thingio/1.0 | |||
Authorization: Basic ZGFmZnk6c2VjZXJldA== | Authorization: Basic ZGFmZnk6c2VjZXJldA== | |||
Content-Type: application/atom+xml | Content-Type: application/atom+xml | |||
Content-Length: nnn | Content-Length: nnn | |||
Slug: First Post | Slug: First Post | |||
<?xml version="1.0" ?> | <?xml version="1.0" ?> | |||
<entry xmlns="http://www.w3.org/2005/Atom" | <entry xmlns="http://www.w3.org/2005/Atom"> | |||
xmlns:app="http://purl.org/atom/app#"> | ||||
<title>Atom-Powered Robots Run Amok</title> | <title>Atom-Powered Robots Run Amok</title> | |||
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> | <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> | |||
<updated>2003-12-13T18:30:02Z</updated> | <updated>2003-12-13T18:30:02Z</updated> | |||
<author><name>John Doe</name></author> | <author><name>John Doe</name></author> | |||
<content>Some text.</content> | <content>Some text.</content> | |||
</entry> | </entry> | |||
The server signals a successful creation with a status code of 201. | The server signals a successful creation with a status code of 201. | |||
The response includes a Location: header indicating the Member Entry | The response includes a Location: header indicating the Member Entry | |||
URI of the Atom Entry and a representation of that Entry in the body | URI of the Atom Entry and a representation of that Entry in the body | |||
of the response. | of the response. | |||
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: nnn | Content-Length: nnn | |||
Content-Type: application/atom+xml; charset="utf-8" | Content-Type: application/atom+xml; charset="utf-8" | |||
Location: http://example.org/edit/first-post.atom | Location: http://example.org/edit/first-post.atom | |||
<?xml version="1.0"?> | <?xml version="1.0"?> | |||
<entry xmlns="http://www.w3.org/2005/Atom" | <entry xmlns="http://www.w3.org/2005/Atom"> | |||
xmlns:app="http://purl.org/atom/app#"> | ||||
<title>Atom-Powered Robots Run Amok</title> | <title>Atom-Powered Robots Run Amok</title> | |||
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> | <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> | |||
<updated>2003-12-13T18:30:02Z</updated> | <updated>2003-12-13T18:30:02Z</updated> | |||
<author><name>John Doe</name></author> | <author><name>John Doe</name></author> | |||
<content>Some text.</content> | <content>Some text.</content> | |||
<link rel="edit" | <link rel="edit" | |||
href="http://example.org/edit/first-post.atom"/> | href="http://example.org/edit/first-post.atom"/> | |||
</entry> | </entry> | |||
The created Entry returned by the server might not match the Entry | The created Entry returned by the server might not match the Entry | |||
POSTed by the client. A server MAY change the values of various | POSTed by the client. A server MAY change the values of various | |||
elements in the Entry such as the atom:id, atom:updated and atom: | elements in the Entry such as the atom:id, atom:updated and atom: | |||
author values and MAY choose to remove or add other elements and | author values and MAY choose to remove or add other elements and | |||
attributes, or change element and attribute values. | attributes, or change element and attribute values. | |||
In particular, the publishing system in this example filled in some | 9.3. Updating Resources with PUT | |||
values not provided in the original POST. For example, it | ||||
ascertained the name of the author, presumably via the authentication | ||||
protocol used to establish the right to post. | ||||
9.3 Updating Resources with PUT | ||||
To update a resource, clients send PUT requests to its Member URI, as | To update a resource, clients send PUT requests to its Member URI, as | |||
specified in [RFC2616]. | specified in [RFC2616]. | |||
To avoid unintentional loss of data when editing Member Entries or | To avoid unintentional loss of data when editing Member Entries or | |||
Media Link Entries, Atom Protocol clients SHOULD preserve all | Media Link Entries, Atom Protocol clients SHOULD preserve all | |||
metadata that has not been intentionally modified, including unknown | metadata that has not been intentionally modified, including unknown | |||
foreign markup as defined in Section 6 of [RFC4287]. | foreign markup as defined in Section 6 of [RFC4287]. | |||
9.4 Deleting Resources with DELETE | 9.4. Deleting Resources with DELETE | |||
To delete a resource, clients send DELETE requests to its Member URI, | To delete a resource, clients send DELETE requests to its Member URI, | |||
as specified in [RFC2616]. For Media Resources, deletion of a Media | as specified in [RFC2616]. For Media Resources, deletion of a Media | |||
Link Entry SHOULD result in the deletion of the associated Media | Link Entry SHOULD result in the deletion of the associated Media | |||
Resource. | Resource. | |||
9.5 Media Resources and Media Link Entries | 9.5. Media Resources and Media Link Entries | |||
A client can POST a media type other than application/atom+xml to a | A client can POST a media type other than application/atom+xml to a | |||
Collection. Such a request always creates two new resources - one | Collection. Such a request always creates two new resources - one | |||
that corresponds to the entity sent in the request, called the Media | that corresponds to the entity sent in the request, called the Media | |||
Resource, and an associated Member Entry, called the Media Link | Resource, and an associated Member Entry, called the Media Link | |||
Entry. Media Link Entries are represented as Atom Entries. The | Entry. Media Link Entries are represented as Atom Entries. The | |||
server can signal the media types it will accept via the "accept" | server can signal the media types it will accept via the "accept" | |||
element in the Service Document (Section 8.2.4). | element in the Service Document (Section 8.2.4). | |||
The Media Link Entry contains the IRI of, and metadata about, the | The Media Link Entry contains the IRI of, and metadata about, the | |||
skipping to change at page 26, line 5 | skipping to change at page 27, line 27 | |||
media type. It does not specify any request semantics or server | media type. It does not specify any request semantics or server | |||
behavior in the case where the POSTed media-type is "application/ | behavior in the case where the POSTed media-type is "application/ | |||
atom+xml" but the body is something other than an Atom Entry. In | atom+xml" but the body is something other than an Atom Entry. In | |||
particular, what happens on POSTing an Atom Feed Document to a | particular, what happens on POSTing an Atom Feed Document to a | |||
Collection using the "application/atom+xml" media type is undefined. | Collection using the "application/atom+xml" media type is undefined. | |||
The Atom Protocol does not specify a means to create multiple | The Atom Protocol does not specify a means to create multiple | |||
representations of the same resource (for example a PNG and a JPG of | representations of the same resource (for example a PNG and a JPG of | |||
the same image) on creation or update. | the same image) on creation or update. | |||
9.5.1 Examples | 9.5.1. Examples | |||
Below, the client sends a POST request containing a PNG image to the | Below, the client sends a POST request containing a PNG image to the | |||
URI of a Collection that accepts PNG images: | URI of a Collection that accepts PNG images: | |||
POST /media/ HTTP/1.1 | POST /media/ HTTP/1.1 | |||
Host: example.org | Host: example.org | |||
Content-Type: image/png | Content-Type: image/png | |||
Slug: The Beach | Slug: The Beach | |||
Authorization: Basic ZGFmZnk6c2VjZXJldA== | Authorization: Basic ZGFmZnk6c2VjZXJldA== | |||
Content-Length: nnn | Content-Length: nnn | |||
skipping to change at page 31, line 40 | skipping to change at page 32, line 40 | |||
href="http://example.org/blog/edit/a-day-at-the-beach.atom"/> | href="http://example.org/blog/edit/a-day-at-the-beach.atom"/> | |||
<link rel="alternate" type="application/xhtml+xml" | <link rel="alternate" type="application/xhtml+xml" | |||
href="http://example.org/blog/a-day-at-the-beach.xhtml"/> | href="http://example.org/blog/a-day-at-the-beach.xhtml"/> | |||
</entry> | </entry> | |||
Note that the returned Entry contains a link with a relation of | Note that the returned Entry contains a link with a relation of | |||
"alternate" that points to the associated XHTML page that was | "alternate" that points to the associated XHTML page that was | |||
created. This is not required by this specification, but is included | created. This is not required by this specification, but is included | |||
to show the kinds of changes a server may make to an Entry. | to show the kinds of changes a server may make to an Entry. | |||
9.6 The Slug: Header | 9.6. The Slug: Header | |||
Slug is a HTTP entity-header whose value is a short name that, when | Slug is a HTTP entity-header whose value is a short name that, when | |||
accompanying a POST to a Collection, constitutes a request by the | accompanying a POST to a Collection, constitutes a request by the | |||
client that its value be used as part of the URI for the to-be- | client that its value be used as part of the URI for the to-be- | |||
created Member Resource. | created Member Resource. | |||
When POSTing an entity to a Collection to add a new Member, the | When POSTing an entity to a Collection to add a new Member, the | |||
server MAY use this information when creating the Member URI of the | server MAY use this information when creating the Member URI of the | |||
newly-created resource, for instance by using some or all of the | newly-created resource, for instance by using some or all of the | |||
words in the last URI segment. It MAY also use it when creating the | words in the last URI segment. It MAY also use it when creating the | |||
atom:id or as the title of a Media Link Entry (see Section 9.5.). | atom:id or as the title of a Media Link Entry (see Section 9.5.). | |||
Servers MAY ignore the Slug entity-header and MAY alter its value | Servers MAY ignore the Slug entity-header and MAY alter its value | |||
before using it. For example, the server MAY filter out some | before using it. For example, the server MAY filter out some | |||
characters or replace accented letters with non-accented ones, spaces | characters or replace accented letters with non-accented ones, spaces | |||
with underscores, etc. | with underscores, etc. | |||
9.6.1 Slug: Header syntax | 9.6.1. Slug: Header syntax | |||
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]. The TEXT | in section 2.1 of the HTTP/1.1 specification [RFC2616]. The TEXT | |||
rule is described in section 2.2 of the same document. | rule is described in section 2.2 of the same document. | |||
Slug = "Slug" ":" *TEXT | Slug = "Slug" ":" *TEXT | |||
Clients MAY send non-ASCII characters in the Slug entity-header, | Clients MAY send non-ASCII characters in the Slug entity-header, | |||
which they MUST encode using "encoded-words", as defined in | which they MUST encode using "encoded-words", as defined in | |||
[RFC2047]. Servers SHOULD treat the slug as [RFC2047] encoded if it | [RFC2047]. Servers SHOULD treat the slug as [RFC2047] encoded if it | |||
matches the "encoded-words" production. | matches the "encoded-words" production. | |||
9.6.2 Example | 9.6.2. Example | |||
Here is an example of the Slug: header that uses the encoding rules | Here is an example of the Slug: header that uses the encoding rules | |||
of [RFC2047]. | of [RFC2047]. | |||
POST /myblog/entries HTTP/1.1 | POST /myblog/entries HTTP/1.1 | |||
Host: example.org | Host: example.org | |||
Content-Type: image/png | Content-Type: image/png | |||
Slug: =?iso-8859-1?q?The_Beach?= | Slug: =?iso-8859-1?q?The_Beach?= | |||
Authorization: Basic ZGFmZnk6c2VjZXJldA== | Authorization: Basic ZGFmZnk6c2VjZXJldA== | |||
Content-Length: nnn | Content-Length: nnn | |||
skipping to change at page 33, line 31 | skipping to change at page 34, line 31 | |||
in a Collection. That is, the Atom Syndication Format states that | in a Collection. That is, the Atom Syndication Format states that | |||
the value of atom:updated is altered when the changes to an Entry are | the value of atom:updated is altered when the changes to an Entry are | |||
something that "the publisher considers significant." The atom: | something that "the publisher considers significant." The atom: | |||
updated value is not equivalent to the HTTP Last-Modified: header and | updated value is not equivalent to the HTTP Last-Modified: header and | |||
can not be used to determine the freshness of cached responses. | can not be used to determine the freshness of cached responses. | |||
Clients MUST NOT assume that an Atom Entry returned in the Feed is a | Clients MUST NOT assume that an Atom Entry returned in the Feed is a | |||
full representation of a Member Entry Resource and SHOULD perform a | full representation of a Member Entry Resource and SHOULD perform a | |||
GET on the URI of the Member Entry before editing. | GET on the URI of the Member Entry before editing. | |||
10.1 Collection Paging | 10.1. Collection Paging | |||
Collections can contain large numbers of resources. A naive client | Collections can contain large numbers of resources. A naive client | |||
such as a web spider or web browser could be overwhelmed if the | such as a web spider or web browser could be overwhelmed if the | |||
response to a GET contained every Entry in the Collection, 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. For this reason, servers MAY | clients unable to handle the response. For this reason, servers MAY | |||
return a partial listing of the most recently updated Member | return a partial listing of the most recently updated Member | |||
Resources. Such partial feed documents MUST have an atom:link with a | Resources. Such partial feed documents MUST have an atom:link with a | |||
"next" relation whose "href" value is the URI of the next partial | "next" relation whose "href" value is the URI of the next partial | |||
listing of the Collection (the next most recently updated Member | listing of the Collection (the next most recently updated Member | |||
skipping to change at page 34, line 37 | skipping to change at page 35, line 37 | |||
href="http://example.org/entries/go" /> | href="http://example.org/entries/go" /> | |||
<link rel="previous" | <link rel="previous" | |||
href="http://example.org/entries/go" /> | href="http://example.org/entries/go" /> | |||
<link rel="next" | <link rel="next" | |||
href="http://example.org/entries/3" /> | href="http://example.org/entries/3" /> | |||
<link rel="last" | <link rel="last" | |||
href="http://example.org/entries/10" /> | href="http://example.org/entries/10" /> | |||
... | ... | |||
</feed> | </feed> | |||
10.2 The "app:edited" Element | 10.2. The "app:edited" Element | |||
The "app:edited" element is a Date construct as defined by [RFC4287] | The "app:edited" element is a Date construct as defined by [RFC4287] | |||
whose value indicates the most recent instant in time when an Entry | whose value indicates the most recent instant in time when an Entry | |||
was edited, including when created. Atom Entry elements in | was edited, including when created. Atom Entry elements in | |||
Collection documents SHOULD contain one "app:edited" element, and | Collection documents SHOULD contain one "app:edited" element, and | |||
MUST NOT contain more than one. | MUST NOT contain more than one. | |||
appEdited = element app:edited ( atomDateConstruct ) | appEdited = element app:edited ( atomDateConstruct ) | |||
The server SHOULD change the value of this element every time a | The server SHOULD change the value of this element every time a | |||
Collection Member Resource or an associated Media Resource has been | Collection Member Resource or an associated Media Resource has been | |||
edited. | edited. | |||
11. Atom Format Link Relation Extensions | 11. Atom Format Link Relation Extensions | |||
11.1 The "edit" Link Relation | 11.1. The "edit" Link Relation | |||
This specification adds the value "edit" to the Atom Registry of Link | This specification adds the value "edit" to the Atom Registry of Link | |||
Relations (see section 7.1 of [RFC4287]). The value of "edit" | Relations (see section 7.1 of [RFC4287]). The value of "edit" | |||
specifies that the value of the href attribute is the IRI of an | specifies that the value of the href attribute is the IRI of an | |||
editable Member Entry. When appearing within an atom:entry, the href | editable Member Entry. When appearing within an atom:entry, the href | |||
IRI can be used to retrieve, update and delete the resource | IRI can be used to retrieve, update and delete the resource | |||
represented by that Entry. An atom:entry MUST contain no more than | represented by that Entry. An atom:entry MUST contain no more than | |||
one "edit" link relation. | one "edit" link relation. | |||
11.2 The "edit-media" Link Relation | 11.2. The "edit-media" Link Relation | |||
This specification adds the value "edit-media" to the Atom Registry | This specification adds the value "edit-media" to the Atom Registry | |||
of Link Relations (see section 7.1 of [RFC4287]). When appearing | of Link Relations (see section 7.1 of [RFC4287]). When appearing | |||
within an atom:entry, the value of the href attribute is an IRI that | within an atom:entry, the value of the href attribute is an IRI that | |||
can be used to modify a Media Resource associated with that Entry. | can be used to modify a Media Resource associated with that Entry. | |||
An atom:entry element MAY contain zero or more "edit-media" link | An atom:entry element MAY contain zero or more "edit-media" link | |||
relations. An atom:entry MUST NOT contain more than one atom:link | relations. An atom:entry MUST NOT contain more than one atom:link | |||
element with a rel attribute value of "edit-media" that has the same | element with a rel attribute value of "edit-media" that has the same | |||
"type" and "hreflang" attribute values. All "edit-media" link | "type" and "hreflang" attribute values. All "edit-media" link | |||
relations in the same Entry reference the same resource. If a client | relations in the same Entry reference the same resource. If a client | |||
encounters multiple "edit-media" link relations in an Entry then it | encounters multiple "edit-media" link relations in an Entry then it | |||
SHOULD choose a link based on the client preferences for "type" and | SHOULD choose a link based on the client preferences for "type" and | |||
"hreflang". If a client encounters multiple "edit-media" link | "hreflang". If a client encounters multiple "edit-media" link | |||
relations in an Entry and has no preference based on the "type" and | relations in an Entry and has no preference based on the "type" and | |||
"hreflang" attributes then the client SHOULD pick the first "edit- | "hreflang" attributes then the client SHOULD pick the first "edit- | |||
media" link relation in document order. | media" link relation in document order. | |||
12. Atom Publishing Controls | 12. The Atom Format Type Parameter | |||
The Atom Syndication Format (RFC 4287) defines the 'application/ | ||||
atom+xml' media type to identify both Atom Feed and Atom Entry | ||||
Documents. Implementation experience has demonstrated that Atom Feed | ||||
and Entry Documents can have different processing models and that | ||||
there are situations where they need to be differentiated. This | ||||
document defines an optional 'type' parameter used to differentiate | ||||
the two types of Atom documents. | ||||
12.1. The 'type' parameter | ||||
This document defines a new "type" parameter for use with the | ||||
'application/atom+xml' media type. | ||||
type = "entry" / "feed" | ||||
Neither the parameter name nor its value are case sensitive. | ||||
The value 'entry' indicates that the media type identifies an Atom | ||||
Entry Document. The root element of the document MUST be atom:entry. | ||||
The value 'feed' indicates that the media type identifies an Atom | ||||
Feed Document. The root element of the document MUST be atom:feed. | ||||
If not specified, the type is assumed to be unspecified, requiring | ||||
Atom processors to examine the root element to determine the type of | ||||
Atom document. | ||||
12.1.1. Conformance | ||||
New specifications MAY require that the type parameter be used to | ||||
identify the Atom Document type. Producers of Atom Entry Documents | ||||
SHOULD use the type parameter regardless of whether or not it is | ||||
required. Producers of Atom Feed Documents MAY use the parameter. | ||||
Atom processors that do not recognize the 'type' parameter MUST | ||||
ignore its value and examine the root element to determine the | ||||
document type. | ||||
Atom processors that do recognize the parameter SHOULD detect and | ||||
report inconsistencies between the parameter's value and the actual | ||||
type of the document's root element. | ||||
13. Atom Publishing Controls | ||||
This specification defines an Atom Format Structured Extension, as | This specification defines an Atom Format Structured Extension, as | |||
defined in Section 6 of [RFC4287], for publishing control within the | defined in Section 6 of [RFC4287], for publishing control within the | |||
"http://purl.org/atom/app#" namespace. | "http://purl.org/atom/app#" namespace. | |||
12.1 The "app:control" Element | 13.1. The "app:control" Element | |||
namespace app = "http://purl.org/atom/app#" | namespace app = "http://purl.org/atom/app#" | |||
pubControl = | pubControl = | |||
element app:control { | element app:control { | |||
atomCommonAttributes, | atomCommonAttributes, | |||
pubDraft? | pubDraft? | |||
& extensionElement | & extensionElement | |||
} | } | |||
skipping to change at page 36, line 38 | skipping to change at page 38, line 38 | |||
control element is considered foreign markup as defined in Section 6 | control element is considered foreign markup as defined in Section 6 | |||
of [RFC4287]. | of [RFC4287]. | |||
The app:control element and its child elements MAY be included in | The app:control element and its child elements MAY be included in | |||
Atom Feed or Entry Documents. | Atom Feed or Entry Documents. | |||
The app:control element can contain an optional "app:draft" element | The app:control element can contain an optional "app:draft" element | |||
as defined below, and can contain extension elements as defined in | as defined below, and can contain extension elements as defined in | |||
Section 6 of [RFC4287]. | Section 6 of [RFC4287]. | |||
12.1.1 The "app:draft" Element | 13.1.1. The "app:draft" Element | |||
The number of app:draft elements in app:control MUST be zero or one. | The number of app:draft elements in app:control MUST be zero or one. | |||
Its value MUST be one of "yes" or "no". A value of "no" indicates a | Its value MUST be one of "yes" or "no". A value of "no" indicates a | |||
client request that the Member Resource be made publicly visible. If | client request that the Member Resource be made publicly visible. If | |||
the app:draft element is missing then the value MUST be understood to | the app:draft element is missing then the value MUST be understood to | |||
be "no". The inclusion of the app:draft element represents a request | be "no". The inclusion of the app:draft element represents a request | |||
by the client to control the visibility of a Member Resource and the | by the client to control the visibility of a Member Resource and the | |||
app:draft element MAY be ignored by the server. | app:draft element MAY be ignored by the server. | |||
13. Securing the Atom Publishing Protocol | 14. Securing the Atom Publishing Protocol | |||
The Atom Publishing Protocol is based on HTTP. Authentication | The Atom Publishing Protocol is based on HTTP. Authentication | |||
requirements for HTTP are covered in Section 11 of [RFC2616]. | requirements for HTTP are covered in Section 11 of [RFC2616]. | |||
The use of authentication mechanisms to prevent POSTing or editing by | The use of authentication mechanisms to prevent POSTing or editing by | |||
unknown or unauthorized clients is RECOMMENDED but not required. | unknown or unauthorized clients is RECOMMENDED but not required. | |||
When authentication is not used, clients and servers are vulnerable | When authentication is not used, clients and servers are vulnerable | |||
to trivial spoofing, denial of service and defacement attacks, | to trivial spoofing, denial of service and defacement attacks, | |||
however, in some contexts, this is an acceptable risk. | however, in some contexts, this is an acceptable risk. | |||
skipping to change at page 38, line 5 | skipping to change at page 40, line 5 | |||
good or better at the time of deployment. It is RECOMMENDED that | good or better at the time of deployment. It is RECOMMENDED that | |||
clients be implemented in such a way that allows new authentication | clients be implemented in such a way that allows new authentication | |||
schemes to be deployed. | schemes to be deployed. | |||
Because this protocol uses HTTP response status codes as the primary | Because this protocol uses HTTP response status codes as the primary | |||
means of reporting the result of a request, servers are advised to | means of reporting the result of a request, servers are advised to | |||
respond to unauthorized or unauthenticated requests using an | respond to unauthorized or unauthenticated requests using an | |||
appropriate 4xx HTTP response code (e.g. 401 "Unauthorized" or 403 | appropriate 4xx HTTP response code (e.g. 401 "Unauthorized" or 403 | |||
"Forbidden") in accordance with [RFC2617]. | "Forbidden") in accordance with [RFC2617]. | |||
14. Security Considerations | 15. Security Considerations | |||
As an HTTP-based protocol, APP is subject to the security | As an HTTP-based protocol, APP is subject to the security | |||
considerations found in Section 15 of [RFC2616]. | considerations found in Section 15 of [RFC2616]. | |||
14.1 Denial of Service | 15.1. Denial of Service | |||
Atom Publishing server implementations need to take adequate | Atom Publishing server implementations need to take adequate | |||
precautions to ensure malicious clients cannot consume excessive | precautions to ensure malicious clients cannot consume excessive | |||
server resources (CPU, memory, disk, etc). | server resources (CPU, memory, disk, etc). | |||
14.2 Replay Attacks | 15.2. Replay Attacks | |||
Atom Publishing server implementations are susceptible to replay | Atom Publishing server implementations are susceptible to replay | |||
attacks. Specifically, this specification does not define a means of | attacks. Specifically, this specification does not define a means of | |||
detecting duplicate requests. Accidentally sent duplicate requests | detecting duplicate requests. Accidentally sent duplicate requests | |||
are indistinguishable from intentional and malicious replay attacks. | are indistinguishable from intentional and malicious replay attacks. | |||
14.3 Spoofing Attacks | 15.3. Spoofing Attacks | |||
Atom Publishing implementations are susceptible to a variety of | Atom Publishing implementations are susceptible to a variety of | |||
spoofing attacks. Malicious clients may send Atom Entries containing | spoofing attacks. Malicious clients may send Atom Entries containing | |||
inaccurate information anywhere in the document. | inaccurate information anywhere in the document. | |||
14.4 Linked Resources | 15.4. Linked Resources | |||
Atom Feed and Entry documents can contain XML External Entities as | Atom Feed and Entry documents can contain XML External Entities as | |||
defined in Section 4.2.2 of [W3C.REC-xml-20060816]. Atom | defined in Section 4.2.2 of [W3C.REC-xml]. Atom implementations are | |||
implementations are not required to load external entities. External | not required to load external entities. External entities are | |||
entities are subject to the same security concerns as any network | subject to the same security concerns as any network operation and | |||
operation and can alter the semantics of an Atom document. The same | can alter the semantics of an Atom document. The same issues exist | |||
issues exist for resources linked to by Atom elements such as atom: | for resources linked to by Atom elements such as atom:link and atom: | |||
link and atom:content. | content. | |||
14.5 Digital Signatures and Encryption | 15.5. Digital Signatures and Encryption | |||
Atom Entry Documents sent to a server might contain XML Digital | Atom Entry Documents sent to a server might contain XML Digital | |||
Signatures [W3C.REC-xmldsig-core-20020212] and might be encrypted | Signatures [W3C.REC-xmldsig-core] and might be encrypted using XML | |||
using XML Encryption [W3C.REC-xmlenc-core-20021210] as specified in | Encryption [W3C.REC-xmlenc-core] as specified in Section 5 of | |||
Section 5 of [RFC4287]. | [RFC4287]. | |||
Servers are allowed to modify received resource representations in | Servers are allowed to modify received resource representations in | |||
ways that can invalidate signatures covering those representations. | ways that can invalidate signatures covering those representations. | |||
14.6 URIs and IRIs | 15.6. URIs and IRIs | |||
Atom Publishing Protocol implementations handle URIs and IRIs. See | Atom Publishing Protocol implementations handle URIs and IRIs. See | |||
Section 7 of [RFC3986] and Section 8 of [RFC3987]. | Section 7 of [RFC3986] and Section 8 of [RFC3987]. | |||
15. IANA Considerations | 16. IANA Considerations | |||
15.1 Content-type registration for 'application/atomserv+xml' | 16.1. Content-type registration for 'application/atomserv+xml' | |||
An Atom Publishing Protocol Service Document, when serialized as XML | An Atom Publishing Protocol Service Document, when serialized as XML | |||
1.0, can be identified with the following media type: | 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. | |||
[[anchor31: 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. [[anchor32: 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 40, line 16 | skipping to change at page 42, line 16 | |||
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). [[anchor33: | Author/Change controller: This specification's author(s). | |||
update upon publication]] | [[anchor34: update upon publication]] | |||
15.2 Content-type registration for 'application/atomcat+xml' | 16.2. Content-type registration for 'application/atomcat+xml' | |||
An Atom Publishing Protocol Category Document, when serialized as XML | An Atom Publishing Protocol Category Document, when serialized as XML | |||
1.0, can be identified with the following media type: | 1.0, can be identified with the following media type: | |||
MIME media type name: application | MIME media type name: application | |||
MIME subtype name: atomcat+xml | MIME subtype name: atomcat+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. | |||
[[anchor34: update upon publication]] | [[anchor35: 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. [[anchor35: update upon | Published specification: This specification. [[anchor36: 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 41, line 30 | skipping to change at page 43, line 30 | |||
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). [[anchor36: | Author/Change controller: This specification's author(s). | |||
update upon publication]] | [[anchor37: update upon publication]] | |||
15.3 Header field registration for 'SLUG' | ||||
[[anchor37: incomplete section --dehora]] | 16.3. Header field registration for 'SLUG' | |||
Header field: SLUG | Header field: SLUG | |||
Applicable protocol: http [RFC2616] | Applicable protocol: http [RFC2616] | |||
Status: standard. | Status: standard. | |||
Author/Change controller: IETF (iesg@ietf.org) Internet Engineering | Author/Change controller: IETF (iesg@ietf.org) Internet Engineering | |||
Task Force | Task Force | |||
Specification document(s): draft-ietf-atompub-protocol-11.txt | Specification document(s): draft-ietf-atompub-protocol-13.txt | |||
([[anchor38: update on rfc number assignment --dehora]]) | ([[anchor38: update on rfc number assignment]]) | |||
Related information: | Related information: | |||
16. References | 16.4. The Link Relation registration "edit" | |||
16.1 Normative References | Attribute Value: edit | |||
Description: An IRI of an editable Member Entry. When appearing | ||||
within an atom:entry, the href IRI can be used to retrieve, update | ||||
and delete the resource represented by that Entry. | ||||
Expected display characteristics: Undefined; this relation can be | ||||
used for background processing or to provide extended | ||||
functionality without displaying its value. | ||||
Security considerations: Automated agents should take care when this | ||||
relation crosses administrative domains (e.g., the URI has a | ||||
different authority than the current document). | ||||
16.5. The Link Relation registration "edit-media" | ||||
Attribute Value: edit-media | ||||
Description: An IRI of an editable Media Resource. When appearing | ||||
within an atom:entry, the href IRI can be used to retrieve, update | ||||
and delete the Media Resource associated with that Entry. | ||||
Expected display characteristics: Undefined; this relation can be | ||||
used for background processing or to provide extended | ||||
functionality without displaying its value. | ||||
Security considerations: Automated agents should take care when this | ||||
relation crosses administrative domains (e.g., the URI has a | ||||
different authority than the current document). | ||||
16.6. The Atom Format Media Type Parameter | ||||
IANA is requested to add a reference to this specification in the | ||||
'application/atom+xml' media type registration. | ||||
17. References | ||||
17.1. Normative References | ||||
[RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) | [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) | |||
Part Three: Message Header Extensions for Non-ASCII Text", | Part Three: Message Header Extensions for Non-ASCII Text", | |||
RFC 2047, November 1996. | RFC 2047, November 1996. | |||
[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. | |||
[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 | |||
skipping to change at page 43, line 43 | skipping to change at page 45, line 43 | |||
[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 | [RFC4287] Nottingham, M. and R. Sayre, "The Atom Syndication | |||
Format", RFC 4287, December 2005. | Format", RFC 4287, December 2005. | |||
[RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security | [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security | |||
(TLS) Protocol Version 1.1", RFC 4346, April 2006. | (TLS) Protocol Version 1.1", RFC 4346, April 2006. | |||
[W3C.REC-xml-20060816] | [W3C.REC-xml] | |||
Bray, T., Paoli, J., Maler, E., Sperberg-McQueen, C., and | Yergeau, F., Paoli, J., Bray, T., Sperberg-McQueen, C., | |||
F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fourth | and E. Maler, "Extensible Markup Language (XML) 1.0 | |||
Edition)", World Wide Web Consortium Recommendation REC- | (Fourth Edition)", World Wide Web Consortium | |||
xml-20060816, August 2006. | Recommendation REC-xml-20060816, August 2006, | |||
<http://www.w3.org/TR/2006/REC-xml-20060816>. | ||||
[W3C.REC-xml-infoset-20040204] | [W3C.REC-xml-infoset] | |||
Cowan, J., Tobin, R., and A. Layman, "XML Information Set | Cowan, J. and R. Tobin, "XML Information Set (Second | |||
(Second Edition)", W3C REC W3C.REC-xml-infoset-20040204, | Edition)", World Wide Web Consortium Recommendation REC- | |||
February 2004. | xml-infoset-20040204, February 2004, | |||
<http://www.w3.org/TR/2004/REC-xml-infoset-20040204>. | ||||
[W3C.REC-xml-names-20060816] | [W3C.REC-xml-names] | |||
Hollander, D., Bray, T., and A. Layman, "Namespaces in | Hollander, D., Bray, T., Tobin, R., and A. Layman, | |||
XML", World Wide Web Consortium Recommendation REC-xml- | "Namespaces in XML 1.0 (Second Edition)", World Wide Web | |||
names-20060816, August 2006. | Consortium Recommendation REC-xml-names-20060816, | |||
August 2006, | ||||
<http://www.w3.org/TR/2006/REC-xml-names-20060816>. | ||||
[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. | |||
[W3C.REC-xmldsig-core-20020212] | [W3C.REC-xmldsig-core] | |||
Solo, D., Reagle, J., and D. Eastlake, "XML-Signature | Solo, D., Reagle, J., and D. Eastlake, "XML-Signature | |||
Syntax and Processing", World Wide Web Consortium | Syntax and Processing", World Wide Web Consortium | |||
Recommendation REC-xmldsig-core-20020212, February 2002, | Recommendation REC-xmldsig-core-20020212, February 2002, | |||
<http://www.w3.org/TR/2002/REC-xmldsig-core-20020212>. | <http://www.w3.org/TR/2002/REC-xmldsig-core-20020212>. | |||
[W3C.REC-xmlenc-core-20021210] | [W3C.REC-xmlenc-core] | |||
Eastlake, D. and J. Reagle, "XML Encryption Syntax and | Eastlake, D. and J. Reagle, "XML Encryption Syntax and | |||
Processing", World Wide Web Consortium Recommendation REC- | Processing", World Wide Web Consortium Recommendation REC- | |||
xmlenc-core-20021210, December 2002, | xmlenc-core-20021210, December 2002, | |||
<http://www.w3.org/TR/2002/REC-xmlenc-core-20021210>. | <http://www.w3.org/TR/2002/REC-xmlenc-core-20021210>. | |||
16.2 Informative References | 17.2. Informative References | |||
[RNC] Clark, J., "RELAX NG Compact Syntax", December 2001. | [RNC] Clark, J., "RELAX NG Compact Syntax", December 2001, <http | |||
://www.oasis-open.org/committees/relax-ng/ | ||||
compact-20021121.html>. | ||||
[W3C.REC-webarch-20041215] | [W3C.REC-webarch-20041215] | |||
Walsh, N. and I. Jacobs, "Architecture of the World Wide | Walsh, N. and I. Jacobs, "Architecture of the World Wide | |||
Web, Volume One", W3C REC REC-webarch-20041215, | Web, Volume One", W3C REC REC-webarch-20041215, | |||
December 2004. | December 2004. | |||
URIs | URIs | |||
[1] <http://www.imc.org/atom-protocol/index.html> | [1] <http://www.imc.org/atom-protocol/index.html> | |||
Authors' Addresses | ||||
Joe Gregorio (editor) | ||||
IBM | ||||
4205 South Miama Blvd. | ||||
Research Triangle Park, NC 27709 | ||||
US | ||||
Phone: +1 919 272 3764 | ||||
Email: joe@bitworking.org | ||||
URI: http://ibm.com/ | ||||
Bill de hOra (editor) | ||||
Propylon Ltd. | ||||
45 Blackbourne Square, Rathfarnham Gate | ||||
Dublin, Dublin D14 | ||||
IE | ||||
Phone: +353-1-4927444 | ||||
Email: bill.dehora@propylon.com | ||||
URI: http://www.propylon.com/ | ||||
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. | |||
[[anchor42: chairs to compile a contribution list for 1.0 --dehora]] | [[anchor42: chairs to compile a contribution list for 1.0 --dehora]] | |||
Appendix B. RELAX NG Compact Schema | Appendix B. RELAX NG Compact Schema | |||
This appendix is informative. | This appendix is informative. | |||
skipping to change at page 48, line 20 | skipping to change at page 50, line 20 | |||
& extensionElement* ) | & extensionElement* ) | |||
} | } | |||
# app:workspace | # app:workspace | |||
appWorkspace = | appWorkspace = | |||
element app:workspace { | element app:workspace { | |||
appCommonAttributes, | appCommonAttributes, | |||
( atomTitle | ( atomTitle | |||
& appCollection* | & appCollection* | |||
& extensionElement* ) | & extensionSansTitleElement* ) | |||
} | } | |||
atomTitle = element atom:title { atomTextConstruct } | atomTitle = element atom:title { atomTextConstruct } | |||
# app:collection | # app:collection | |||
appCollection = | appCollection = | |||
element app:collection { | element app:collection { | |||
appCommonAttributes, | appCommonAttributes, | |||
attribute href { atomURI }, | attribute href { atomURI }, | |||
( atomTitle | ( atomTitle | |||
& appAccept? | & appAccept? | |||
& appCategories* | & appCategories* | |||
& extensionElement* ) | & extensionSansTitleElement* ) | |||
} | } | |||
# app:categories | # app:categories | |||
atomCategory = | atomCategory = | |||
element atom:category { | element atom:category { | |||
atomCommonAttributes, | atomCommonAttributes, | |||
attribute term { text }, | attribute term { text }, | |||
attribute scheme { atomURI }?, | attribute scheme { atomURI }?, | |||
attribute label { text }?, | attribute label { text }?, | |||
skipping to change at page 49, line 30 | skipping to change at page 51, line 30 | |||
( appTypeValue? ) | ( appTypeValue? ) | |||
} | } | |||
appTypeValue = ( "entry" | media-type |entry-or-media-type ) | appTypeValue = ( "entry" | media-type |entry-or-media-type ) | |||
media-type = xsd:string { pattern = "entry,(.+/.+,?)*" } | media-type = xsd:string { pattern = "entry,(.+/.+,?)*" } | |||
entry-or-media-type = xsd:string { pattern = "(.+/.+,?)*" } | entry-or-media-type = xsd:string { pattern = "(.+/.+,?)*" } | |||
# above is an approximation, rnc doesn't support interleaved text | # above is an approximation, rnc doesn't support interleaved text | |||
# Simple Extension | # Simple Extension | |||
simpleSansTitleExtensionElement = | ||||
element * - (app:*|atom:title) { | ||||
text | ||||
} | ||||
simpleExtensionElement = | simpleExtensionElement = | |||
element * - app:* { | element * - (app:*) { | |||
text | text | |||
} | } | |||
# Structured Extension | # Structured Extension | |||
structuredSansTitleExtensionElement = | ||||
element * - (app:*|atom:title) { | ||||
(attribute * { text }+, | ||||
(text|anyElement)*) | ||||
| (attribute * { text }*, | ||||
(text?, anyElement+, (text|anyElement)*)) | ||||
} | ||||
structuredExtensionElement = | structuredExtensionElement = | |||
element * - app:* { | element * - (app:*) { | |||
(attribute * { text }+, | (attribute * { text }+, | |||
(text|anyElement)*) | (text|anyElement)*) | |||
| (attribute * { text }*, | | (attribute * { text }*, | |||
(text?, anyElement+, (text|anyElement)*)) | (text?, anyElement+, (text|anyElement)*)) | |||
} | } | |||
# Other Extensibility | # Other Extensibility | |||
extensionSansTitleElement = | ||||
simpleSansTitleExtensionElement|structuredSansTitleExtensionElement | ||||
extensionElement = | extensionElement = | |||
simpleExtensionElement | structuredExtensionElement | simpleExtensionElement | structuredExtensionElement | |||
undefinedContent = (text|anyForeignElement)* | undefinedContent = (text|anyForeignElement)* | |||
# Extensions | # Extensions | |||
anyElement = | anyElement = | |||
element * { | element * { | |||
(attribute * { text } | (attribute * { text } | |||
| text | | text | |||
| anyElement)* | | anyElement)* | |||
} | } | |||
skipping to change at page 50, line 16 | skipping to change at page 52, line 34 | |||
# Extensions | # Extensions | |||
anyElement = | anyElement = | |||
element * { | element * { | |||
(attribute * { text } | (attribute * { text } | |||
| text | | text | |||
| anyElement)* | | anyElement)* | |||
} | } | |||
anyForeignElement = | anyForeignElement = | |||
element * - atom:* { | element * - app:* { | |||
(attribute * { text } | (attribute * { text } | |||
| text | | text | |||
| anyElement)* | | anyElement)* | |||
} | } | |||
atomPlainTextConstruct = | atomPlainTextConstruct = | |||
atomCommonAttributes, | atomCommonAttributes, | |||
attribute type { "text" | "html" }?, | attribute type { "text" | "html" }?, | |||
text | text | |||
skipping to change at page 51, line 4 | skipping to change at page 53, line 22 | |||
| text | | text | |||
| anyXHTML)* | | anyXHTML)* | |||
} | } | |||
# EOF | # EOF | |||
The Schema for Category Documents: | The Schema for Category Documents: | |||
# -*- 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 atom = "http://www.w3.org/2005/Atom" | namespace atom = "http://www.w3.org/2005/Atom" | |||
namespace xsd = "http://www.w3.org/2001/XMLSchema" | namespace xsd = "http://www.w3.org/2001/XMLSchema" | |||
namespace local = "" | namespace local = "" | |||
start = appCategories | start = appCategories | |||
# common:attrs | ||||
atomCommonAttributes = | atomCommonAttributes = | |||
attribute xml:base { atomUri }?, | attribute xml:base { atomURI }?, | |||
attribute xml:lang { atomLanguageTag }?, | attribute xml:lang { atomLanguageTag }?, | |||
undefinedAttribute* | undefinedAttribute* | |||
undefinedAttribute = | undefinedAttribute = | |||
attribute * - (xml:base | xml:lang | local:*) { text } | attribute * - (xml:base | xml:lang | local:*) { text } | |||
atomUri = text | atomURI = text | |||
atomLanguageTag = xsd:string { | atomLanguageTag = xsd:string { | |||
pattern = "[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*" | pattern = "[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*" | |||
} | } | |||
atomCategory = | atomCategory = | |||
element atom:category { | element atom:category { | |||
atomCommonAttributes, | atomCommonAttributes, | |||
attribute term { text }, | attribute term { text }, | |||
attribute scheme { atomUri }?, | attribute scheme { atomURI }?, | |||
attribute label { text }?, | attribute label { text }?, | |||
undefinedContent | undefinedContent | |||
} | } | |||
appInlineCategories = | appInlineCategories = | |||
element app:categories { | element app:categories { | |||
attribute fixed { "yes" | "no" }?, | attribute fixed { "yes" | "no" }?, | |||
attribute scheme { atomUri }?, | attribute scheme { atomURI }?, | |||
(atomCategory*) | (atomCategory*) | |||
} | } | |||
appOutOfLineCategories = | appOutOfLineCategories = | |||
element app:categories { | element app:categories { | |||
attribute href { atomURI }, | attribute href { atomURI }, | |||
(empty) | (empty) | |||
} | } | |||
appCategories = appInlineCategories | appOutOfLineCategories | appCategories = appInlineCategories | appOutOfLineCategories | |||
skipping to change at page 53, line 7 | skipping to change at page 55, line 7 | |||
element * - atom:* { | element * - atom:* { | |||
(attribute * { text } | (attribute * { text } | |||
| text | | text | |||
| anyElement)* | | anyElement)* | |||
} | } | |||
# EOF | # EOF | |||
Appendix C. Revision History | Appendix C. Revision History | |||
[[anchor44: This section to be removed upon publication.]] | ||||
draft-ietf-atompub-protocol-13: Added Lisa's verbiage. Folded in | ||||
James' Atom Format media type 'type' parameter spec. Updated | ||||
document references to be more consistent, added URLs to some, and | ||||
shortened up their anchors. Debugged rnc. | ||||
draft-ietf-atompub-protocol-11: Parts of PaceAppEdited. | draft-ietf-atompub-protocol-11: Parts of PaceAppEdited. | |||
PaceSecurityConsiderationsRevised. | PaceSecurityConsiderationsRevised. | |||
draft-ietf-atompub-protocol-10: PaceRemoveTitleHeader2, | draft-ietf-atompub-protocol-10: PaceRemoveTitleHeader2, | |||
PaceSlugHeader4, PaceOnlyMemberURI,PaceOneAppNamespaceOnly, | PaceSlugHeader4, PaceOnlyMemberURI,PaceOneAppNamespaceOnly, | |||
PaceAppCategories, PaceExtendIntrospection, | PaceAppCategories, PaceExtendIntrospection, | |||
UseElementsForAppCollectionTitles3, renamed Introspection to Service, | UseElementsForAppCollectionTitles3, renamed Introspection to Service, | |||
lots of good editorials suggestions, updated media example with slug, | lots of good editorials suggestions, updated media example with slug, | |||
moved xml conventions to convention sections, renamed XMl related | moved xml conventions to convention sections, renamed XMl related | |||
Conventions to Atom Publishing Protocol Documents, added auth header | Conventions to Atom Publishing Protocol Documents, added auth header | |||
skipping to change at page 56, line 5 | skipping to change at page 58, line 5 | |||
instead they are retrieved via GET. Cleaned up figure titles, as | instead they are retrieved via GET. Cleaned up figure titles, as | |||
they are rendered poorly in HTML. All content-types have been | they are rendered poorly in HTML. All content-types have been | |||
changed to application/atom+xml. | changed to application/atom+xml. | |||
Rev 01 - 5Jul2003 - Renamed from EchoAPI.html to follow the more | Rev 01 - 5Jul2003 - Renamed from EchoAPI.html to follow the more | |||
commonly used format: draft-gregorio-NN.html. Renamed all references | commonly used format: draft-gregorio-NN.html. Renamed all references | |||
to URL to URI. Broke out introspection into its own section. Added | to URL to URI. Broke out introspection into its own section. Added | |||
the Revision History section. Added more to the warning that the | the Revision History section. Added more to the warning that the | |||
example URIs are not normative. | example URIs are not normative. | |||
Intellectual Property Statement | Authors' Addresses | |||
Joe Gregorio (editor) | ||||
IBM | ||||
4205 South Miama Blvd. | ||||
Research Triangle Park, NC 27709 | ||||
US | ||||
Phone: +1 919 272 3764 | ||||
Email: joe@bitworking.org | ||||
URI: http://ibm.com/ | ||||
Bill de hOra (editor) | ||||
Propylon Ltd. | ||||
45 Blackbourne Square, Rathfarnham Gate | ||||
Dublin, Dublin D14 | ||||
IE | ||||
Phone: +353-1-4927444 | ||||
Email: bill.dehora@propylon.com | ||||
URI: http://www.propylon.com/ | ||||
Full Copyright Statement | ||||
Copyright (C) The IETF Trust (2007). | ||||
This document is subject to the rights, licenses and restrictions | ||||
contained in BCP 78, and except as set forth therein, the authors | ||||
retain all their rights. | ||||
This document and the information contained herein are provided on an | ||||
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS | ||||
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND | ||||
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS | ||||
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF | ||||
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED | ||||
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. | ||||
Intellectual Property | ||||
The IETF takes no position regarding the validity or scope of any | The IETF takes no position regarding the validity or scope of any | |||
Intellectual Property Rights or other rights that might be claimed to | Intellectual Property Rights or other rights that might be claimed to | |||
pertain to the implementation or use of the technology described in | pertain to the implementation or use of the technology described in | |||
this document or the extent to which any license under such rights | this document or the extent to which any license under such rights | |||
might or might not be available; nor does it represent that it has | might or might not be available; nor does it represent that it has | |||
made any independent effort to identify any such rights. Information | made any independent effort to identify any such rights. Information | |||
on the procedures with respect to rights in RFC documents can be | on the procedures with respect to rights in RFC documents can be | |||
found in BCP 78 and BCP 79. | found in BCP 78 and BCP 79. | |||
skipping to change at page 56, line 29 | skipping to change at page 59, line 45 | |||
such proprietary rights by implementers or users of this | such proprietary rights by implementers or users of this | |||
specification can be obtained from the IETF on-line IPR repository at | specification can be obtained from the IETF on-line IPR repository at | |||
http://www.ietf.org/ipr. | http://www.ietf.org/ipr. | |||
The IETF invites any interested party to bring to its attention any | The IETF invites any interested party to bring to its attention any | |||
copyrights, patents or patent applications, or other proprietary | copyrights, patents or patent applications, or other proprietary | |||
rights that may cover technology that may be required to implement | rights that may cover technology that may be required to implement | |||
this standard. Please address the information to the IETF at | this standard. Please address the information to the IETF at | |||
ietf-ipr@ietf.org. | ietf-ipr@ietf.org. | |||
The IETF has been notified of intellectual property rights claimed in | ||||
regard to some or all of the specification contained in this | ||||
document. For more information consult the online list of claimed | ||||
rights. | ||||
Disclaimer of Validity | ||||
This document and the information contained herein are provided on an | ||||
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS | ||||
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET | ||||
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, | ||||
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE | ||||
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED | ||||
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. | ||||
Copyright Statement | ||||
Copyright (C) The Internet Society (2006). This document is subject | ||||
to the rights, licenses and restrictions contained in BCP 78, and | ||||
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 provided by the IETF | |||
Internet Society. | Administrative Support Activity (IASA). | |||
End of changes. 124 change blocks. | ||||
286 lines changed or deleted | 411 lines changed or added | |||
This html diff was produced by rfcdiff 1.32. The latest version is available from http://www.levkowetz.com/ietf/tools/rfcdiff/ |