draft-ietf-atompub-protocol-15.txt   draft-ietf-atompub-protocol-16.txt 
Network Working Group J. Gregorio, Ed. Network Working Group J. Gregorio, Ed.
Internet-Draft IBM Internet-Draft IBM
Intended status: Standards Track B. de hOra, Ed. Intended status: Standards Track B. de hOra, Ed.
Expires: November 23, 2007 Propylon Ltd. Expires: December 29, 2007 June 27, 2007
May 22, 2007
The Atom Publishing Protocol The Atom Publishing Protocol
draft-ietf-atompub-protocol-15.txt draft-ietf-atompub-protocol-16.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 34
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on November 23, 2007. This Internet-Draft will expire on December 29, 2007.
Copyright Notice Copyright Notice
Copyright (C) The IETF Trust (2007). Copyright (C) The IETF Trust (2007).
Abstract Abstract
The Atom Publishing Protocol (APP) is an application-level protocol The Atom Publishing Protocol (APP) is an application-level protocol
for publishing and editing Web resources. The protocol is based on for publishing and editing Web resources. The protocol is based on
HTTP transfer of Atom-formatted representations. The Atom format is HTTP transfer of Atom-formatted representations. The Atom format is
skipping to change at page 3, line 38 skipping to change at page 3, line 38
5.2. Listing Collection Members . . . . . . . . . . . . . . . . 14 5.2. Listing Collection Members . . . . . . . . . . . . . . . . 14
5.3. Creating a Resource . . . . . . . . . . . . . . . . . . . 15 5.3. Creating a Resource . . . . . . . . . . . . . . . . . . . 15
5.4. Editing a Resource . . . . . . . . . . . . . . . . . . . . 15 5.4. Editing a Resource . . . . . . . . . . . . . . . . . . . . 15
5.4.1. Retrieving a Resource . . . . . . . . . . . . . . . . 15 5.4.1. Retrieving a Resource . . . . . . . . . . . . . . . . 15
5.4.2. Editing a Resource . . . . . . . . . . . . . . . . . . 16 5.4.2. Editing a Resource . . . . . . . . . . . . . . . . . . 16
5.4.3. Deleting a Resource . . . . . . . . . . . . . . . . . 16 5.4.3. Deleting a Resource . . . . . . . . . . . . . . . . . 16
5.5. Use of HTTP Response codes . . . . . . . . . . . . . . . . 16 5.5. Use of HTTP Response codes . . . . . . . . . . . . . . . . 16
6. Protocol Documents . . . . . . . . . . . . . . . . . . . . . . 18 6. Protocol Documents . . . . . . . . . . . . . . . . . . . . . . 18
6.1. Document Types . . . . . . . . . . . . . . . . . . . . . . 18 6.1. Document Types . . . . . . . . . . . . . . . . . . . . . . 18
6.2. Document Extensibility . . . . . . . . . . . . . . . . . . 18 6.2. Document Extensibility . . . . . . . . . . . . . . . . . . 18
7. Category Documents . . . . . . . . . . . . . . . . . . . . . . 20 7. Category Documents . . . . . . . . . . . . . . . . . . . . . . 19
7.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 20 7.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 19
7.2. Element Definitions . . . . . . . . . . . . . . . . . . . 20 7.2. Element Definitions . . . . . . . . . . . . . . . . . . . 19
7.2.1. The "app:categories" element . . . . . . . . . . . . . 20 7.2.1. The "app:categories" element . . . . . . . . . . . . . 19
8. Service Documents . . . . . . . . . . . . . . . . . . . . . . 22 8. Service Documents . . . . . . . . . . . . . . . . . . . . . . 21
8.1. Workspaces . . . . . . . . . . . . . . . . . . . . . . . . 22 8.1. Workspaces . . . . . . . . . . . . . . . . . . . . . . . . 21
8.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 23 8.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 22
8.3. Element Definitions . . . . . . . . . . . . . . . . . . . 24 8.3. Element Definitions . . . . . . . . . . . . . . . . . . . 23
8.3.1. The "app:service" Element . . . . . . . . . . . . . . 24 8.3.1. The "app:service" Element . . . . . . . . . . . . . . 23
8.3.2. The "app:workspace" Element . . . . . . . . . . . . . 24 8.3.2. The "app:workspace" Element . . . . . . . . . . . . . 23
8.3.3. The "app:collection" Element . . . . . . . . . . . . . 25 8.3.3. The "app:collection" Element . . . . . . . . . . . . . 24
8.3.4. The "app:accept" Element . . . . . . . . . . . . . . . 26 8.3.4. The "app:accept" Element . . . . . . . . . . . . . . . 25
8.3.5. Usage in Atom Feed Documents . . . . . . . . . . . . . 26 8.3.5. Usage in Atom Feed Documents . . . . . . . . . . . . . 25
8.3.6. The "app:categories" Element . . . . . . . . . . . . . 26 8.3.6. The "app:categories" Element . . . . . . . . . . . . . 25
9. Creating and Editing Resources . . . . . . . . . . . . . . . . 28 9. Creating and Editing Resources . . . . . . . . . . . . . . . . 27
9.1. Member URIs . . . . . . . . . . . . . . . . . . . . . . . 28 9.1. Member URIs . . . . . . . . . . . . . . . . . . . . . . . 27
9.2. Creating Resources with POST . . . . . . . . . . . . . . . 28 9.2. Creating Resources with POST . . . . . . . . . . . . . . . 27
9.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 29 9.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 28
9.3. Editing Resources with PUT . . . . . . . . . . . . . . . . 30 9.3. Editing Resources with PUT . . . . . . . . . . . . . . . . 29
9.4. Deleting Resources with DELETE . . . . . . . . . . . . . . 30 9.4. Deleting Resources with DELETE . . . . . . . . . . . . . . 29
9.5. Caching and entity tags . . . . . . . . . . . . . . . . . 30 9.5. Caching and entity tags . . . . . . . . . . . . . . . . . 29
9.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 30 9.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 29
9.6. Media Resources and Media Link Entries . . . . . . . . . . 32 9.6. Media Resources and Media Link Entries . . . . . . . . . . 31
9.6.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 33 9.6.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 32
9.7. The Slug: Header . . . . . . . . . . . . . . . . . . . . . 39 9.7. The Slug: Header . . . . . . . . . . . . . . . . . . . . . 38
9.7.1. Slug: Header syntax . . . . . . . . . . . . . . . . . 40 9.7.1. Slug: Header syntax . . . . . . . . . . . . . . . . . 39
9.7.2. Example . . . . . . . . . . . . . . . . . . . . . . . 40 9.7.2. Example . . . . . . . . . . . . . . . . . . . . . . . 39
10. Listing Collections . . . . . . . . . . . . . . . . . . . . . 41 10. Listing Collections . . . . . . . . . . . . . . . . . . . . . 40
10.1. Collection partial lists . . . . . . . . . . . . . . . . . 41 10.1. Collection partial lists . . . . . . . . . . . . . . . . . 40
10.2. The "app:edited" Element . . . . . . . . . . . . . . . . . 42 10.2. The "app:edited" Element . . . . . . . . . . . . . . . . . 41
11. Atom Format Link Relation Extensions . . . . . . . . . . . . . 43 11. Atom Format Link Relation Extensions . . . . . . . . . . . . . 42
11.1. The "edit" Link Relation . . . . . . . . . . . . . . . . . 43 11.1. The "edit" Link Relation . . . . . . . . . . . . . . . . . 42
11.2. The "edit-media" Link Relation . . . . . . . . . . . . . . 43 11.2. The "edit-media" Link Relation . . . . . . . . . . . . . . 42
12. The Atom Format Type Parameter . . . . . . . . . . . . . . . . 44 12. The Atom Format Type Parameter . . . . . . . . . . . . . . . . 43
12.1. The 'type' parameter . . . . . . . . . . . . . . . . . . . 44 12.1. The 'type' parameter . . . . . . . . . . . . . . . . . . . 43
12.1.1. Conformance . . . . . . . . . . . . . . . . . . . . . 44 12.1.1. Conformance . . . . . . . . . . . . . . . . . . . . . 43
13. Atom Publishing Controls . . . . . . . . . . . . . . . . . . . 45 13. Atom Publishing Controls . . . . . . . . . . . . . . . . . . . 44
13.1. The "app:control" Element . . . . . . . . . . . . . . . . 45 13.1. The "app:control" Element . . . . . . . . . . . . . . . . 44
13.1.1. The "app:draft" Element . . . . . . . . . . . . . . . 45 13.1.1. The "app:draft" Element . . . . . . . . . . . . . . . 44
14. Securing the Atom Publishing Protocol . . . . . . . . . . . . 46 14. Securing the Atom Publishing Protocol . . . . . . . . . . . . 45
15. Security Considerations . . . . . . . . . . . . . . . . . . . 47 15. Security Considerations . . . . . . . . . . . . . . . . . . . 46
15.1. Denial of Service . . . . . . . . . . . . . . . . . . . . 47 15.1. Denial of Service . . . . . . . . . . . . . . . . . . . . 46
15.2. Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 47 15.2. Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 46
15.3. Spoofing Attacks . . . . . . . . . . . . . . . . . . . . . 47 15.3. Spoofing Attacks . . . . . . . . . . . . . . . . . . . . . 46
15.4. Linked Resources . . . . . . . . . . . . . . . . . . . . . 47 15.4. Linked Resources . . . . . . . . . . . . . . . . . . . . . 46
15.5. Digital Signatures and Encryption . . . . . . . . . . . . 47 15.5. Digital Signatures and Encryption . . . . . . . . . . . . 46
15.6. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 47 15.6. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 47
15.7. Code Injection and Cross Site Scripting . . . . . . . . . 48 15.7. Code Injection and Cross Site Scripting . . . . . . . . . 47
16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48
16.1. Content-type registration for 'application/atomcat+xml' . 49 16.1. Content-type registration for 'application/atomcat+xml' . 48
16.2. Content-type registration for 'application/atomsvc+xml' . 50 16.2. Content-type registration for 'application/atomsvc+xml' . 49
16.3. Header field registration for 'SLUG' . . . . . . . . . . . 51 16.3. Header field registration for 'SLUG' . . . . . . . . . . . 50
16.4. The Link Relation registration "edit" . . . . . . . . . . 52 16.4. The Link Relation registration "edit" . . . . . . . . . . 51
16.5. The Link Relation registration "edit-media" . . . . . . . 52 16.5. The Link Relation registration "edit-media" . . . . . . . 51
16.6. The Atom Format Media Type Parameter . . . . . . . . . . . 52 16.6. The Atom Format Media Type Parameter . . . . . . . . . . . 51
17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 53 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 52
17.1. Normative References . . . . . . . . . . . . . . . . . . . 53 17.1. Normative References . . . . . . . . . . . . . . . . . . . 52
17.2. Informative References . . . . . . . . . . . . . . . . . . 54 17.2. Informative References . . . . . . . . . . . . . . . . . . 53
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 56 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 55
Appendix B. RELAX NG Compact Schema . . . . . . . . . . . . . . . 57 Appendix B. RELAX NG Compact Schema . . . . . . . . . . . . . . . 56
Appendix C. Revision History . . . . . . . . . . . . . . . . . . 63 Appendix C. Revision History . . . . . . . . . . . . . . . . . . 62
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 66
Intellectual Property and Copyright Statements . . . . . . . . . . 68 Intellectual Property and Copyright Statements . . . . . . . . . . 67
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
[REC-xml]. The protocol supports the creation of Web Resources and [REC-xml]. The protocol supports the creation of Web Resources and
provides facilities for: provides facilities for:
o Collections: Sets of Resources, which can be retrieved in whole or o Collections: Sets of Resources, which can be retrieved in whole or
in part. in part.
skipping to change at page 7, line 42 skipping to change at page 7, line 42
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 [REC-xmlbase]. When xml:base is used, it serves the attribute [REC-xmlbase]. When xml:base is used, it serves the
function described in Section 5.1.1 of URI Generic Syntax [RFC3986], function described in Section 5.1.1 of URI Generic Syntax [RFC3986],
by establishing the base URI (or IRI) for resolving relative by establishing the base URI (or IRI) for resolving relative
references found within the scope of the xml:base attribute. references found within the scope of the xml:base attribute.
Any element defined by this specification MAY have an xml:lang Any element defined by this specification MAY have an xml:lang
attribute, whose content indicates the natural language for the attribute, whose content indicates the natural language for the
element and its descendents. Requirements regarding the content and element and its descendants. Requirements regarding the content and
interpretation of xml:lang are specified in Section 2.12 of XML 1.0 interpretation of xml:lang are specified in Section 2.12 of XML 1.0
[REC-xml]. [REC-xml].
3. Terminology 3. Terminology
For convenience, this protocol can be referred to as the "Atom For convenience, this protocol can be referred to as the "Atom
Protocol" or "APP". The following terminology is used by this Protocol" or "APP". The following terminology is used by this
specification: specification:
o URI - A Uniform Resource Identifier as defined in [RFC3986]. In o URI - A Uniform Resource Identifier as defined in [RFC3986]. In
skipping to change at page 18, line 21 skipping to change at page 18, line 21
A Category Document (Section 7) contains lists of categories A Category Document (Section 7) contains lists of categories
specified using the "atom:category" element from the Atom Syndication specified using the "atom:category" element from the Atom Syndication
Format (see Section 4.2.2 of [RFC4287]). Format (see Section 4.2.2 of [RFC4287]).
A Service Document (Section 8) groups available Collections into A Service Document (Section 8) groups available Collections into
Workspaces. Workspaces.
The namespace name [REC-xml-names] for either kind of document is: The namespace name [REC-xml-names] for either kind of document is:
http://purl.org/atom/app# http://www.w3.org/2007/app
[[anchor9: The namespace name 'http://purl.org/atom/app#' needs to be
updated throughout the document with the final URI upon publication]]
Atom Publishing Protocol XML Documents MUST be "namespace-well- Atom Publishing Protocol XML Documents MUST be "namespace-well-
formed" as specified in Section 7 of [REC-xml-names]. formed" as specified in Section 7 of [REC-xml-names].
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]. These namespace name of the Atom Syndication Format [RFC4287]. These
namespace prefixes are not semantically significant. namespace prefixes are not semantically significant.
This specification does not define any DTDs for Atom Protocol This specification does not define any DTDs for Atom Protocol
skipping to change at page 18, line 48 skipping to change at page 18, line 45
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 Section 6 of the Atom considered "foreign markup" as defined in Section 6 of the Atom
Syndication Format [RFC4287]. Foreign markup can be used anywhere Syndication Format [RFC4287]. Foreign markup can be used anywhere
within a Category or Service Document unless it is explicitly within a Category or Service Document unless it is explicitly
forbidden. Processors that encounter foreign markup MUST NOT stop forbidden. Processors that encounter foreign markup MUST NOT stop
processing and MUST NOT signal an error. Clients SHOULD preserve processing and MUST NOT signal an error. Clients SHOULD preserve
foreign markup when transmitting such documents. foreign markup when transmitting such documents.
The namespace name "http://purl.org/atom/app#" is reserved for The namespace name "http://www.w3.org/2007/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://www.w3.org/2007/app" namespace MUST be treated as foreign
markup. markup.
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 indicate Categories can also appear in Service Documents, where they indicate
the categories allowed in a Collection (see Section 8.3.6). the categories allowed in a Collection (see Section 8.3.6).
Category Documents are identified with the "application/atomcat+xml" Category Documents are identified with the "application/atomcat+xml"
media type (see Section 16.1). media type (see Section 16.1).
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://www.w3.org/2007/app"
xmlns:atom="http://www.w3.org/2005/Atom" xmlns:atom="http://www.w3.org/2005/Atom"
fixed="yes" scheme="http://example.com/cats/big3"> fixed="yes" scheme="http://example.com/cats/big3">
<atom:category term="animal" /> <atom:category term="animal" />
<atom:category term="vegetable" /> <atom:category term="vegetable" />
<atom:category term="mineral" /> <atom:category term="mineral" />
</app:categories> </app:categories>
This Category Document contains atom:category elements, with the This Category Document contains atom:category elements, with the
terms 'animal', 'vegetable', and 'mineral'. None of the categories terms 'animal', 'vegetable', and 'mineral'. None of the categories
use the "label" attribute defined in [RFC4287]. They all inherit the use the "label" attribute defined in [RFC4287]. They all inherit the
skipping to change at page 23, line 8 skipping to change at page 22, line 8
specification. This specification assigns no meaning to Workspaces; specification. This specification assigns no meaning to Workspaces;
that is, a Workspace does not imply any specific processing that is, a Workspace does not imply any specific processing
assumptions. assumptions.
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.2. Example 8.2. 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://www.w3.org/2007/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/blog/main" > href="http://example.org/blog/main" >
<atom:title>My Blog Entries</atom:title> <atom:title>My Blog Entries</atom:title>
<categories <categories
href="http://example.com/cats/forMain.cats" /> href="http://example.com/cats/forMain.cats" />
</collection> </collection>
<collection <collection
skipping to change at page 24, line 29 skipping to change at page 23, line 29
8.3. Element Definitions 8.3. Element Definitions
8.3.1. The "app:service" Element 8.3.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://www.w3.org/2007/app"
start = appService start = appService
appService = appService =
element app:service { element app:service {
appCommonAttributes, appCommonAttributes,
( appWorkspace+ ( appWorkspace+
& extensionElement* ) & extensionElement* )
} }
8.3.2. The "app:workspace" Element 8.3.2. The "app:workspace" Element
skipping to change at page 26, line 51 skipping to change at page 25, line 51
collection element is considered foreign markup as defined in Section collection element is considered foreign markup as defined in Section
6 of [RFC4287]. 6 of [RFC4287].
8.3.6. The "app:categories" Element 8.3.6. The "app:categories" Element
The "app:categories" element provides a list of the categories that The "app:categories" element provides a list of the categories that
can be applied to the members of a Collection. See Section 7.2.1 for can be applied to the members of a Collection. See Section 7.2.1 for
the detailed definition of app:categories. the detailed definition of app:categories.
The server MAY reject attempts to create or store members whose The server MAY reject attempts to create or store members whose
categories are not present in it's categories list. Collections that categories are not present in its categories list. Collections that
indicate the category set is open SHOULD NOT reject otherwise indicate the category set is open SHOULD NOT reject otherwise
acceptable members whose categories are not in its categories list. acceptable members whose categories are not in its categories list.
The absence of an "app:categories" element means that the category The absence of an "app:categories" element means that the category
handling of the Collection is unspecified. A "fixed" category list handling of the Collection is unspecified. A "fixed" category list
that contains zero categories indicates the Collection does not that contains zero categories indicates the Collection does not
accept category data. accept category data.
9. Creating and Editing Resources 9. Creating and Editing Resources
9.1. Member URIs 9.1. Member URIs
skipping to change at page 33, line 14 skipping to change at page 32, line 14
an atom:content element with a "src" attribute. The value of the an atom:content element with a "src" attribute. The value of the
"src" attribute is an IRI for the newly created Media Resource. It "src" attribute is an IRI for the newly created Media Resource. It
is OPTIONAL that the IRI of the "src" attribute on the atom:content is OPTIONAL that the IRI of the "src" attribute on the atom:content
element be the same as the Media Resource IRI. For example, the element be the same as the Media Resource IRI. For example, the
"src" attribute value might instead be a link into a static cache or "src" attribute value might instead be a link into a static cache or
content distribution network and not the Media Resource IRI. content distribution network and not the Media Resource IRI.
Implementers are asked to note that [RFC4287] specifies that Atom Implementers are asked to note that [RFC4287] specifies that Atom
Entries MUST contain an atom:summary element. Thus, upon successful Entries MUST contain an atom:summary element. Thus, upon successful
creation of a Media Link Entry, a server MAY choose to populate the creation of a Media Link Entry, a server MAY choose to populate the
atom:summary element (as well as any other required elements such as atom:summary element (as well as any other mandatory elements such as
atom:id, atom:author and atom:title) with content derived from the atom:id, atom:author and atom:title) with content derived from the
POSTed entity or from any other source. A server might not allow a POSTed entity or from any other source. A server might not allow a
client to modify the server selected values for these elements. client to modify the server selected values for these elements.
For Resource creation this specification only defines cases where the For Resource creation this specification only defines cases where the
POST body has an Atom Entry entity declared as an Atom media type POST body has an Atom Entry entity declared as an Atom media type
("application/atom+xml"), or a non-Atom entity declared as a non-Atom ("application/atom+xml"), or a non-Atom entity declared as a non-Atom
media type. When a client is POSTing an Atom Entry to a collection, media type. When a client is POSTing an Atom Entry to a collection,
it may use a media-type of either "application/atom+xml" or it may use a media-type of either "application/atom+xml" or
"application/atom +xml;type=entry". This specification does not "application/atom +xml;type=entry". This specification does not
skipping to change at page 39, line 36 skipping to change at page 38, line 36
</xhtml:p> </xhtml:p>
</xhtml:div> </xhtml:div>
</content> </content>
<link rel="edit" <link rel="edit"
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="text/html" <link rel="alternate" type="text/html"
href="http://example.org/blog/a-day-at-the-beach.html"/> href="http://example.org/blog/a-day-at-the-beach.html"/>
</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 HTML page that was created. "alternate" that points to the associated HTML page that was created
This is not required by this specification, but is included to show - this is not required by this specification, but is included to show
the kinds of changes a server can make to an Entry. the kinds of changes a server can make to an Entry.
9.7. The Slug: Header 9.7. The Slug: Header
Slug is an HTTP entity-header whose presence in a POST to a Slug is an HTTP entity-header whose presence in a POST to a
Collection constitutes a request by the client to use the header's Collection constitutes a request by the client to use the header's
value as part of any URIs that would normally used to retrieve the value as part of any URIs that would normally used to retrieve the
to-be-created Entry or Media resources. to-be-created Entry or Media resources.
Servers MAY use the value of the Slug header when creating the Member Servers MAY use the value of the Slug header when creating the Member
skipping to change at page 40, line 13 skipping to change at page 39, line 13
Link Entry (see Section 9.6.). Link Entry (see Section 9.6.).
Servers MAY choose to ignore the Slug entity-header. Servers MAY Servers MAY choose to ignore the Slug entity-header. Servers MAY
alter the header value before using it. For instance, a server might alter the header value before using it. For instance, a server might
filter out some characters or replace accented letters with non- filter out some characters or replace accented letters with non-
accented ones, replace spaces with underscores, change case, and so accented ones, replace spaces with underscores, change case, and so
on. on.
9.7.1. Slug: Header syntax 9.7.1. Slug: Header syntax
The syntax of this header MUST conform to the augmented BNF grammar The syntax of the Slug header is defined using the augmented BNF
in section 2.1 of the HTTP/1.1 specification [RFC2616]. The TEXT syntax defined in Section 2.1 of [RFC2616]:
rule is described in section 2.2 of the same document.
Slug = "Slug" ":" *TEXT LWS = <defined in Section 2.2 of [RFC2616]>
slugtext = %x20-7E | LWS
Slug = "Slug" ":" *slugtext
The field-value of the Slug header is a percent-encoded utf-8 Unicode The field-value is the percent-encoded value of the UTF-8 encoding of
string that does not contain CR or LF, where CR and LF are defined in the character sequence to be included (see Section 2.1 of [RFC3986]
[RFC2616]. All non-ASCII characters in the utf-8 representation MUST for the definition of percent encoding, and [RFC3629] for the
be percent-encoded according to the rules in Section 2.1 of definition of the UTF-8 encoding).
[RFC3986].
Implementation note: to produce the field value from a character
sequence, first encode it using the UTF-8 encoding, then encode all
octets outside the ranges %20-24 and %26-7E using percent encoding
(%25 is the ASCII encoding of "%", thus it needs to be escaped). To
consume the field value first reverse the percent encoding, then run
the resulting octet sequence through a UTF-8 decoding process.
9.7.2. Example 9.7.2. Example
Here is an example of the Slug: header that uses percent-encoding to Here is an example of the Slug: header that uses percent-encoding to
represent the Unicode character U+00E8 (LATIN SMALL LETTER E WITH represent the Unicode character U+00E8 (LATIN SMALL LETTER E WITH
GRAVE): GRAVE):
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
skipping to change at page 44, line 12 skipping to change at page 43, line 12
"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. The Atom Format Type Parameter 12. The Atom Format Type Parameter
The Atom Syndication Format [RFC4287] defines the "application/ The Atom Syndication Format [RFC4287] defines the "application/
atom+xml" media type to identify both Atom Feed and Atom Entry atom+xml" media type to identify both Atom Feed and Atom Entry
Documents. Implementation experience has demonstrated that Atom Feed Documents. Implementation experience has demonstrated that Atom Feed
and Entry Documents can have different processing models and that and Entry Documents can have different processing models and that
there are situations where they need to be differentiated. This there are situations where they need to be differentiated. This
document defines an optional "type" parameter used to differentiate specification defines an optional "type" parameter used to
the two types of Atom documents. differentiate the two types of Atom documents.
12.1. The 'type' parameter 12.1. The 'type' parameter
This document defines a new "type" parameter for use with the This specification defines a new "type" parameter for use with the
"application/atom+xml" media type. The "type" parameter has a value "application/atom+xml" media type. The "type" parameter has a value
of "entry" or "feed". of "entry" or "feed".
Neither the parameter name nor its value are case sensitive. Neither the parameter name nor its value are case sensitive.
The value "entry" indicates that the media type identifies an Atom The value "entry" indicates that the media type identifies an Atom
Entry Document. The root element of the document MUST be atom:entry. Entry Document. The root element of the document MUST be atom:entry.
The value "feed" indicates that the media type identifies an Atom The value "feed" indicates that the media type identifies an Atom
Feed Document. The root element of the document MUST be atom:feed. Feed Document. The root element of the document MUST be atom:feed.
If not specified, the type is assumed to be unspecified, requiring If not specified, the type is assumed to be unspecified, requiring
Atom processors to examine the root element to determine the type of Atom processors to examine the root element to determine the type of
Atom document. Atom document.
12.1.1. Conformance 12.1.1. Conformance
New specifications MAY require that the "type" parameter be used to New specifications MAY require that the "type" parameter be used to
identify the Atom Document type. Producers of Atom Entry Documents identify the Atom Document type. Producers of Atom Entry Documents
SHOULD use the "type" parameter regardless of whether or not it is SHOULD use the "type" parameter regardless of whether or not it is
required. Producers of Atom Feed Documents MAY use the parameter. mandatory. Producers of Atom Feed Documents MAY use the parameter.
Atom processors that do not recognize the "type" parameter MUST Atom processors that do not recognize the "type" parameter MUST
ignore its value and examine the root element to determine the ignore its value and examine the root element to determine the
document type. document type.
Atom processors that do recognize the "type" parameter SHOULD detect Atom processors that do recognize the "type" parameter SHOULD detect
and report inconsistencies between the parameter's value and the and report inconsistencies between the parameter's value and the
actual type of the document's root element. actual type of the document's root element.
13. Atom Publishing Controls 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://www.w3.org/2007/app" namespace.
13.1. The "app:control" Element 13.1. The "app:control" Element
namespace app = "http://purl.org/atom/app#" namespace app = "http://www.w3.org/2007/app"
pubControl = pubControl =
element app:control { element app:control {
atomCommonAttributes, atomCommonAttributes,
pubDraft? pubDraft?
& extensionElement & extensionElement
} }
pubDraft = pubDraft =
element app:draft { "yes" | "no" } element app:draft { "yes" | "no" }
The "app:control" element MAY appear as a child of an atom:entry that The "app:control" element MAY appear as a child of an atom:entry that
is being created or updated via the Atom Publishing Protocol. The is being created or updated via the Atom Publishing Protocol. The
app:control element MUST appear only once in an Entry. The app: app:control element MUST appear only once in an Entry. The app:
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 "app:draft" element as defined
as defined below, and can contain extension elements as defined in below, and can contain extension elements as defined in Section 6 of
Section 6 of [RFC4287]. [RFC4287].
13.1.1. The "app:draft" Element 13.1.1. The "app:draft" Element
The inclusion of the "app:draft" element represents a request by the The inclusion of the "app:draft" element represents a request by the
client to control the visibility of a Member Resource. Server client to control the visibility of a Member Resource. The app:draft
support is optional and thus the app:draft element MAY be ignored by element MAY be ignored by the server.
the server.
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.
The content of an app:draft element MUST be one of "yes" or "no". If The content of an app:draft element MUST be one of "yes" or "no". If
the element contains "no" this indicates a client request that the the element contains "no" this indicates a client request that the
Member Resource be made publicly visible. If the app:draft element Member Resource be made publicly visible. If the app:draft element
is not present then servers that support the extension MUST behave as is not present then servers that support the extension MUST behave as
though an app:draft element containing "no" was sent. though an app:draft element containing "no" was sent.
14. 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.
The type of authentication deployed is a local decision made by the The type of authentication deployed is a local decision made by the
server operator. Clients are likely to face authentication schemes server operator. Clients are likely to face authentication schemes
that vary across server deployments. At a minimum, client and server that vary across server deployments. At a minimum, client and server
implementations MUST be capable of being configured to use HTTP Basic implementations MUST be capable of being configured to use HTTP Basic
Authentication [RFC2617] in conjunction with a TLS [RFC2246] Authentication [RFC2617] in conjunction with a connection made with
connection as defined in [RFC2818] (but note that [RFC2246] has been TLS 1.0 [RFC2246] or a subsequent standards-track version of TLS,
superseded by [RFC4346]). See [RFC4346] for more information on TLS. supporting the conventions for using HTTP over TLS described in
[RFC2818]. At a minimum, client and server implementations MUST be
capable of being configured to use HTTP Basic Authentication
[RFC2617] in conjunction with a TLS 1.0 [RFC2246] or a subsequent
standards-track version of TLS, supporting the conventions for using
HTTP over TLS described in [RFC2818].
The choice of authentication mechanism will impact interoperability. The choice of authentication mechanism will impact interoperability.
The minimum level of security referenced above (Basic Authentication The minimum level of security referenced above (Basic Authentication
with TLS) is considered good practice for Internet applications at with TLS) is considered good practice for Internet applications at
the time of publication of this specification and sufficient for the time of publication of this specification and sufficient for
establishing a baseline for interoperability. Implementers are establishing a baseline for interoperability. Implementers are
encouraged to investigate and use alternative mechanisms regarded as encouraged to investigate and use alternative mechanisms regarded as
equivalently good or better at the time of deployment. It is equivalently good or better at the time of deployment. It is
RECOMMENDED that clients be implemented in such a way that new RECOMMENDED that clients be implemented in such a way that new
authentication schemes can be deployed. authentication schemes can 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].
15. Security Considerations 15. Security Considerations
The Atom Publishing Protocol is based on HTTP and thus subject to the The Atom Publishing Protocol is based on HTTP and thus subject to the
security considerations found in Section 15 of [RFC2616]. security considerations found in Section 15 of [RFC2616].