[Osr-101] rev 20088 - public/osr-101/trunk
andi at wyona.com
andi at wyona.com
Fri Nov 17 19:45:35 CET 2006
Author: andi
Date: 2006-11-17 19:45:34 +0100 (Fri, 17 Nov 2006)
New Revision: 20088
Added:
public/osr-101/trunk/draft-neutron-protocol-v0.template.xml
Log:
Added original import as template for referencing purposes.
Added: public/osr-101/trunk/draft-neutron-protocol-v0.template.xml
===================================================================
--- public/osr-101/trunk/draft-neutron-protocol-v0.template.xml 2006-11-17 18:44:37 UTC (rev 20087)
+++ public/osr-101/trunk/draft-neutron-protocol-v0.template.xml 2006-11-17 18:45:34 UTC (rev 20088)
@@ -0,0 +1,2065 @@
+<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
+<!ENTITY rfc2119 SYSTEM 'bibxml/reference.RFC.2119.xml'>
+
+ <!ENTITY rfc4287 SYSTEM 'bibxml/reference.RFC.4287.xml'>
+ <!ENTITY rfc2396 SYSTEM 'bibxml/reference.RFC.2396.xml'>
+ <!ENTITY rfc2616 SYSTEM 'bibxml/reference.RFC.2616.xml'>
+ <!ENTITY rfc2617 SYSTEM 'bibxml/reference.RFC.2617.xml'>
+
+ <!ENTITY rfc2818 SYSTEM 'bibxml/reference.RFC.2818.xml'>
+ <!ENTITY rfc4346 SYSTEM 'bibxml/reference.RFC.4346.xml'>
+
+ <!ENTITY rfc3023 SYSTEM 'bibxml/reference.RFC.3023.xml'>
+ <!ENTITY rfc3339 SYSTEM 'bibxml/reference.RFC.3339.xml'>
+ <!ENTITY rfc3986 SYSTEM 'bibxml/reference.RFC.3986.xml'>
+ <!ENTITY rfc3987 SYSTEM 'bibxml/reference.RFC.3987.xml'>
+ <!ENTITY rfc2047 SYSTEM 'bibxml/reference.RFC.2047.xml'>
+
+ <!ENTITY WEBARCH SYSTEM 'bibxml/reference.W3C.REC-webarch-20041215.xml'>
+
+ <!ENTITY XML SYSTEM 'bibxml/reference.W3C.REC-xml-20060816.xml'>
+ <!ENTITY XMLNS SYSTEM 'bibxml/reference.W3C.REC-xml-names-20060816.xml'>
+ <!ENTITY XMLBASE SYSTEM 'bibxml/reference.W3C.REC-xml-base-20010627.xml'>
+ <!ENTITY INFOSET SYSTEM 'bibxml/reference.W3C.REC-xml-infoset-20040204.xml'>
+
+ <!ENTITY XMLDSIG SYSTEM 'bibxml/reference.W3C.REC-xmldsig-core-20020212.xml'>
+ <!ENTITY XMLENC SYSTEM 'bibxml/reference.W3C.REC-xmlenc-core-20021210.xml'>
+
+ <!ENTITY ISO88591 SYSTEM 'bibxml/reference.ISO88591.xml'>
+]>
+
+
+<!--
+$LastChangedDate: 2006-10-03 21:48:23 -0400 (Tue, 03 Oct 2006) $
+$LastChangedRevision: 253 $
+-->
+
+<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
+
+<?rfc toc="yes" ?>
+<?rfc symrefs="yes" ?>
+<?rfc sortrefs="yes"?>
+<?rfc iprnotified="yes" ?>
+<?rfc strict="yes" ?>
+<?rfc compact="no" ?>
+<?rfc comments="yes" ?>
+<?rfc inline="yes" ?>
+<?rfc tocdepth="3" ?>
+<!--
+1. Update the docName
+2. Update the date
+3. Update the Revision History.
+-->
+
+<!--
+Bill todo:
+
+* The reference to Section 3.1 is misleading as RFC 3987 requires that such
+ conversion takes place only if it is necessary and as late as possible; it may
+ or may not be necessary under a revision of RFC 2616 and the bit about as late
+ as possible is lost here It is unclear what this is supposed to imply; there
+ are three variants in 3.1, the spec needs to say which to choose.
+
+* It's not entirely clear how section 5 and section 9 relate to each other; add
+an introductory sentence to 5.
+
+
+
+Joe issues:
+
+1. No mandate to supply "next" in collecion feeds
+ (An anti-social implementation could supply only "last" and "previous" and
+ be conformant to the spec.)
+2.
+
+-->
+ <rfc category="std" ipr="full3978" docName="draft-ietf-atompub-protocol-11.txt">
+ <front>
+ <title>The Neutron Protocol</title>
+ <author initials='M.H.' surname="Wechner" fullname='Michael Wechner' role="editor">
+ <organization>Wyona</organization>
+ <address>
+ <postal>
+ <street>4205 South Miama Blvd.</street>
+ <city>Zurich</city> <region>NC</region> <code>27709</code>
+ <country>Switzerland</country>
+ </postal>
+ <phone>+1 919 272 3764</phone>
+ <email>michael.wechner at wyona.com</email>
+ <uri>http://www.wyona.com</uri>
+ </address>
+ </author>
+ <author initials='B.' surname="de hOra" fullname='Bill de hOra' role="editor">
+ <organization>Propylon Ltd.</organization>
+ <address>
+ <postal>
+ <street>45 Blackbourne Square, Rathfarnham Gate</street>
+ <city>Dublin</city> <region>Dublin</region> <code>D14</code>
+ <country>IE</country>
+ </postal>
+ <phone>+353-1-4927444</phone>
+ <email>bill.dehora at propylon.com</email>
+ <uri>http://www.propylon.com/</uri>
+ </address>
+ </author>
+
+ <date day="03" month="October" year="2006"/>
+ <abstract>
+
+ <t>The Atom Publishing Protocol (APP) is an application-level
+ protocol for publishing and editing Web
+ resources. The protocol is based on HTTP transport of
+ Atom-formatted representations. The Atom format is documented in
+ the Atom Syndication Format [RFC4287].
+ </t>
+
+ </abstract>
+
+ <note title="Editorial Note">
+ <t>To provide feedback on this Internet-Draft, join the <eref
+ target="http://www.imc.org/atom-protocol/index.html">atom-protocol mailing
+ list (http://www.imc.org/atom-protocol/index.html)</eref>.
+ </t>
+ </note>
+ </front>
+
+ <middle>
+
+ <section title="Introduction">
+
+ <t>The Atom Publishing Protocol is an application-level
+ protocol for publishing and editing Web resources using HTTP
+ <xref target="RFC2616"/> and XML 1.0 <xref
+ target="W3C.REC-xml-20060816"/>. The protocol supports the creation of arbitrary web resources and
+ provides facilities for:</t>
+
+<t>
+ <list style="symbols">
+ <t>Collections: Sets of resources, which can be retrieved in whole or in part.</t>
+ <t>Service: Discovering and describing Collections.</t>
+ <t>Editing: Creating, updating and deleting resources.</t>
+ </list>
+</t>
+
+ </section>
+
+ <section title="Notational Conventions">
+ <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
+ "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
+ and "OPTIONAL" in this document are to be interpreted as
+ described in <xref target="RFC2119"/>.
+ </t>
+
+
+ <section title="XML-related Conventions" anchor="xml-conv">
+
+
+ <section title="Referring to Information Items" anchor="i-items">
+
+ <t>Atom Protocol Document formats are specified in terms of the XML
+ Information Set <xref target="W3C.REC-xml-infoset-20040204"/>, serialized
+ as XML 1.0 <xref target="W3C.REC-xml-20060816"/>.</t>
+ <t>The Infoset terms "Element Information Item" and "Attribute Information Item"
+ are shortened to "element" and "attribute" respectively.
+ Therefore, when this specification uses the term "element",
+ it is referring to an Element Information Item, and when it uses the term "attribute", it is
+ referring to an Attribute Information Item. </t></section>
+
+ <section title="RELAX NG Schema">
+ <t>
+ Some sections of this specification are illustrated with
+ fragments of a non-normative RELAX NG Compact schema <xref
+ target="RNC"/>. However, the text of this specification
+ provides the definition of conformance. Complete schemas
+ appear in <xref target="schema"/>. </t></section>
+
+
+ <section title="Use of xml:base and xml:lang" anchor="baselang">
+
+ <t>XML elements defined by this specification MAY have an xml:base
+ attribute <xref target="W3C.REC-xmlbase-20010627"/>. When xml:base is
+ used, it serves the function described in Section 5.1.1 of URI Generic Syntax <xref
+ target="RFC3986"/>, by establishing the base URI (or IRI) for resolving
+ relative references found within the scope of the
+ xml:base attribute. </t>
+
+ <t>Any element defined by this specification MAY have an xml:lang
+ attribute, whose content indicates the natural language for the element
+ and its descendents. The language context is only significant for
+ elements and attributes declared to be "Language-Sensitive" by this
+ specification. Requirements regarding the content and interpretation of
+ xml:lang are specified in Section 2.12 of XML 1.0 <xref
+ target="W3C.REC-xml-20060816"/>.
+
+ </t>
+
+ </section>
+
+
+ </section>
+
+
+
+
+ </section>
+
+ <section title="Terminology" anchor="terminology">
+
+ <t>For convenience, this protocol can be referred to as the "Atom Protocol"
+ or "APP".
+ </t>
+
+ <t>URI/IRI - A Uniform Resource Identifier and Internationalized
+ Resource Identifier. These terms and the distinction between
+ them are defined in <xref target="RFC3986"/> and
+ <xref target="RFC3987"/>. Before an IRI found in a document is
+ used by HTTP, the IRI is first converted to a URI (see
+ <xref target="model" />
+ </t>
+
+ <t>The phrase "the URI of a document" in this specification is
+ shorthand for "a URI which, when dereferenced, is expected to
+ produce that document as a representation".
+ </t>
+
+ <t>Resource - A network-accessible data object or
+ service
+ identified by an IRI, as defined in <xref target="RFC2616"/>. See
+ <xref target="W3C.REC-webarch-20041215"/> for further discussion
+ on resources.
+ </t>
+
+
+ <t>Representation - An entity included with a request or
+ response as defined in <xref target="RFC2616"/>.
+ </t>
+
+ <t>Collection - A resource that contains a set of Member Entries.
+ See <xref target="collection_resource"/>.
+ </t>
+
+ <t>Member - A resource whose IRI is listed in a Collection
+ by a link element with a relation of "edit" or "edit-media". See
+ <xref target="memuri"/>.
+ </t>
+
+ <t>Workspace - A group of collections. See <xref target="appdocs"/>.
+ </t>
+
+ <t>Service Document - A document that describes the
+ location and capabilities of one or more Collections. See <xref
+ target="appdocs"/>.</t>
+
+ <t>Category Document - A document that describes the categories
+ allowed in a Collection. See <xref target="catdocs"/>.
+ </t>
+
+
+ </section>
+
+
+ <section title="Protocol Model" anchor="model">
+
+ <t>
+ The Atom Publishing Protocol uses HTTP methods to author
+ Member Resources as follows:
+ </t>
+ <t>
+ <list style="symbols">
+ <t>GET is used to retrieve a representation of a
+ known resource.</t>
+ <t>POST is used to create a new, dynamically-named,
+ resource.</t>
+ <t>PUT is used to update a known resource.</t>
+ <t>DELETE is used to remove a known resource.</t>
+ </list>
+
+ </t>
+ <t>
+ Along with operations on Member Resources the Atom Protocol
+ defines Collection resources for managing and organizing
+ Member Resources. Collections are represented by Atom Feed
+ documents and contain the IRIs of, and metadata about, their
+ Member Resources.
+ </t>
+
+ <t>Atom Protocol documents allow the use of IRIs
+ <xref target="RFC3987"/>, as well as URIs
+ <xref target="RFC3986"/>. Before an IRI found in a document is used
+ by HTTP, the IRI is first converted to a URI according the procedure
+ defined in Section 3.1 of <xref target="RFC3987"/>. The resource
+ identified by the URI after conversion is the same as the one
+ identified by the IRI.
+ </t>
+ <t>
+ There are two kinds of Member Resources - Member Entry
+ Resources and Media Resources. Member Entry Resources are
+ represented as Atom Entries <xref target="RFC4287"/>. Media Resources can have
+ representations in any media type. A Media Link Entry is a
+ Member Entry that contains metadata about a Media Resource.
+ This diagram shows the classification of the resources:
+ </t>
+
+<figure>
+<artwork>
+ Member Resource
+ -> Member Entry Resource
+ -> Media Link Entry Resource
+ -> Media Resource
+</artwork>
+</figure>
+
+ <t>Collections, represented by Atom feeds, contain
+ entries. Those entries contain the Member Entry and Media Resources IRIs of the Collection.
+ A Collection can contain any
+ number of entries of either kind. In the diagram of a Collection
+ below there are two entries. The first contains the IRI of a
+ Member Entry Resource. The second contains the IRIs of both a
+ Media Resource and a Media Link Entry Resource, which contains
+ the metadata for that Media Resource:
+ </t>
+<figure>
+<artwork>
+ Collection
+ Entry
+ Member Entry IRI -> Member Entry Resource
+
+ Entry
+ Member Entry IRI -> Media Link Entry Resource
+ Media IRI -> Media Resource
+
+</artwork>
+</figure>
+
+<t> Service Documents represent server-defined groups of Collections, and are
+used to initialize the process of creating and editing resources. </t>
+
+
+
+</section>
+
+<section title="Protocol Operations" anchor="operation">
+
+<section title="Retrieving a Service Document" anchor="find-collections">
+<figure>
+<artwork>
+Client Server
+ | |
+ | 1.) GET to Service Document |
+ |------------------------------------------>|
+ | |
+ | 2.) Service Document |
+ |<------------------------------------------|
+ | |
+</artwork>
+</figure>
+
+<t>
+
+<list style="numbers">
+ <t>The client sends a GET request using the URI of the Service Document.</t>
+ <t>The server responds with the document enumerating the IRIs of a set of
+ Collections and the capabilities of those Collections supported by the
+ server. The content of this document can vary based on aspects of the client
+ request, including, but not limited to, authentication credentials.</t>
+</list>
+</t>
+</section>
+
+<section title="Listing Collection Members" anchor="listing">
+
+<t>
+ 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 containing one Atom
+ Entry for each Member Entry Resource. See <xref target="templates"/> and <xref
+ target="atom-entry-extensions"/> for a description of the feed contents.
+</t>
+ <figure>
+ <artwork>
+Client Server
+ | |
+ | 1.) GET to Collection URI |
+ |------------------------------->|
+ | |
+ | 2.) 200 OK, Atom Feed Doc |
+ |<-------------------------------|
+ | |
+ </artwork>
+ </figure>
+
+ <t>
+ <list style="numbers">
+ <t>
+ The client sends a GET request to the URI of the Collection.
+ </t>
+ <t>
+ The server responds with an Atom Feed Document containing the IRIs
+ of the Collection members.
+ </t>
+ </list>
+ </t>
+
+ </section>
+
+
+
+
+<section title="Creating a Resource" anchor="post-to-create">
+
+<figure>
+<artwork>
+Client Server
+ | |
+ | 1.) POST to URI of Collection |
+ |------------------------------------------>|
+ | |
+ | 2.) 201 Created |
+ | Location: Member Entry URI |
+ |<------------------------------------------|
+ | |
+</artwork>
+</figure>
+
+<t>
+<list style="numbers">
+ <t>The client POSTs a representation of the Member to the URI of the
+ Collection.</t>
+ <t>If the Member Resource was created successfully, the server responds with a
+ status code of 201 and a Location: header that contains the IRI of the
+ newly created Member Entry Resource. Media Resources may have also
+ been created and their IRIs can be found through the Member Entry Resource.
+ See <xref target="media-link-entries"/> for more details.</t>
+</list>
+</t>
+
+</section>
+
+
+<section title="Editing a Resource" anchor="edit">
+
+<t>Once a resource has been created and its Member URI is known, that URI can be used
+to retrieve, update, and delete the resource.</t>
+
+ <section title="Retrieving a Resource">
+
+<figure>
+<artwork>
+Client Server
+ | |
+ | 1.) GET to Member URI |
+ |------------------------------------------>|
+ | |
+ | 2.) Member Representation |
+ |<------------------------------------------|
+ | |
+</artwork>
+</figure>
+
+<t>
+<list style="numbers">
+ <t>The client sends a GET request to the URI of a Member Resource to retrieve its
+ representation.</t>
+ <t>The server responds with the representation of the resource.</t>
+</list>
+</t>
+</section>
+
+<section title="Updating a Resource">
+
+<figure>
+<artwork>
+Client Server
+ | |
+ | 1.) PUT to Member URI |
+ |------------------------------------------>|
+ | |
+ | 2.) 200 OK |
+ |<------------------------------------------|
+</artwork>
+</figure>
+
+<t>
+<list style="numbers">
+ <t>The client PUTs an updated representation to the URI of a Member Resource.</t>
+ <t>Upon a successful update of the resource the server responds with a status
+ code of 200.</t>
+</list>
+</t>
+</section>
+
+<section title="Deleting a Resource">
+<figure>
+<artwork>
+Client Server
+ | |
+ | 1.) DELETE to Member URI |
+ |------------------------------------------>|
+ | |
+ | 2.) 200 Ok |
+ |<------------------------------------------|
+ | |
+</artwork>
+</figure>
+
+<t>
+<list style="numbers">
+ <t>The client sends a DELETE request to the URI of a Member Resource.</t>
+ <t>Upon the successful deletion of the resource the server responds with a
+ status code of 200. </t>
+</list>
+ A different approach is taken
+ for deleting Media Resources, see <xref target="media-link-entries"/> for details.
+</t>
+</section>
+</section>
+
+
+
+
+ <section title="Use of HTTP Response codes">
+ <t>
+ The Atom Protocol uses the response status codes defined in HTTP to
+ indicate the success or failure of an operation. Consult the HTTP
+ specification <xref target="RFC2616"/> for detailed definitions of each
+ status code. Implementers are asked to note that per the HTTP
+ specification, HTTP 4xx and 5xx response entities SHOULD include a
+ human-readable explanation of the error.
+ </t>
+ </section>
+
+ </section>
+
+
+ <section title="Atom Publishing Protocol Documents" anchor="xmlns">
+
+<section title='Document Types' anchor="appcatsext">
+ <t>This specification describes two kinds of Documents - Category
+ Documents and Service Documents.</t>
+
+ <t>A Category Document (<xref target="catdocs" />) contain lists of
+ categories specified using the "atom:category" element from the Atom
+ Syndication Format. A Service Document (<xref target="appdocs" />) describes
+ capabilities of workspaces, which are server-defined groupings of
+ Collections. </t>
+
+ <t>The namespace name <xref target="W3C.REC-xml-names-20060816"/> for either
+ kind of document is: </t>
+ <figure>
+ <artwork> http://purl.org/atom/app#</artwork>
+ </figure>
+
+ <t>
+ <cref>Needs to be updated with the final URI upon publication</cref>
+ </t>
+
+ <t> This specification uses the prefix "app:" for the namespace name. The
+ prefix "atom:" is used for "http://www.w3.org/2005/Atom", the namespace name of
+ the Atom Syndication Format <xref target="RFC4287"/>. The namespace prefixes
+ are not semantically significant.</t>
+
+ <t> Atom Publishing Protocol Documents MUST be well-formed XML. This
+ 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.</t>
+</section>
+
+<section title='Document Extensibility' anchor="appcatsex">
+
+ <t> Unrecognized markup in an Atom Publishing Protocol document is considered
+ "foreign markup" as defined in <xref target="RFC4287"/>. Such foreign markup
+ can be used anywhere within a Category or Service Document unless it is
+ explicitly forbidden. Processors that encounter foreign markup MUST NOT stop
+ processing or signal an error, and SHOULD preserve foreign markup when
+ transmitting such documents. </t>
+
+<t>The namespace name "http://purl.org/atom/app#" is reserved for forward
+ compatible revisions of the Category and Service Document types - this does
+ not exclude the addition of elements and attributes that might not be
+ recognised by processors conformant to this specification. Such unrecognised
+ markup from the "http://purl.org/atom/app#" namespace MUST be treated as
+ foreign markup.</t>
+
+</section>
+
+
+ </section>
+
+<section title="Category Documents" anchor="catdocs">
+
+
+ <t>
+Category Documents contain lists of categories described using the
+"atom:category" element from the Atom Syndication Format <xref target="RFC4287"/>.
+Categories can also appear in Service Documents and describe the categories allowed in a Collection (see <xref target="categories-elem" />).
+ </t>
+
+ <t>Category Documents are identified with the "application/atomcat+xml" media type (see
+ <xref target="iana"/>).
+ </t>
+
+
+<section title="Example" anchor="catdocseg">
+
+<figure>
+<artwork>
+<![CDATA[ <?xml version="1.0" ?>
+ <app:categories
+ xmlns:app="http://purl.org/atom/app#"
+ xmlns="http://www.w3.org/2005/Atom"
+ fixed="yes" scheme="http://example.com/cats/big3">
+ <category term="animal" />
+ <category term="vegetable" />
+ <category term="mineral" />
+ </app:categories>]]>
+</artwork>
+
+</figure>
+
+<t>
+This Category Document contains three categories, with the terms "animal",
+"vegetable", and "mineral". None of the categories use the 'label' attribute
+defined in <xref target="RFC4287"/>. They all inherit the
+"http://example.com/cats/big3" 'scheme' attribute declared on the app:categories
+element. Therefore if the "mineral" category were to appear in an Atom Entry or
+Feed Document, it would appear as:
+</t>
+
+<figure>
+<artwork>
+<![CDATA[ <category scheme="http://example.com/cats/big3" term="mineral" />]]>
+</artwork>
+</figure>
+
+</section>
+
+<section title="Element Definitions" anchor="catdocselemdef">
+
+<section title='The "app:categories" element' anchor="appcats">
+<t>
+The root of a Category Document is the "app:categories" element. An
+app:categories element can contain zero or more "atom:category" elements from the
+Atom namespace ("http://www.w3.org/2005/Atom").
+</t>
+
+<t>An app:category child element that has no "scheme" attribute inherits the
+attribute from its app:categories parent. An app:category child element with an
+existing "scheme" attribute does not inherit the "scheme" value of its
+"app:categories" parent element. </t>
+
+<section title='Attributes of "app:categories"' anchor="appcatsattr">
+
+
+<!-- FIXME: english -->
+<t>The app:categories element can contain a "fixed" attribute, with a value of
+either "yes" or "no", indicating whether the list of categories is a fixed or an
+open set. Newly created or updated members whose categories are not listed in
+the Collection Document MAY be rejected by the server. Collections that indicate
+the set is open SHOULD NOT reject otherwise acceptable members whose categories
+are not listed in the Collection.</t>
+
+<t>Alternatively, the app:categories element MAY contain an "href" attribute,
+whose value MUST be an IRI reference identifying a Category Document. If the
+"href" attribute is provided the app:categories element MUST be empty and MUST
+NOT have the "fixed" or "scheme" attributes.</t>
+
+
+ <t>
+ <figure>
+ <artwork name="app:categories"/>
+ </figure>
+ </t>
+
+</section>
+
+</section>
+
+</section>
+
+</section>
+
+
+
+
+
+
+ <section title="Service Documents" anchor="appdocs">
+
+
+ <t> For authoring to commence, a client needs to first discover the
+ capabilities and locations of the available collections. Service
+ Documents are designed to support this discovery process. How
+ Service Documents are in turn discovered is not defined in this
+ specification.
+
+ </t>
+
+ <t>A Service Document describes workspaces, which are server-defined groupings of Collections.
+ Service Documents are identified with the "application/atomserv+xml" media type (see
+ <xref target="iana"/>).
+ </t>
+
+ <t> There is no requirement that a server support multiple workspaces. In
+ addition, a Collection MAY appear in more than one Workspace.
+ </t>
+
+
+ <section title="Example" anchor="appdocs_example">
+
+ <figure>
+ <artwork name="introspectionDoc" />
+ </figure>
+
+
+ <t>
+ This Service Document describes two workspaces. The first Workspace
+ is called "Main Site", has two collections called "My Blog Entries"
+ and "Pictures" whose IRIs are "http://example.org/reilly/main" and
+ "http://example.org/reilly/pic" respectively. The "Pictures"
+ Workspace includes an "accept" element indicating that a client can
+ post image files to the Collection to create new entries. Entries
+ with associated media resources are discussed in <xref
+ target="media-link-entries"/>.
+ </t>
+ <t>
+ The second Workspace is called "Side Bar Blog" and has a single Collection
+ called "Remaindered Links" whose IRI is "http://example.org/reilly/list".
+ </t>
+
+<t>
+Within each of the two entry collections, the categories element provides a list
+of available categories for member entries. In the "My Blog Entries" Collection,
+the list of available categories is obtainable through the "href" attribute. The
+"Side Bar Blog" Collection provides a category list within the Service Document,
+but states the list is fixed, signaling a request from the server that entries
+be posted using only those two categories.
+</t>
+
+ </section>
+
+
+ <section title="Element Definitions" anchor="service_document_elements">
+
+ <section title='The "app:service" Element'>
+
+ <t>The root of a Service Document is the "app:service" element. </t>
+
+ <t>The "app:service" element is the container for service
+ information associated with one or more workspaces. An app:service
+ element MUST contain one or more app:workspace elements.</t>
+
+ <t>
+ <figure>
+ <artwork>
+namespace app = "http://purl.org/atom/app#"
+start = appService
+ </artwork>
+ </figure>
+
+ </t>
+
+ <t>
+ <figure>
+ <artwork name="app:service"/>
+ </figure>
+ </t>
+
+
+ </section>
+
+ <section title='The "app:workspace" Element'>
+ <!-- PaceCollectionOrderSignificance -->
+
+ <t>
+ The "app:workspace" element contains information elements about
+ the collections of resources available for editing. The
+ app:workspace element contains zero or more app:collection
+ elements.
+ </t>
+
+ <t>
+ <figure>
+ <artwork name="app:workspace"/>
+ </figure>
+ </t>
+
+
+ <t>
+ In an app:workspace element, the first app:collection element
+ MUST refer to the preferred or primary Collection. This
+ distinction is considered useful in scenarios where Members and
+ Media Link Entries are POSTed to different Collections. In the
+ following example, the "Eintragungen" collection would be
+ considered the preferred Collection:
+ </t>
+
+ <t>
+ <figure>
+ <artwork><![CDATA[ <service xmlns="http://purl.org/atom/app#"
+ xmlns:atom="http://www.w3.org/2005/Atom">
+ <workspace xml:lang="de">
+ <atom:title>Das Blog</atom:title>
+ <collection
+ href="http://example.org/blog/eintragungen" >
+ <atom:title>Eintragungen</atom:title>
+ </collection>
+ <collection
+ href="http://example.org/blog/fotos">
+ <atom:title>Fotos</atom:title>
+ <accept>image/*</accept>
+ </collection>
+ </workspace>
+ </service>]]> </artwork>
+ </figure>
+ </t>
+
+ <section title='The "atom:title" Element'>
+ <t>
+The app:workspace element MUST contain one "atom:title" element (as defined
+in <xref target="RFC4287"/>), giving
+a human-readable title for the workspace.
+ </t>
+ </section>
+
+ </section>
+
+
+
+ <section title='The "app:collection" Element'>
+ <t>
+ The "app:collection" element describes a Collection. The app:collection
+ element MAY contain one app:accept element and MAY contain any
+ number of app:categories elements. The app:collection element
+ MUST NOT contain more than one app:accept element.
+ </t>
+ <t>
+ <figure>
+ <artwork name="app:collection"/>
+ </figure>
+ </t>
+<section title='Usage in Atom Feed Documents'>
+ <t>
+ 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 Collection by which new entries can be added to
+ appear in the feed. The app:control element is considered
+ foreign markup as defined in Section 6 of <xref target="RFC4287"
+ />.
+
+ </t>
+
+</section>
+ <section title='The "href" Attribute'>
+ <t>The app:collection element MUST contain an "href"
+ attribute, whose value gives the IRI of the
+ Collection.
+ </t>
+ </section>
+ <section title='The "atom:title" Element'>
+ <t>
+ The app:collection Element MUST contain one "atom:title"
+ element, giving a human-readable title for the Workspace.
+ </t>
+ </section>
+
+
+ </section>
+
+ <section title='The "app:accept" Element' anchor="accept">
+
+ <t>
+
+ The "app:accept" element value specifies a comma-separated list
+ of media-ranges (see <xref target="RFC2616"/>) identifying the
+ types of representations that can be POSTed to the URI of a
+ Collection. Whitespace around and between media-range values is
+ considered insignificant and MUST be ignored.
+ </t>
+ <t>
+
+ The app:accept element is similar to the HTTP Accept request-header <xref target="RFC2616"/> with
+ the exception that app:accept has no notion of preference. As a result, the value
+ syntax of app:accept does not use "accept-params" or "q" arguments as specified in
+ <xref target="RFC2616"/>, section 14.1. </t>
+
+ <t> The order of media-ranges is not significant. The following lists are
+ all equivalent:
+ </t>
+
+ <t>
+ <figure>
+ <artwork><![CDATA[
+ <app:accept>image/png,image/*</app:accept>
+ <app:accept>image/*, image/png</app:accept>
+ <app:accept> image/* </app:accept>]]> </artwork>
+ </figure>
+ </t>
+
+ <t>
+ A value of "entry" may appear in any list of media-ranges in an
+ accept element and indicates that Atom Entry Documents can be
+ posted to the Collection. If the accept element is omitted or
+ empty, clients SHOULD assume that only Atom Entry documents will
+ be accepted by the Collection.
+
+<!-- FIXME -->
+
+ </t>
+
+
+ <t>
+ <figure>
+ <artwork name="app:accept" />
+ </figure>
+ </t>
+ </section>
+
+<section title='The "app:categories" Element' anchor="categories-elem">
+
+<t>The "app:categories" element provides a listing of the categories that can be
+applied to the members of a Collection.</t>
+
+ <t>
+ <figure>
+ <artwork name="app:categories" />
+ </figure>
+</t>
+
+<t>
+The app:categories element MAY contain a "fixed" attribute, with a value of
+either "yes" or "no", indicating whether or not the listing of categories is
+considered to be a fixed, or closed set. The absence of the "fixed" attribute
+is equivalent to the presence of a "fixed" attribute with a value of "no".
+Collections that indicate a fixed set
+MAY reject members that include categories not specified in the provided
+listing. Collections that indicate an open set SHOULD NOT reject otherwise
+acceptable members whose categories are not present in the
+provided list.
+</t>
+
+<t>
+The app:categories element MAY contain an "href" attribute, whose value MUST be
+an IRI reference identifying a Category Document. If the "href" attribute is
+provided, the app:categories element MUST be empty and the
+"fixed" and "scheme" attributes MUST NOT be present.
+</t>
+
+
+</section>
+
+
+ </section>
+
+
+
+</section>
+
+
+
+
+
+ <section title="Creating and Editing Resources" anchor="collection_resource">
+
+<section title="Member URIs" anchor="memuri">
+
+<t>
+ The Member URI supports retrieving, updating and deleting the resource
+ using HTTP GET, PUT and DELETE as described in this section. Retrieval and updating
+ of Member Entry Resources are done via Atom Entry representations.
+</t>
+
+<t>
+ Member Entry URIs appear in two places. First, they are returned in a Location header
+ after successful resource creation using POST, as described below. Second, in
+ the entries of a Collection document, by an atom:link element with a link relation of
+ "edit".
+</t>
+
+<t>
+Each Member Entry SHOULD contain such an atom:link element
+providing its Member Entry URI.
+</t>
+
+</section>
+
+ <section title="Creating resources with POST">
+ <t>
+ To add members to a Collection, clients send POST requests to the
+ URI of a Collection. Successful member creation is normally
+ indicated with a 201 ("Created") response code. Collections MAY
+ generate a response with a status code of 415 ("Unsupported Media
+ Type") to indicate media-type of POSTed entity is not allowed or
+ supported by the Collection.
+ </t>
+ <t>
+ When a Member Resource is created in the Collection which
+ received the POST, its Member Entry URI MUST be returned in an
+ HTTP Location header.
+ </t>
+ <t>
+<!-- PaceDontRepeatMemberURI -->
+
+When the server generates a response with a status code of 201 ("Created"), it
+SHOULD also return a response body, which if provided, MUST be an Atom Entry
+Document representing the newly-created resource.
+
+ </t>
+ <t>
+
+ Since the server is free to alter the posted entry, for example by
+ changing the content of the "id" element, returning the Entry as
+ described in the previous paragraph can be useful to the client,
+ enabling it to correlate the client and server views of the new
+ Entry.
+ </t>
+ <t>
+
+ When the POST request contains an Atom Entry Document, the
+ response from the server SHOULD contain a Content-Location header
+ that contains the same character-by-character value as the
+ Location header.
+ </t>
+ <t>
+
+ 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 issues in posting
+ such content, see <xref target="media-link-entries"/>.
+
+ </t>
+
+
+
+
+
+
+
+ <section title="Example" anchor="create-example">
+ <t>Below, the client sends a POST request containing an Atom Entry representation to the URI of the Collection:
+ <figure>
+ <artwork><![CDATA[
+ POST /myblog/entries HTTP/1.1
+ Host: example.org
+ User-Agent: Thingio/1.0
+ Authorization: Basic ZGFmZnk6c2VjZXJldA==
+ Content-Type: application/atom+xml
+ Content-Length: nnn
+ Slug: First Post
+
+ <?xml version="1.0" ?>
+ <entry xmlns="http://www.w3.org/2005/Atom"
+ xmlns:app="http://purl.org/atom/app#">
+ <title>Atom-Powered Robots Run Amok</title>
+ <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
+ <updated>2003-12-13T18:30:02Z</updated>
+ <author><name>John Doe</name></author>
+ <content>Some text.</content>
+ </entry>]]></artwork>
+ </figure>
+ </t>
+
+ <t>
+ The server signals a successful creation with a status code of
+ 201. The response includes a "Location" header indicating the
+ Member Entry URI of the Atom Entry and a representation of that Entry in
+ the body of the response.
+
+ <figure>
+ <artwork><![CDATA[
+ HTTP/1.1 201 Created
+ Date: Fri, 7 Oct 2005 17:17:11 GMT
+ Content-Length: nnn
+ Content-Type: application/atom+xml; charset="utf-8"
+ Content-Location: http://example.org/edit/first-post.atom
+ Location: http://example.org/edit/first-post.atom
+
+ <?xml version="1.0"?>
+ <entry xmlns="http://www.w3.org/2005/Atom"
+ xmlns:app="http://purl.org/atom/app#">
+ <title>Atom-Powered Robots Run Amok</title>
+ <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
+ <updated>2003-12-13T18:30:02Z</updated>
+ <author><name>John Doe</name></author>
+ <content>Some text.</content>
+ <link rel="edit"
+ href="http://example.org/edit/first-post.atom"/>
+ </entry>]]></artwork>
+ </figure>
+ </t>
+
+ <t>
+ The Entry created and returned by the server might not match the
+ Entry 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:author values and MAY choose to remove or add other elements
+ and attributes, or change element and attribute values.
+ </t>
+ <t>
+ In particular, the publishing system in this example filled in some
+ 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.
+ </t>
+
+ </section> <!-- Collections | Example -->
+
+
+
+
+ </section> <!-- Creating with POST -->
+
+
+ <section title="Updating Resources with PUT" anchor="update-via-PUT">
+ <t>
+ To update a resource, clients send PUT requests to its Member URI, as
+ specified in <xref target="RFC2616"/>.
+ </t>
+ <t>
+ To avoid unintentional loss of data when editing Member Entries or
+ Media Link Entries, Atom Protocol clients SHOULD preserve all metadata
+ that has not been intentionally modified, including unknown
+ foreign markup as defined in Section 6 of <xref
+ target="RFC4287"/>.
+ </t>
+ </section>
+
+
+ <section title="Deleting Resources with DELETE" anchor="update-via-DELETE">
+
+ <t>
+ To delete a resource, clients send DELETE requests to its Member URI, as
+ specified in <xref target="RFC2616"/>. For Media
+ Resources, deletion of a Media Link Entry SHOULD result in the deletion of the
+ associated Media Resource.
+
+ </t>
+
+ </section>
+
+
+
+
+ <section title="Media Resources and Media Link Entries" anchor="media-link-entries">
+
+ <!-- Bill: heavily edited: original 09 text below for cmp -->
+
+ <t> A client can POST a media type other than application/atom+xml to a
+ Collection. Such a request creates two new resources - one that
+ corresponds to the entity sent in the request, called the Media
+ Resource, and an associated Member Entry, called the Media Link
+ Entry. Media Link Entries are represented as Atom Entries. The server
+ can signal the media types it will accept via the "accept" element in
+ the Service Document (<xref target="accept"/>). </t>
+
+ <t>The Media Link Entry contains the IRI of the Media Resource
+ and makes metadata about it separately available for
+ retrieval and update. The Media Link Entry is used to store
+ metadata about the (perhaps non-textual) Media Resource. </t>
+
+ <t> Successful responses to creation requests MUST include the URI of
+ the Media Link Entry in the Location header. The Media Link
+ Entry SHOULD contain an atom:link element with a link relation of
+ "edit-media" that contains the Media Resource IRI.
+ The Media Link Entry MUST have an "atom:content" element with a
+ non-empty "src" attribute. The value of the "src" attribute
+ is an IRI of the newly created Media Resource.
+ It is OPTIONAL that the IRI of the "src" attribute on the
+ atom:content element be the same as the Media Resource IRI. That is,
+ the "src" attribute value might instead be a link into a static cache
+ or content distribution network and not be the Media Resource IRI.
+ </t>
+
+ <t>Implementers are asked to note that according to the requirements of
+ <xref target="RFC4287"/>, entries, and thus Media Link Entries, MUST
+ contain an atom:summary element. Upon successful creation of a Media
+ Link Entry, a server MAY choose to populate the atom:summary element
+ (as well as other required elements such as 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 client to modify the server
+ selected values for these elements.</t>
+
+<!-- we just said this a few paras back
+ <t>Deletion of a Media Link Entry SHOULD result in the deletion of the
+ associated Media Resource. </t>
+-->
+ <t>For resource creation this specification only defines cases where
+ the 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
+ media type. It does not specify any request semantics or server
+ behavior in the case where the POSTed media-type is
+ "application/atom+xml" but the body is something other than an Atom
+ Entry. In particular, what happens on POSTing an Atom Feed Document
+ to a Collection using the "application/atom+xml" media type is
+ undefined.
+ </t>
+
+
+ </section> <!-- Media resources and link entries -->
+
+<section title="The Slug: Header">
+
+
+<t>Slug is a HTTP entity-header whose value is a "slug" - a short name
+that can be used as part of the URI for a Member Resource.</t>
+
+<t>
+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 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 atom:id or as the title of a Media Link Entry (see
+<xref target="media-link-entries"/>.).
+</t>
+
+
+
+<t>
+Servers MAY ignore the Slug entity-header and MAY alter its value before using
+it. For example, the server MAY filter out some characters or replace accented
+letters with non-accented ones, spaces with underscores, etc.
+</t>
+
+<section title="Slug: Header syntax">
+
+<t>The syntax of this header MUST conform to the augmented BNF grammar in section 2.1 of
+the HTTP/1.1 specification <xref target="RFC2616" />. The TEXT rule is described in section 2.2 of the same document. </t>
+
+<figure>
+<artwork>
+<![CDATA[ Slug = "Slug" ":" *TEXT
+]]></artwork>
+</figure>
+
+
+<t>Clients MAY send non-ASCII characters in the Slug entity-header, which they MUST
+encode using "encoded-words", as defined in <xref target="RFC2047" />. Servers SHOULD treat the slug
+as <xref target="RFC2047" /> encoded if it matches the "encoded-words" production. </t>
+
+
+</section>
+
+
+
+ <section title="Examples" anchor="title-header-example">
+ <t>
+ Below, the client sends a POST request containing a PNG image to the
+ URI of the Collection:
+ </t>
+
+ <t>
+ <figure>
+ <artwork><![CDATA[
+ POST /myblog/entries HTTP/1.1
+ Host: example.org
+ Content-Type: image/png
+ Slug: The Beach
+ Authorization: Basic ZGFmZnk6c2VjZXJldA==
+ Content-Length: nnn
+
+ ...binary data...]]> </artwork>
+ </figure>
+ </t>
+
+
+ <t>
+ The server signals a successful creation with a status code
+ of 201. The response includes a Location header indicating
+ the Member URI of the Media Link Entry and a representation
+ of that entry in the body of the response. The Media Link
+ Entry includes a content element with a src attribute,
+ and a link using the link
+ relation "edit-media" specifying the IRI to be used for
+ modifying the Media Resource.
+ </t>
+
+ <t>
+ <figure>
+ <artwork><![CDATA[
+ HTTP/1.1 201 Created
+ Date: Fri, 7 Oct 2005 17:17:11 GMT
+ Content-Length: nnn
+ Content-Type: application/atom+xml; charset="utf-8"
+ Content-Location: http://example.org/myblog/edit/the_beach
+ Location: http://example.org/myblog/edit/the_beach
+
+ <?xml version="1.0"?>
+ <entry xmlns="http://www.w3.org/2005/Atom">
+ <title>The Beach</title>
+ <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
+ <updated>2005-10-07T17:17:08Z</updated>
+ <author><name>Daffy</name></author>
+ <summary type="text" />
+ <content type="image/png"
+ src="http://example.org/media/the_beach.png"/>
+ <link rel="edit-media"
+ href="http://example.org/media/edit/the_beach.png" />
+ <link rel="edit"
+ href="http://example.org/myblog/edit/the_beach />
+ </entry>]]> </artwork>
+ </figure>
+ </t>
+
+ <t>
+ Here is an example of the Slug: header that uses the encoding
+ rules of <xref target="RFC2047"/>.
+ </t>
+
+ <t>
+ <figure>
+ <artwork><![CDATA[
+ POST /myblog/entries HTTP/1.1
+ Host: example.org
+ Content-Type: image/png
+ Slug: =?iso-8859-1?q?The_Beach?=
+ Authorization: Basic ZGFmZnk6c2VjZXJldA==
+ Content-Length: nnn
+
+ ...binary data...]]> </artwork>
+ </figure>
+ </t>
+
+ <t>
+ See <xref target="create-example"/> for an example
+ of the Slug: header applied to the creation of
+ a Member Entry Resource.
+ </t>
+
+
+
+
+ </section> <!-- Slug: header example -->
+
+ </section> <!-- Slug: header -->
+
+
+ </section> <!-- Collections -->
+
+ <section title="Listing Collections" anchor="templates">
+
+<t>Collection resources MUST provide representations in the form of Atom Feed documents
+whose entries represent the Members in the Collection.
+Each entry in the Feed Document SHOULD have an atom:link element with a relation of "edit" (See <xref target="new-link-relation"/>). </t>
+
+<t>The entries in the returned Atom Feed SHOULD be ordered by their "atom:updated" property, with
+the most recently updated entries coming first in the document order. Clients SHOULD be constructed in consideration of the fact that
+changes which do not alter the atom:updated value of an entry will not affect the position of the entry in a Collection.
+</t>
+
+<t>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 GET on the URI of the Member Entry before editing.</t>
+
+
+
+<section title="Collection Paging" >
+
+<t>Collections can contain large numbers of resources. A naive client 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 server would waste large
+amounts of bandwidth and processing time on clients unable to handle the
+response. For this reason, servers MAY return a partial listing of the most
+recently updated Member Resources. Such partial feed documents MUST have an
+atom:link with a "next" relation whose "href" value is the URI of the next
+partial listing of the Collection (the next most recently updated Member Resources)
+where it exists. This is called "Collection paging".
+</t>
+
+
+
+
+<t> The returned Atom Feed MAY contain a subset the Member Entries for a
+Collection. In addition, the Atom Feed document MAY contain link elements with "rel"
+attribute values of "next", "previous", "first" and "last" that can be used to
+navigate through the complete set of matching entries.
+</t>
+
+<t>
+For instance, suppose a client is supplied the URI "http://example.org/entries/go"
+of a Collection of Member entries, where the server as a matter of
+policy avoids generating feed documents containing more than 10 entries.
+The Atom Feed document for the Collection will then represent the first 'page' in
+a set of 10 linked feed documents. The "first" relation will reference the initial feed document in the set and the "last"
+relation references the final Atom Feed Document in the set. Within each document, the "next" and
+"previous" link relations reference the preceding and subsequent documents.
+
+<figure>
+<artwork><![CDATA[
+ <feed xmlns="http://www.w3.org/2005/Atom">
+ <link rel="first"
+ href="http://example.org/entries/go" />
+ <link rel="next"
+ href="http://example.org/entries/2" />
+ <link rel="last"
+ href="http://example.org/entries/10" />
+ ...
+ </feed>
+]]></artwork>
+</figure>
+</t>
+
+<t>
+The "next" and "previous" link elements for the feed 'page' located at
+"http://example.org/entries/2" would look like this:
+<figure>
+<artwork><![CDATA[
+ <feed xmlns="http://www.w3.org/2005/Atom">
+ <link rel="first"
+ href="http://example.org/entries/go" />
+ <link rel="previous"
+ href="http://example.org/entries/go" />
+ <link rel="next"
+ href="http://example.org/entries/3" />
+ <link rel="last"
+ href="http://example.org/entries/10" />
+ ...
+ </feed>
+]]></artwork>
+</figure>
+
+
+</t>
+
+
+ </section>
+ <section title='The "app:edited" Element'>
+ <t>
+ The "app:edited" element is a Date construct as defined by
+ [RFC4287] whose value indicates the most recent instant in
+ time when an entry was edited, including when created. Atom
+ entry elements in Collection documents SHOULD contain one
+ "app:edited" element, and MUST NOT contain more than one.
+ </t>
+
+ <figure>
+ <artwork>
+appEdited = element app:edited ( atomDateConstruct )
+</artwork>
+</figure>
+
+ <t>
+ The server SHOULD change the value of this element every time
+ a Collection Member Resource or an associated Media Resource
+ has been edited by any means.
+ </t>
+ </section>
+</section>
+
+
+
+
+ <section title="Atom Format Link Relation Extensions" anchor="atom-entry-extensions">
+
+ <section title='The "edit" Link Relation' anchor="new-link-relation">
+ <t>
+ This specification adds the value "edit" to the Atom Registry of
+ Link Relations (see section 7.1 of <xref target="RFC4287"/>).
+ The value of "edit" specifies that the value of the href
+ attribute is the 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. An
+ atom:entry MUST contain no more than one "edit" link relation.
+ </t>
+ </section>
+
+
+ <section title='The "edit-media" Link Relation' anchor="new-media-link-relation">
+ <t>
+ This specification adds the value "edit-media" to the Atom
+ Registry of Link Relations (see section 7.1 of
+ <xref target="RFC4287"/>). When appearing 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.
+ </t>
+ <t>
+ An atom:entry element MAY contain zero or more "edit-media" 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 type and hreflang attribute values. All "edit-media" link
+ relations in the same entry reference the same resource. If a
+ client encounters multiple "edit-media" link relations in an
+ entry then it SHOULD choose a link based on the client
+ preferences for type and hreflang. If a client encounters
+ multiple "edit-media" link relations in an entry and has no
+ preference based on the type and hreflang attributes then the
+ client SHOULD pick the first "edit-media" link relation in
+ document order.
+ </t>
+ </section>
+
+ </section>
+
+ <section title="Atom Publishing Controls" anchor="pub-control">
+
+
+
+ <t>
+ This specification defines an Atom Format Structured Extension,
+ as defined in Section 6 of <xref target="RFC4287"/>, for publishing
+ control within the http://purl.org/atom/app# namespace.
+ </t>
+
+
+ <section title='The "app:control" Element'>
+
+ <figure>
+ <artwork>
+namespace app = "http://purl.org/atom/app#"
+
+ pubControl =
+ element app:control {
+ atomCommonAttributes,
+ pubDraft?
+ & extensionElement
+ }
+
+ pubDraft =
+ element app:draft { "yes" | "no" }</artwork>
+ </figure>
+
+
+ <t>
+ The "app:control" element MAY appear as a child of an atom:entry which
+ is being created or updated via the Atom Publishing Protocol. The
+ app:control element MUST appear only once in an Entry. The
+ app:control element is considered foreign markup as defined in Section
+ 6 of <xref target="RFC4287"/>.
+ </t>
+ <t>
+ The app:control element and its child elements MAY be included in Atom
+ Feed or Entry Documents.
+ </t>
+ <t>
+ The app:control element can contain an optional "app:draft" element as
+ defined below, and can contain extension elements as defined in
+ Section 6 of <xref target="RFC4287"/>.
+ </t>
+
+ <section title='The "app:draft" Element'>
+ <t>
+ 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 client request that the Member Resource be made publicly visible. If 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 by the client to control the visibility of a Member
+ Resource and the app:draft element MAY be ignored by the server.
+ </t>
+ </section>
+
+ </section>
+
+ </section>
+
+ <section title="Securing the Atom Publishing Protocol">
+ <t>
+ The Atom Publishing Protocol is based on HTTP. Authentication requirements for HTTP
+ are covered in Section 11 of <xref target="RFC2616"/>.
+ </t>
+ <t>
+ The use of authentication mechanisms to prevent posting or editing by unknown or
+ unauthorized clients is RECOMMENDED but not required. When authentication is not
+ used, clients and servers are vulnerable to trivial spoofing, denial of service
+ and defacement attacks, however, in some contexts, this is an acceptable risk.
+ </t>
+ <t>
+ The type of authentication deployed is a local decision made by the server operator.
+ Clients are likely to face authentication schemes that vary across server deployments.
+ At a minimum, client and server implementations MUST be capable of being configured
+ to use HTTP Basic Authentication <xref target="RFC2617"/> in conjunction with a TLS connection
+ <xref target="RFC4346"/> as specified by <xref target="RFC2818"/>.
+ </t>
+ <t>
+ The choice of authentication mechanism will impact interoperability. The minimum level
+ of security referenced above (Basic Auth with TLS) is considered good practice
+ for Internet applications at the time of publication of this specification and
+ sufficient for establishing a baseline for interoperability. Implementers should,
+ in general, investigate and use alternative mechanisms regarded as equivalently
+ good or better at the time of deployment. It is RECOMMENDED that clients be
+ implemented in such a way that allows new authentication schemes to be deployed.
+ </t>
+ <t>
+ Because this protocol uses HTTP response status codes as the primary means of
+ reporting the result of a request, servers are advised to respond to unauthorized
+ or unauthenticated requests using an appropriate 4xx HTTP response code
+ (e.g. 401 "Unauthorized" or 403 "Forbidden") in accordance with <xref target="RFC2617"/>.
+ </t>
+ </section>
+
+ <section title="Security Considerations">
+ <t>
+ As an HTTP-based protocol, APP is subject to the security considerations found
+ in Section 15 of <xref target="RFC2616"/>.
+ </t>
+
+ <section title="Denial of Service">
+ <t>
+ Atom Publishing server implementations need to take adequate precautions to ensure
+ malicious clients cannot consume excessive server resources (CPU, memory, disk, etc).
+ </t>
+ </section>
+
+ <section title="Replay Attacks">
+ <t>
+ Atom Publishing server implementations are susceptible to replay attacks. Specifically,
+ this specification does not define a means of detecting duplicate requests. Accidentally
+ sent duplicate requests are indistinguishable from intentional and malicious replay attacks.
+ </t>
+ </section>
+
+ <section title="Spoofing Attacks">
+ <t>
+ Atom Publishing implementations are susceptible to a variety of spoofing attacks. Malicious
+ clients may send Atom entries containing inaccurate information anywhere in the document.
+ </t>
+ </section>
+
+ <section title="Linked Resources">
+ <t>
+ Atom Feed and Entry documents can contain XML External Entities as defined in Section
+ 4.2.2 of <xref target="W3C.REC-xml-20060816"/>. Atom implementations are not required to load external entities.
+ External entities are subject to the same security concerns as any network operation
+ and can alter the semantics of an Atom document. The same issues exist for resources
+ linked to by Atom elements such as atom:link and atom:content.
+ </t>
+ </section>
+
+ <section title="Digital Signatures and Encryption">
+
+ <t>
+ Atom Entry Documents sent to a server might contain XML Digital Signatures
+ <xref target="W3C.REC-xmldsig-core-20020212"/> and might be encrypted using XML Encryption
+ <xref target="W3C.REC-xmlenc-core-20021210"/> as specified in Section 5 of <xref target="RFC4287"/>.
+ </t>
+
+ <t>
+ Servers are allowed to modify received resource representations in ways that
+ can invalidate signatures covering those representations.
+ </t>
+ </section>
+
+ <section title="URIs and IRIs">
+ <t>
+ Atom Publishing Protocol implementations handle URIs and IRIs. See Section 7 of <xref target="RFC3986"/> and
+ Section 8 of <xref target="RFC3987"/>.
+ </t>
+ </section>
+ </section>
+
+
+
+
+ <section title="IANA Considerations" anchor="iana">
+
+
+ <section title="Content-type registration for 'application/atomserv+xml'" anchor="iana-atomserv">
+
+ <t>An Atom Publishing Protocol Service Document, when serialized
+ as XML 1.0, can be identified with the following media type:</t>
+
+ <t>
+ <list style="hanging">
+ <t hangText="MIME media type name:"> application</t>
+ <t hangText="MIME subtype name:"> atomserv+xml</t>
+ <t hangText="Mandatory parameters:"> None.</t>
+ <t hangText="Optional parameters:">
+ <list style="hanging">
+ <t hangText='"charset":'> This parameter has identical
+ semantics to the charset parameter of the
+ "application/xml" media type as specified in <xref
+ target="RFC3023"/>.</t>
+ </list>
+ </t>
+
+ <t hangText="Encoding considerations:"> Identical to those of
+ "application/xml" as described in <xref target="RFC3023"/>,
+ section 3.2.</t>
+
+ <t hangText="Security considerations:"> As defined in this
+ specification. <cref>update upon publication</cref></t>
+
+ <t>In addition, as this media type uses the "+xml" convention,
+ it shares the same security considerations as described in
+ <xref target="RFC3023"/>, section 10.</t>
+
+ <t hangText="Interoperability considerations:"> There are no
+ known interoperability issues.</t>
+
+ <t hangText="Published specification:"> This
+ specification. <cref>update upon publication</cref></t>
+
+ <t hangText="Applications that use this media type:"> No known
+ applications currently use this media type.</t>
+
+ </list>
+ </t>
+
+ <t>Additional information:</t>
+
+ <t>
+ <list style="hanging">
+
+ <t hangText="Magic number(s):"> As specified for
+ "application/xml" in <xref target="RFC3023"/>, section
+ 3.2.</t>
+
+ <t hangText="File extension:"> .atomsrv</t>
+
+ <t hangText="Fragment identifiers:"> As specified for
+ "application/xml" in <xref target="RFC3023"/>, section 5.</t>
+
+ <t hangText="Base URI:"> As specified in <xref
+ target="RFC3023"/>, section 6.</t>
+
+ <t hangText="Macintosh File Type code:"> TEXT</t>
+
+ <t hangText="Person and email address to contact for further information:"> Joe Gregorio <joe at bitworking.org></t>
+
+ <t hangText="Intended usage:">
+ COMMON</t> <t hangText="Author/Change controller:"> This
+ specification's author(s). <cref>update upon publication</cref></t>
+ </list>
+ </t>
+ </section>
+
+ <section title="Content-type registration for 'application/atomcat+xml'" anchor="iana-atomcat">
+
+ <t>An Atom Publishing Protocol Category Document, when serialized
+ as XML 1.0, can be identified with the following media type:</t>
+
+ <t>
+ <list style="hanging">
+ <t hangText="MIME media type name:"> application</t>
+ <t hangText="MIME subtype name:"> atomcat+xml</t>
+ <t hangText="Mandatory parameters:"> None.</t>
+ <t hangText="Optional parameters:">
+ <list style="hanging">
+ <t hangText='"charset":'> This parameter has identical
+ semantics to the charset parameter of the
+ "application/xml" media type as specified in <xref
+ target="RFC3023"/>.</t>
+ </list>
+ </t>
+
+ <t hangText="Encoding considerations:"> Identical to those of
+ "application/xml" as described in <xref target="RFC3023"/>,
+ section 3.2.</t>
+
+ <t hangText="Security considerations:"> As defined in this
+ specification. <cref>update upon publication</cref></t>
+
+ <t>In addition, as this media type uses the "+xml" convention,
+ it shares the same security considerations as described in
+ <xref target="RFC3023"/>, section 10.</t>
+
+ <t hangText="Interoperability considerations:"> There are no
+ known interoperability issues.</t>
+
+ <t hangText="Published specification:"> This
+ specification. <cref>update upon publication</cref></t>
+
+ <t hangText="Applications that use this media type:"> No known
+ applications currently use this media type.</t>
+
+ </list>
+ </t>
+
+ <t>Additional information:</t>
+
+ <t>
+ <list style="hanging">
+
+ <t hangText="Magic number(s):"> As specified for
+ "application/xml" in <xref target="RFC3023"/>, section
+ 3.2.</t>
+
+ <t hangText="File extension:"> .atomcat</t>
+
+ <t hangText="Fragment identifiers:"> As specified for
+ "application/xml" in <xref target="RFC3023"/>, section 5.</t>
+
+ <t hangText="Base URI:"> As specified in <xref
+ target="RFC3023"/>, section 6.</t>
+
+ <t hangText="Macintosh File Type code:"> TEXT</t>
+
+ <t hangText="Person and email address to contact for further information:"> Joe Gregorio <joe at bitworking.org></t>
+
+ <t hangText="Intended usage:">
+ COMMON</t> <t hangText="Author/Change controller:"> This
+ specification's author(s). <cref>update upon publication</cref></t>
+ </list>
+ </t>
+ </section>
+
+<!--
+http://www.rfc-editor.org/rfc/rfc3864.txt
+-->
+
+<section title="Header field registration for 'SLUG'" anchor="iana-slug">
+
+ <t><cref source="dehora">incomplete section</cref></t>
+ <t>
+ <list style="hanging">
+ <t hangText="Header field:">SLUG</t>
+ <t hangText="Applicable protocol:">http <xref target="RFC2616" /></t>
+ <t hangText="Status:">standard.</t>
+ <t hangText=" Author/Change controller:">IETF (iesg at ietf.org) Internet Engineering Task Force</t>
+ <t hangText="Specification document(s):">
+ draft-ietf-atompub-protocol-11.txt
+ (<cref source="dehora">update on rfc number
+ assignment</cref>)</t>
+ <t hangText="Related information:"></t>
+ </list>
+ </t>
+</section>
+
+
+
+ </section>
+
+
+ </middle>
+ <back>
+
+
+ <references title='Normative References'>
+
+ &rfc2119;
+ <!-- &rfc2246; -->
+ <!--&rfc2396;-->
+ &rfc2616;
+ &rfc2617;
+ &rfc2818;
+ &rfc4346;
+ &rfc4287;
+ &rfc3023;
+ &rfc3986;
+ &rfc3987;
+ &rfc2047;
+ &XML;
+ &XMLNS;
+ &XMLBASE;
+ &INFOSET;
+ &XMLDSIG;
+ &XMLENC;
+
+ </references>
+
+ <references title="Informative References">
+
+ &WEBARCH;
+ <reference anchor="RNC">
+ <front>
+ <title>RELAX NG Compact Syntax</title>
+ <author initials="J." surname="Clark" fullname="James Clark">
+ <organization/>
+ </author>
+ <date month="December" year="2001" />
+ </front>
+
+ </reference>
+
+ </references>
+<section title="Contributors">
+ <t>
+ The content and concepts within are a product of the Atom community and the Atompub Working Group.
+ </t>
+ <t>
+ <cref source="dehora">chairs to compile a contribution list for 1.0</cref>
+ <!--
+ The Atompub Working Group has many active contributors who proposed ideas and wording
+ for this document, including:
+ -->
+ </t>
+</section>
+
+<section title="RELAX NG Compact Schema" anchor="schema">
+<t>
+This appendix is informative.
+</t>
+
+<t>
+The Relax NG schema explicitly excludes elements in the Atom Protocol namespace which are
+not defined in this revision of the specification. Requirements for Atom Protocol
+processors encountering such markup are given in Section 6.2 and Section 6.3 of
+<xref target="RFC4287" />.
+</t>
+
+<t> The Schema for Service Documents: </t>
+
+ <figure>
+
+<artwork name="app:allSchema" />
+
+ </figure>
+
+<t> The Schema for Category Documents: </t>
+
+
+ <figure>
+
+<artwork name="app:catSchema" />
+
+ </figure>
+
+ </section>
+
+
+
+
+
+ <section title="Revision History">
+
+ <t>draft-ietf-atompub-protocol-11:
+ Parts of PaceAppEdited. PaceSecurityConsiderationsRevised.
+ </t>
+
+
+<t>draft-ietf-atompub-protocol-10: PaceRemoveTitleHeader2, PaceSlugHeader4,
+PaceOnlyMemberURI,PaceOneAppNamespaceOnly, PaceAppCategories,
+PaceExtendIntrospection, UseElementsForAppCollectionTitles3, renamed
+Introspection to Service, lots of good editorials suggestions, updated
+media example with slug, moved xml conventions to convention
+sections, renamed XMl related Conventions to Atom Publishing Protocol Documents,
+added auth header to examples, consolidated definition of all resource types into
+the model section, added IANA reg info for application/atomcat+xml.
+</t>
+
+<t>draft-ietf-atompub-protocol-09: PaceWorkspaceMayHaveCollections, PaceMediaEntries5,
+ http://www.imc.org/atom-protocol/mail-archive/msg05322.html, and
+ http://www.imc.org/atom-protocol/mail-archive/msg05272.html
+</t>
+
+<t>draft-ietf-atompub-protocol-08: added infoset ref; added wording re IRI/URI; fixed URI/IRI ;
+next/previous fixed as per Atom LinkRelations Attribute (http://www.imc.org/atom-protocol/mail-archive/msg04095.html);
+incorporated: PaceEditLinkMustToMay; PaceMissingDraftHasNoMeaning, PaceRemoveMemberTypeMust, PaceRemoveMemberTypePostMust,
+PaceTitleHeaderOnlyInMediaCollections, PacePreserveForeignMarkup, PaceClarifyTitleHeader, PaceClarifyMediaResourceLinks,
+PaceTwoPrimaryCollections;
+</t>
+
+ <t>draft-ietf-atompub-protocol-07: updated Atom refs to RFC4287;
+ incorporated PaceBetterHttpResponseCode;
+ PaceClarifyCollectionAndDeleteMethodByWritingLessInsteadOfMore;
+ PaceRemoveAcceptPostText; PaceRemoveListTemplate2;
+ PaceRemoveRegistry; PaceRemoveWhoWritesWhat;
+ PaceSimplifyClarifyBetterfyRemoveBogusValidityText;
+ PaceCollectionOrderSignificance; PaceFixLostIntrospectionText;
+ PaceListPaging; PaceCollectionControl; element typo in Listing
+ collections para3 (was app:member-type, not app:list-template);
+ changed post atom entry example to be valid. Dropped inline use of
+ 'APP'. Removed nested diagram from section 4. Added ed notes in the
+ security section.
+
+ </t>
+
+ <t>draft-ietf-atompub-protocol-06 - Removed: Robert Sayre from the
+ contributors section per his request.
+ Added in PaceCollectionControl. Fixed all the {daterange} verbage
+ and examples so they all use a dash. Added full rnc schema.
+ Collapsed Introspection and Collection documents into a single
+ document. Removed {dateRange} queries. Renamed search to list.
+ Moved discussion of media and entry collection until
+ later in the document and tied the discussion to the
+ Introspection element app:member-type.
+ </t>
+
+ <t>draft-ietf-atompub-protocol-05 - Added: Contributors section. Added:
+ de hOra to editors. Fixed: typos. Added diagrams and description to
+ model section. Incorporates PaceAppDocuments, PaceAppDocuments2,
+ PaceSimplifyCollections2 (large-sized chunks of it anyhow: the notions
+ of Entry and Generic resources, the section 4 language on the Protocol
+ Model, 4.1 through 4.5.2, the notion of a Collection document, as in
+ Section 5 through 5.3, Section 7 "Collection resources", Selection
+ resources (modified from pace which talked about search); results in
+ major mods to Collection Documents, Section 9.2 "Title: Header" and
+ brokeout para to section 9.1 Editing Generic Resources). Added XML
+ namespace and language section. Some cleanup of front matter. Added
+ Language Sensitivity to some attributes. Removed resource descriptions
+ from terminology. Some juggling of sections. See:
+ http://www.imc.org/atom-protocol/mail-archive/msg01812.html.
+ </t>
+
+ <t>draft-ietf-atompub-protocol-04 -
+ Add ladder diagrams, reorganize, add SOAP interactions
+ </t>
+
+ <t>draft-ietf-atompub-protocol-03 -
+ Incorporates PaceSliceAndDice3 and PaceIntrospection.
+ </t>
+
+
+ <t>draft-ietf-atompub-protocol-02 -
+ Incorporates Pace409Response, PacePostLocationMust,
+ and PaceSimpleResourcePosting.
+ </t>
+
+ <t>draft-ietf-atompub-protocol-01 -
+ Added in sections on Responses for the EditURI.
+ Allow 2xx for response to EditURI PUTs.
+ Elided all mentions of WSSE. Started adding in some
+ normative references. Added the section "Securing the
+ Atom Protocol". Clarified that it is possible that the PostURI and FeedURI
+ could be the same URI. Cleaned up descriptions for Response codes
+ 400 and 500.
+ </t>
+ <t>Rev draft-ietf-atompub-protocol-00 - 5Jul2004 -
+ Renamed the file and re-titled the document to conform
+ to IETF submission guidelines. Changed MIME type to match the one
+ selected for the Atom format. Numerous typographical fixes.
+ We used to have two 'Introduction' sections. One of them was
+ moved into the Abstract the other absorbed the Scope section.
+ IPR and copyright notifications were added.
+ </t>
+ <t>Rev 09 - 10Dec2003 - Added the section on SOAP enabled clients
+ and servers.</t>
+
+ <t>Rev 08 - 01Dec2003 - Refactored the specification, merging the Introspection
+ file into the feed format. Also dropped the distinction between the
+ type of URI used to create new entries and the kind used to create comments.
+ Dropped user preferences.</t>
+
+ <t>Rev 07 - 06Aug2003 - Removed the use of the RSD file for auto-discovery. Changed copyright
+ until a final standards body is chosen. Changed query parameters for the search facet
+ to all begin with atom- to avoid name collisions. Updated all the Entries to follow
+ the 0.2 version. Changed the format of the search results and template file
+ to a pure element based syntax.
+ </t>
+
+ <t>Rev 06 - 24Jul2003 - Moved to PUT for updating Entries.
+ Changed all the mime-types to application/x.atom+xml. Added template
+ editing. Changed 'edit-entry' to 'create-entry' in the Introspection file
+ to more accurately reflect its purpose.
+ </t>
+
+ <t>Rev 05 - 17Jul2003 - Renamed everything Echo into Atom. Added
+ version numbers in the Revision history.
+ Changed all the mime-types to application/atom+xml.
+ </t>
+
+ <t>Rev 04 - 15Jul2003 - Updated the RSD version used from 0.7 to 1.0. Change the method of deleting
+ an Entry from POSTing <delete/> to using the HTTP DELETE verb. Also changed the
+ query interface to GET instead of POST. Moved Introspection Discovery to be up under
+ Introspection. Introduced the term 'facet' for the services listed in the Introspection file.
+ </t>
+
+ <t>Rev 03 - 10Jul2003 - Added a link to the Wiki near the front of the
+ document. Added a section on finding an Entry. Retrieving an Entry
+ now broken out into its own section. Changed the HTTP status code for
+ a successful editing of an Entry to 205.
+ </t>
+
+ <t>Rev 02 - 7Jul2003 - Entries are no longer returned from POSTs, instead they are retrieved via GET.
+ Cleaned up figure titles, as they are rendered poorly in HTML. All content-types
+ have been changed to application/atom+xml.
+ </t>
+
+ <t>Rev 01 - 5Jul2003 - Renamed from EchoAPI.html to follow the more commonly used format:
+ draft-gregorio-NN.html. Renamed all
+ references to URL to URI. Broke out introspection into its own section. Added the Revision History section.
+ Added more to the warning that the example URIs are not normative.
+ </t>
+ </section>
+
+ </back>
+ </rfc>
+
+
+
+
+
+
More information about the Osr-101
mailing list