One document matched: draft-divilly-atompub-hierarchy-00.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- edited with XMLSpy v2007 sp2 (http://www.altova.com) by NIKUNJ R MEHTA (ORACLE) -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc2119 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc3986 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml'>
<!ENTITY rfc5005 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5005.xml'>
<!ENTITY rfc5023 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5023.xml'>
<!ENTITY rfc4287 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4287.xml'>
<!ENTITY W3C.REC-xmlbase-20010627 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-xmlbase-20010627.xml'>
]>
<!--<?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="yes" ?>
<?rfc comments="yes" ?>
<?rfc inline="yes" ?>
<?rfc tocdepth="3" ?>
<rfc category="std" ipr="trust200811" docName="draft-divilly-atompub-hierarchy-00">
<front>
<title>Hierarchy Extensions to Atom Feeds</title>
<author initials="C." surname="Divilly" fullname="Colm Divilly">
<organization>Oracle Corp.</organization>
<address>
<email>colm.divilly@oracle.com</email>
<uri>http://cdivilly.wordpress.com</uri>
</address>
</author>
<author initials="N. R." surname="Mehta" fullname="Nikunj Mehta">
<organization>Oracle Corp.</organization>
<address>
<email>nikunj.mehta@oracle.com</email>
<uri>http://o-micron.blogspot.com/</uri>
</address>
</author>
<date day="5" month="May" year="2009"/>
<abstract>
<t>
This specification defines a mechanism to create and remove
AtomPub collections using the AtomPub protocol as well as
to express hierarchies of feeds within the Atom Syndication
Format.
</t>
</abstract>
<note title="Editorial Note">
<t>
To provide feedback on this Internet-Draft, join the
<eref target="http://www.imc.org/atom-protocol/">atom-protocol mailing
list (http://www.imc.org/atom-protocol/)</eref>.
</t>
</note>
</front>
<middle>
<section anchor="intro" title="Introduction">
<t>
Many applications provide their data in the form of syndicated Web
feeds using formats such as Atom <xref target="RFC4287"/> in order to enable
application integration. Applications may also manipulate the contents of
these data feeds using protocols such as AtomPub <xref target="RFC5023"/>.
</t>
<t>
A key requirement for application data feeds is the ability to
dynamically create new Collections and identify relationships
among such feeds and Collections. This specification defines a
mechanism for identifying hierarchical master-detail relations
among data feeds so that consumer applications can perfrom
standard AtomPub operations on them.
</t>
<t>
A hierarchical master-detail relation of an Entry to a Feed implies
the detail Feed is created when the master Entry is
created and the Feed is removed when the Entry is removed. The Entry is called
the "master entry" and the Feed is called "detail feed". This relationship allows a
client to use AtomPub <xref target="RFC5023"/> to create a new Collection
by posting an Entry to an existing Collection.
</t>
<t>
This specification proposes optional and compatible extensions to
Atom and AtomPub to ease the process of creating and manipulating
collections and feeds based on those collections.
</t>
<section title="Namespace">
<t> The XML Namespaces URI for the XML data format described in this specification is: </t>
<figure width="" align="left" height="" alt="" title="">
<artwork name="" align="left" height="" width="" alt="" type="" xml:space="preserve">
http://purl.org/atom/hierarchy/</artwork>
</figure>
<t> This specification uses the prefix "h:" 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" pageno="false" format="default"/>.
The prefix "app:" is used for "http://www.w3.org/2007/app", the namespace name of
the Atom Publishing Protocol <xref target="RFC5023" pageno="false" format="default"/>.
These namespace prefixes are not semantically significant.
</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>
</section>
<section title="Terminology" anchor="terminology">
<t>
A "detail Feed" is a "logical Feed" as defined in Feed History
and Paging <xref target="RFC5005"/> that does not contain a master Entry.
</t>
<t>
A "master Entry" is an Entry that contains a child Feed.
</t>
<t>
A "child Feed" is a "logical Feed" as defined in Feed History
and Paging <xref target="RFC5005"/> that is contained in a master Entry.
</t>
<t>
A "master Feed" is a "logical Feed" as defined in Feed History
and Paging <xref target="RFC5005"/> that contains only master Entries.
</t>
<t>
This specification also uses Atom link relations to identify
different types of links; see the Atom specification <xref target="RFC4287"/> for
information about their syntax, and the IANA link relation registry
for more information about specific values.
</t>
<t>
Note that URI references in link relation values MAY be relative, and
used in conjunction with the xml:base attribute <xref target="W3C.REC-xmlbase-20010627"/>. Such
a relative URI (or IRI) is resolved as described in Section 5.1 of <xref target="RFC3986"/>.
</t>
</section>
<section title="Protocol Model" anchor="protocol-model">
<t>
Hierarchy extensions to Atom specify operations for creating, updating, and removing
AtomPub Collections using existing AtomPub methods and extensions to Atom syntax.
</t>
<section title="Feed Classification" anchor="feed-classification">
<t>
AtomPub <xref target="RFC5023"/> defines Feed, Entry, and Collection resources in
the Atom syntax <xref target="RFC4287"/>. The hierarchy extensions to
Atom are designed for use with unmodifiable Atom Feeds as well as with
AtomPub Collections.
</t>
<t>
The extensions in this specification define two specialized kinds of Feeds --
master Feed and detail Feed. Both are represented as Atom Feed Documents
<xref target="RFC4287"/>.
</t>
<figure>
<artwork name="Resource Classification"
type="example"><![CDATA[
logical Feed
|
-------------------------------
| | |
detail Feed master Feed Feed
| | |
Entry master Entry master Entry
... ... ...
Entry master Entry Entry
]]></artwork>
</figure>
<t>
A master Feed is a container for master Entires. Each master
Entry contains a child Feed, which can be any logical Feed. The kind
child Feed's metadata identifies the kind of new Entries that it can
accept. The child Feed is created when the master Entry is created
and the child Feed is removed when the master Entry is removed.
A master Feed MAY itself be a child of another master Feed.
</t>
<figure>
<preamble>
A master Feed can only accept a new master Entry.
Each of its Entry contains a "detail" atom:link for a logical Feed.
</preamble>
<artwork name="Master feed contents"><![CDATA[
atom:feed
|
o- atom:link@rel="next" (0..1)
o- atom:link@rel="prev" (0..1)
o- atom:link@rel="first" (0..1)
o- atom:link@rel="last" (0..1)
o- atom:link@rel="self" (1..1)
o- atom:link@rel="master" (0..1)
o- app:collection (1..1)
| |
| o- app:accept@h:role="master" (1..1)
|
o- atom:entry (0..n)
|
o- atom:link@rel="self" (1..1)
o- atom:link@rel="edit" (1..1)
o- atom:link@rel="detail" (1..1)
]]></artwork>
</figure>
<t>
A detail Feed MUST be a child of a master Entry.
</t>
<figure>
<preamble>
A detail Feed can only accept a new detail Entry. It provides
an atom:link back to its "master" Entry. None of its Entries
contain a "detail" atom:link.
</preamble>
<artwork name="Detail feed contents"><![CDATA[
atom:feed
|
o- atom:link@rel="next" (0..1)
o- atom:link@rel="prev" (0..1)
o- atom:link@rel="first" (0..1)
o- atom:link@rel="last" (0..1)
o- atom:link@rel="master" (1..1)
o- atom:link@rel="self" (1..1)
o- app:collection (1..1)
| |
| o- app:accept@h:role="detail" (1..1)
|
o- atom:entry (0..n)
|
o- atom:link@rel="self" (1..1)
o- atom:link@rel="edit" (1..1)
]]></artwork>
</figure>
</section>
<section title="Protocol Operations" anchor="protocol-operations">
<t>
AtomPub protocol governs the server behavior for operations involving
master-detail feeds. This section illustrates how additional behavior
results from the semantics of master-detail relations among feeds.
</t>
<t>
No special importance should be attached to the status codes shown
in the illustrations below, and a server is entitled to using any HTTP
status code that adequately represents the result of the requested
operation.
</t>
<section title="Creating a Collection">
<figure>
<artwork><![CDATA[
Client Server
| |
| 1.) POST to master Collection URI |
|-------------------------------------->|
| |
| 2.) 201 Created |
| Master Entry Document |
|<--------------------------------------|
| |
]]></artwork>
</figure>
<t>
<list style="numbers">
<t>
The client sends a POST request containing an Atom Entry
to the URI of the master Collection.
</t>
<t>
The server responds with an Atom Entry Document containing
the IRIs of the newly created master Entry and the child Feed.
</t>
</list>
</t>
</section>
<section title="Editing a Master Entry">
<figure>
<artwork><![CDATA[
Client Server
| |
| 1.) PUT to master Entry URI |
| Master Entry Document |
|-------------------------------------->|
| |
| 2.) 200 OK |
| Master Entry Document |
|<--------------------------------------|
| |
]]></artwork>
</figure>
<t>
<list style="numbers">
<t>
The client sends a PUT request containing an Atom Entry
to the URI of the master Entry.
</t>
<t>
If the request is successful, the server responds with a
200 status code without removing the child Feed from
the master Entry Document.
</t>
</list>
</t>
</section>
<section title="Removing a Master Entry">
<figure>
<artwork><![CDATA[
Client Server
| |
| 1.) DELETE to master Entry URI |
|-------------------------------------->|
| |
| 2.) 204 No Content |
|<--------------------------------------|
| |
]]></artwork>
</figure>
<t>
<list style="numbers">
<t>
The client sends a DELETE request
to the URI of the master Entry.
</t>
<t>
If the request is successful, the server responds with a
204 status code and removes the master Entry and detail Feed.
Future requests to the URI of the master Entry or the child
Feed or any of its entries MAY produce responses with
410 Gone status code.
</t>
</list>
</t>
</section>
</section>
</section>
<section title="Backing Collection" anchor="backing-collection">
<t>
Often applications need to advertise that a Feed is modifiable, or in other words that
new entries can be added to a Feed. If a syndicated feed document is backed by an
AtomPub Collection resource, then clients may be able to augment the Feed by
interacting with its backing Collection.
</t>
<t>
Section 8.3.5 of <xref target="RFC5023"/> specifies the semantics of an app:collection
element appearing as a child of atom:feed element. Along those lines, if a Feed is
backed by a Collection, the server SHOULD identify the backing Collection
using the app:collection element as a child of the atom:feed element.
</t>
<t>If the href attribute of this app:collection element is identical to that of the
parent atom:feed element's self link relation, then the client SHOULD treat
the feed to be the Collection feed.
</t>
<figure>
<preamble>Example: Writable Collection backing a Feed</preamble>
<artwork name="Collection backing a feed" type="example"><![CDATA[
<atom:feed>
<atom:link rel="self" href="http://example.org/feed"/>
<app:collection href="http://example.org/collection">
<atom:title type="text">Writable Feed</atom:title>
<app:accept>application/atom+xml;type=entry</app:accept>
</app:collection>
...
</atom:feed>
]]></artwork>
</figure>
<figure>
<preamble>
Example: Read-only Collection backing a Feed
</preamble>
<artwork name="Collection backing a feed" type="example"><![CDATA[
<atom:feed>
<atom:link rel="self" href="http://example.org/feed"/>
<app:collection href="http://example.org/collection">
<atom:title type="text">Read-only Feed</atom:title>
<app:accept/>
</app:collection>
...
</atom:feed>
]]></artwork>
</figure>
<figure>
<preamble>
Example: Writable Collection Feed
</preamble>
<artwork name="Collection feed" type="example"><![CDATA[
<atom:feed>
<atom:link rel="self" href="http://example.org/collection"/>
<app:collection href="http://example.org/collection">
<atom:title type="text">Collection Feed</atom:title>
</app:collection>
...
</atom:feed>
]]></artwork>
</figure>
</section>
<section title="Master Detail Relations" anchor="master-detail-feeds">
<t>
Master detail relations among entries and feeds are indicated using
link relations.
</t>
<section title="Child feeds" anchor="child-feeds">
<t>
Every master Entry has a child Feed and vice versa. The
contents of a child Feed can be supplied in the following ways:
<list style="numbers">
<t>
Out-of-line reference: The client can retrieve the child Feed by
following a URL specified in the master Entry. This URL is specified
via an atom:link element as detailed below.
</t>
<t>
Inline content with out-of-line reference: The client can use the
embedded content and expect the server to provide the same feed
document at the URL referenced in the master Entry. The server MAY
embed the atom:feed directly inside the atom:link element in the
master entry document, in which case the client MAY safely use
the embedded feed document as the representation of the child Feed.
</t>
</list>
</t>
<section title="The "detail" Link" anchor="detail-link">
<t>
Master Entries identify the URLs of their child Feed in their own metadata.
A master entry MUST contain an atom:link element with link relation of
"detail" to indicate the child Feed URL. The type attribute of this link
element (if present), MUST be the Atom Feed content type, i.e.,
application/atom+xml;type=feed.
</t>
</section>
<section title="The "h:count" Extension Attribute" anchor="count-attribute">
<t>
A master Entry MAY include an optional h:count attribute with a positive
integral value identifying an approximate count of the number of entries in
the detail Feed.
</t>
</section>
<section title="Example" anchor="detail-examples">
<figure>
<preamble>
Example: Entry with out-of-line reference to child Feed
</preamble>
<artwork name="Out-of-line detail feed" type="example"><![CDATA[
<atom:entry>
<atom:title type="text">My Portfolio</atom:title>
<atom:link rel="detail" h:count="4"
href="/finance/feeds/default/portfolios/1/positions"/>
<atom:link rel="edit"
href="/finance/feeds/default/portfolios/1"/>
...
</atom:entry>
]]></artwork>
</figure>
<figure>
<preamble>
Example: Entry with inline child Feed
</preamble>
<artwork name="Inline detail feed" type="example"><![CDATA[
<atom:entry>
<atom:link rel="detail"
href="/finance/feeds/default/portfolios/1/positions">
<atom:feed>
<atom:link rel="master"
href="/finance/feeds/default/portfolios/1"/>
<app:collection href="/finance/feeds/default/portfolios/1/
positions">
<atom:title>Oracle Corp</atom:title>
</app:collection>
<atom:link rel="self"
href="/finance/feeds/default/portfolios/1/positions">
...
</atom:feed>
</atom:link>
<atom:link rel="edit"
href="/finance/feeds/default/portfolios/1"/>
...
</atom:entry>
]]></artwork>
</figure>
</section>
</section>
<section title="Master entries" anchor="master-entries">
<t>
The contents of a master Entry can be supplied in the following ways:
<list style="numbers">
<t>
Out-of-line reference: The client can retrieve the master Entry by
following a URL specified in the child Feed. This URL is specified
via an atom:link element as detailed below.
</t>
<t>
Inline content with out-of-line reference: The client can use the
embedded content and expect the server to provide the same entry
document at the URL referenced in the child Feed. The server MAY
embed the atom:entry directly inside the atom:link element in the
child feed document, in which case the client MAY safely use
the embedded entry document as the representation of the master Entry.
</t>
</list>
</t>
<section title="The "master" Link" anchor="master-link">
<t>
Child Feeds identify the URLs of their master Entry in their own metadata.
A detail Feed MUST contain an atom:link element with link relation of
"master" to indicate the master Entry URL. The type attribute of this link
element (if present), MUST be the Atom Entry content type, i.e.,
application/atom+xml;type=entry.
</t>
</section>
<section title="Example" anchor="master-examples">
<figure>
<preamble>
Example: Feed with out-of-line reference to master Entry
</preamble>
<artwork name="Out-of-line detail feed" type="example"><![CDATA[
<atom:feed>
<atom:title type="text">Positions</atom:title>
<atom:link rel="master"
href="/finance/feeds/default/portfolios/1"/>
<atom:link rel="self"
href="/finance/feeds/default/portfolios/1/positions"/>
...
</atom:feed>
]]></artwork>
</figure>
<figure>
<preamble>
Example: Feed with inline master Entry
</preamble>
<artwork name="Inline detail feed" type="example"><![CDATA[
<atom:feed>
<atom:title type="text">Positions</atom:title>
<atom:link rel="master"
href="/finance/feeds/default/portfolios/1"/>
<atom:entry>
<atom:link rel="detail"
href="/finance/feeds/default/portfolios/1/positions"/>
<atom:link rel="edit"
href="/finance/feeds/default/portfolios/1">
...
</atom:entry>
</atom:link>
<atom:link rel="self"
href="/finance/feeds/default/portfolios/1/positions"/>
...
</atom:feed>
]]></artwork>
</figure>
</section>
</section>
</section>
<section title="The 'h:role' Extension Attribute" anchor="h-role">
<t>
This specification defines additional metadata for AtomPub Service documents and
collection-backed Feed documents for the purpose of identifying master and detail feeds.
</t>
<t>
The "h:role" attribute MAY be added to the app:accept element of an
app:collection declaration. When present, the value MUST be one of
"master" or "detail". If the "h:role" attribute is present then the
content type of the accept element MUST be "application/atom+xml;type=entry".
</t>
<figure>
<artwork name="Syntax for hierarchy type" type="example"><![CDATA[
hierarchyType =
attribute h:role { "master" | "detail" }
]]></artwork>
</figure>
<section title="The 'master' role" anchor="type-master">
<t>
If the "h:role" value is "master" then POSTing an Atom entry
document to that collection MUST cause the server to do both of the
following:
<list style="symbols">
<t>
create a new Atom Entry resource whose location is provided as
defined in Section 9.2.1 of <xref target="RFC5023"/>
</t>
<t>
create a new AtomPub Collection resource whose location is
provided in the master entry document
</t>
</list>
</t>
<figure>
<preamble>
Example: Hierarchy metadata for collections
</preamble>
<artwork name="Hierarchy metadata for collections" type="example"><![CDATA[
<app:collection href="http://example.org/collection">
<title type="text">Master Feed</title>
<app:accept
h:role="master">application/atom+xml;type=entry
</app:accept>
</app:collection>
]]></artwork>
</figure>
<figure>
<preamble>
A POST to that collection would be as per <xref target="RFC5023"/>:
</preamble>
<artwork name="Posting a master feed" type="example"><![CDATA[
POST /collection HTTP/1.1
Host: example.org
Content-Type: application/atom+xml;type=entry
Content-Length: nnn
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>A master entry</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-8003ffefa6a</id>
<updated>2003-12-13T18:30:02Z</updated>
<author><name>John Doe</name></author>
<content>Some text.</content>
</entry>
]]></artwork>
</figure>
<figure>
<preamble>
The server produces the following response:
</preamble>
<artwork name="Posting a master feed, Server Response" type="example"><![CDATA[
201 Created
Location: http://example.org/collection/master1
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:h="http://purl.org/atom/hierarchy/">
<title>A master entry</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-8003ffefa6a</id>
<updated>2003-12-13T18:30:02Z</updated>
<author><name>John Doe</name></author>
<content>Some text.</content>
<link rel="self" href="/collection/master1"/>
<link rel="edit" href="/collection/master1"/>
<link rel="detail" h:count="0"
href="/collection/master1/collection">
<feed xmlns:app="http://www.w3.org/2007/app">
<id>urn:uuid:1225c695-cfb8-4ebb-a33a-8003ffefa6a</id>
<app:collection href="/collection/master1/collection">
<app:accept h:role="detail">
application/atom+xml;type=entry
</app:accept>
</app:collection>
<link rel="self" href=""/collection/master1/collection"/>
</feed>
</link>
</entry>
]]></artwork>
</figure>
</section>
<section title="The 'detail' role" anchor="type-detail">
<t>
If the "h:role" value is "detail" then the server behaves as specified
in Section 9.2.1 of <xref target="RFC5023"/> when a client POSTs an Atom entry
document to the Collection.
</t>
</section>
</section>
<section title="Working With Master-Detail Feeds" anchor="examples">
<section title="Retrieving Master Feeds" anchor="fetch-master">
<figure>
<preamble>
Below is a feed for a finance portfolio tracker application.
Each user has a Collection of portfolios.
Each portfolio is a Collection of positions.
</preamble>
<artwork name="Portfolio Feed" type="example"><![CDATA[
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:app='http://www.w3.org/2007/app'
xmlns:h='http://purl.org/atom/hierarchy#'
xmlns:f='http://example.com/finance'
xml:base='http://example.com'>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344cba6a</id>
<updated>2008-10-01T13:05:30.000Z</updated>
<title type='text'>Portfolio Feed</title>
<link rel='service'
href='/finance/feeds/default/service'/>
<app:collection href='/finance/feeds/default/portfolios'>
<title type='text'>Portfolio Feed</title>
<app:accept h:role='container'>application/atom+xml</app:accept>
</app:collection>
<entry>
<id>urn:uuid:1225c695-cfb8-4ebb-aada-80da344efa6a</id>
<updated>2008-06-10T01:29:49.000Z</updated>
<title type='text'>My Portfolio</title>
<link rel='detail'
type='application/atom+xml;type=feed' title='positions'
href='/finance/feeds/default/portfolios/1/positions'/>
<link rel='edit'
href='/finance/feeds/default/portfolios/1'/>
<summary>Default portfolio</summary>
<f:portfolioData currencyCode='USD' gainPercentage='0.0'
return1w='0.0' return1y='0.0' return3m='0.0' return3y='0.0'
return4w='0.0' return5y='0.0' returnOverall='0.0' returnYTD='0.0'/>
</entry>
</feed>
]]></artwork>
</figure>
</section>
<section title="Creating A Master Entry">
<figure>
<preamble>
If a user wishes to add a new portfolio, they can do so by making an AtomPub
POST request to the portofolio Collection identified above in the
app:collection element of the master portfolio feed:
</preamble>
<artwork name="Create Portfolio" type="example"><![CDATA[
POST /finance/feeds/default/portfolios HTTP/1.1
Host: example.com
Content-Type: application/atom+xml; type=entry
Content-Length: nnn
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:f='http://example.com/finance'>
<id/>
<updated>2008-06-10T23:38:01.000Z</updated>
<title type='text'>Hanky Panky</title>
<f:portfolioData currency='USD'/>
</entry>
]]></artwork>
</figure>
<figure>
<preamble>
The server generates the following response after creating the master entry
and the detail feed.
</preamble>
<artwork name="Server Response" type="example"><![CDATA[
201 Created
Location: /finance/feeds/default/portfolios/2
Content-Type: application/atom+xml; type=entry
Content-Length: nnn
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:f='http://example.com/finance'
xml:base='http://example.com'>
<id>urn:uuid:1225c695-cfb8-4ebb-aada-80da344efa6a</id>
<updated>2008-06-10T23:38:01.000Z</updated>
<title type='text'>Hanky Panky</title>
<link rel='detail'
type='application/atom+xml;type=feed' title='positions'
href='/finance/feeds/default/portfolios/2/positions'/>
<link rel='detail'
type='text/html'
href='http://finance.example.com/portfolio/2'/>
<link rel='edit'
href='/finance/feeds/default/portfolios/2'/>
<summary>Default portfolio</summary>
<f:portfolioData currencyCode='USD' gainPercentage='0.0'
return1w='0.0' return1y='0.0' return3m='0.0' return3y='0.0'
return4w='0.0' return5y='0.0' returnOverall='0.0' returnYTD='0.0'/>
</entry>]]></artwork>
</figure>
<t>
This entry identifies a newly created Holdings Collection in
the link with the "detail" relation.
</t>
</section>
<section title="Creating A Detail Entry">
<figure>
<preamble>
If a user wishes to add a new position, they can do so by making an AtomPub
POST request to the portfolio's Collection identified above in the
app:collection element of the detail positions feed:
</preamble>
<artwork name="Create Holding" type="example"><![CDATA[
POST /finance/feeds/default/portfolios1/positions HTTP/1.1
Host: example.com
Content-Type: application/atom+xml; type=entry
Content-Length: nnn
<entry xmlns='http://www.w3.org/2005/Atom'>
<symbol xmlns='http://api.example.com/finance'
exchange='NASDAQ' fullName='Siebel Systems' symbol='SEBL'/>
</entry>
]]></artwork>
</figure>
<figure>
<preamble>
The server generates the following response after creating the detail entry.
</preamble>
<artwork name="Server Response" type="example"><![CDATA[
201 Created
Location: /finance/feeds/default/portfolios/1/positions/NASD:SEBL
Content-Type: application/atom+xml; type=entry
Content-Length: nnn
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:f='http://api.example.com/finance'>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa9b</id>
<updated>2008-10-01T23:28:01.000Z</updated>
<category scheme='http://api.example.com/cat/2008#kind'
term='http://api.example.com/finance/2008#position'/>
<title type='text'>Siebel Systems</title>
<link rel='edit'
href='/finance/feeds/default/portfolios/1/positions/NASD:SEBL'/>
<f:portfolioData currencyCode='USD' gainPercentage='0.0'
return1w='0.0' return1y='0.0' return3m='0.0' return3y='0.0'
return4w='0.0' return5y='0.0' returnOverall='0.0' returnYTD='0.0'/>
<f:symbol exchange='NASDAQ' fullName='Google Inc'
symbol='SEBL'/>
</entry>]]></artwork>
</figure>
<t>
This entry identifies a newly created SEBL position.
</t>
</section>
</section>
<section title="Security Considerations">
<t>
Atom Publishing Protocol Hierarchy Extensions is subject to the
security considerations found in Section 8 of <xref target="RFC4287"/> and Section 15 of <xref target="RFC5023"/>.
</t>
</section>
<section title="IANA Considerations" anchor="iana">
<t>
This specification defines the following new relations that have been
added to the Link Relations registry:
<list style="symbols">
<t>Attribute Value: detail</t>
<t>Description: A URI that refers to the child feed for a master entry.</t>
<t>Expected display characteristics: none</t>
<t>Security considerations: See this draft</t>
</list>
<list style="symbols">
<t>Attribute Value: master</t>
<t>Description: A URI that refers to the master entry for a child feed.</t>
<t>Expected display characteristics: none</t>
<t>Security considerations: See this draft</t>
</list>
</t>
</section>
</middle>
<back>
<references title="Normative References">
&rfc2119;
&rfc3986;
&rfc5023;
&rfc5005;
&rfc4287;
&W3C.REC-xmlbase-20010627;
</references>
<section title="Acknowledgements">
<t>
Bill de hÓra and Ashish Motivala reviewed early drafts of this I-D and helped
strengthen the text and make it easier to read.
</t>
</section>
<section title="Revision History">
<t>
00 - Initial Revision.
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 12:07:34 |