| draft-nottingham-atompub-feed-history-07.txt |  | draft-nottingham-atompub-feed-history-08.txt |
--- | --- | --- | --- | ---
| Network Working Group M. Nottingham |  | Network Working Group M. Nottingham |
| Intended status: Standards Track |  | Intended status: Standards Track |
| Expires: March 16, 2007 |  | Expires: May 26, 2007 |
| Feed Paging and Archiving |  | Feed Paging and Archiving |
| draft-nottingham-atompub-feed-history-07 |  | draft-nottingham-atompub-feed-history-08 |
| Status of This Memo |  | Status of This Memo |
| By submitting this Internet-Draft, each author represents that any |  | By submitting this Internet-Draft, each author represents that any |
| applicable patent or other IPR claims of which he or she is aware |  | applicable patent or other IPR claims of which he or she is aware |
| have been or will be disclosed, and any of which he or she becomes |  | have been or will be disclosed, and any of which he or she becomes |
| aware will be disclosed, in accordance with Section 6 of BCP 79. |  | aware will be disclosed, in accordance with Section 6 of BCP 79. |
| Internet-Drafts are working documents of the Internet Engineering |  | Internet-Drafts are working documents of the Internet Engineering |
| Task Force (IETF), its areas, and its working groups. Note that |  | Task Force (IETF), its areas, and its working groups. Note that |
| skipping to change at page 1, line 34 |  | skipping to change at page 1, line 34 |
| and may be updated, replaced, or obsoleted by other documents at any |  | and may be updated, replaced, or obsoleted by other documents at any |
| time. It is inappropriate to use Internet-Drafts as reference |  | time. It is inappropriate to use Internet-Drafts as reference |
| material or to cite them other than as "work in progress." |  | material or to cite them other than as "work in progress." |
| The list of current Internet-Drafts can be accessed at |  | The list of current Internet-Drafts can be accessed at |
| http://www.ietf.org/ietf/1id-abstracts.txt. |  | http://www.ietf.org/ietf/1id-abstracts.txt. |
| The list of Internet-Draft Shadow Directories can be accessed at |  | The list of Internet-Draft Shadow Directories can be accessed at |
| http://www.ietf.org/shadow.html. |  | http://www.ietf.org/shadow.html. |
| This Internet-Draft will expire on March 16, 2007. |  | This Internet-Draft will expire on May 26, 2007. |
| Copyright Notice |  | Copyright Notice |
| Copyright (C) The Internet Society (2006). |  | Copyright (C) The Internet Society (2006). |
| Abstract |  | Abstract |
| This specification defines three types of syndicated feeds that |  | This specification defines three types of syndicated Web feeds that |
| enable publication of entries across one or more feed documents. |  | enable publication of entries across one or more feed documents. |
| Table of Contents |  | Table of Contents |
| 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 |  | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 |
| 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 |  | 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 |
| 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 |  | 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 |
| 2. Complete Feeds . . . . . . . . . . . . . . . . . . . . . . . . 4 |  | 2. Complete Feeds . . . . . . . . . . . . . . . . . . . . . . . . 4 |
| 2.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 5 |  | 3. Paged Feeds . . . . . . . . . . . . . . . . . . . . . . . . . 5 |
| 3. Paged Feeds . . . . . . . . . . . . . . . . . . . . . . . . . 6 |  | 4. Archived Feeds . . . . . . . . . . . . . . . . . . . . . . . . 6 |
| 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 7 |  | 4.1. Publishing Archived Feeds . . . . . . . . . . . . . . . . 9 |
| 4. Archived Feeds . . . . . . . . . . . . . . . . . . . . . . . . 8 |  | 4.2. Consuming Archived Feeds . . . . . . . . . . . . . . . . . 9 |
| 4.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 10 |  | 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 |
| 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 |  | 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 |
| 6. Security Considerations . . . . . . . . . . . . . . . . . . . 14 |  | 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 |
| 7. Normative References . . . . . . . . . . . . . . . . . . . . . 14 |  | 7.1. Normative References . . . . . . . . . . . . . . . . . . . 10 |
| Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15 |  | 7.2. Informative References . . . . . . . . . . . . . . . . . . 11 |
| Appendix B. Reconstructing Archived Feeds . . . . . . . . . . . . 15 |  | Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 |
|  |  | Appendix B. Use in RSS 2.0 . . . . . . . . . . . . . . . . . . . 11 |
| 1. Introduction |  | 1. Introduction |
| Syndicated Web feeds (using such formats as Atom [RFC4287] or RSS |  | Syndicated Web feeds (using such formats as Atom [RFC4287]) are often |
| 2.0) are often split up into multiple documents to save bandwidth, |  | split up into multiple documents to save bandwidth, allow "sliding |
| allow "sliding window" access, or for other purposes. |  | window" access, or for other purposes. |
| This specification formalizes two types of feeds that can span one or |  | This specification formalizes two types of feeds that can span one or |
| more feed documents; "paged" feeds and "archived" feeds. |  | more feed documents; "paged" feeds and "archived" feeds. |
| Additionally, it defines "complete" feeds to cover the case when a |  | Additionally, it defines "complete" feeds to cover the case when a |
| single feed document explicitly represents all of the feed's entries. |  | single feed document explicitly represents all of the feed's entries. |
| These types are complementary; each has different properties and |  | Each has different properties and trade-offs: |
| trade-offs: |  |  |
| o Complete feeds contain the entire set of entries in one document, |  | o Complete feeds contain the entire set of entries in one document, |
| and can be useful when it isn't desirable to "remember" |  | and can be useful when it isn't desirable to "remember" |
| previously-seen entries. |  | previously-seen entries. |
| o Paged feeds split the logical feed's entries among multiple |  | o Paged feeds split the logical feed's entries among multiple |
| temporary documents. This can be useful when entries in the feed |  | temporary documents. This can be useful when entries in the feed |
| are not long-lived or stable, and the client needs to access an |  | are not long-lived or stable, and the client needs to access an |
| arbitrary portion of them, usually in close succession. |  | arbitrary portion of them, usually in close succession. |
| o Archived feeds split them among multiple permanent documents, and |  | o Archived feeds split them among multiple permanent documents, and |
| can be useful when entries are long-lived and it is important for |  | can be useful when entries are long-lived and it is important for |
| clients to see every one. |  | clients to see every one. |
|  |  | The semantics of a feed that combines these types is undefined by |
|  |  | this specification. |
| Although they refer to Atom normatively, the mechanisms described |  | Although they refer to Atom normatively, the mechanisms described |
| herein can be used with similar syndication formats, such as the |  | herein can be used with similar syndication formats; see Appendix B |
| various flavors of RSS. |  | for one such use. |
| 1.1. Notational Conventions |  | 1.1. Notational Conventions |
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", |  | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", |
| "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this |  | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this |
| document are to be interpreted as described in BCP 14 [RFC2119], as |  | document are to be interpreted as described in BCP 14 [RFC2119]. |
| scoped to those conformance targets. |  |  |
| This specification uses XML Namespaces [W3C.REC-xml-names-19990114] |  | This specification uses XML Namespaces [W3C.REC-xml-names-19990114] |
| to uniquely identify XML element names. It uses the following |  | to uniquely identify XML element names. It uses the following |
| namespace prefix for the indicated namespace URI; |  | namespace prefix for the indicated namespace URI; |
| "fh": "http://purl.org/syndication/history/1.0" |  | "fh": "http://purl.org/syndication/history/1.0" |
| 1.2. Terminology |  | 1.2. Terminology |
| In this specification, "feed document" refers to an Atom Feed |  | In this specification, "feed document" refers to an Atom Feed |
| Document, RSS document, or similar syndication instance document. It |  | Document or similar syndication instance document. It may contain |
| may contain any number of entries (in RSS, items), and may or may not |  | any number of entries, and may or may not be a complete |
| be a complete representation of the logical feed. |  | representation of the logical feed. |
| A "logical feed" is the set of entries associated with a particular |  | A "logical feed" is the set of entries associated with a particular |
| feed (as contrasted with a feed document, which may contain a subset |  | feed (as contrasted with a feed document, which may contain a subset |
| of them). |  | of them). |
| "Head section" refers to the children of a feed document's document- |  | "Head section" refers to a document's feed-wide metadata container; |
| wide metadata container; e.g., the child elements of the atom:feed |  | e.g., the child elements of the atom:feed element in an Atom Feed |
| element in an Atom Feed Document. |  | Document. |
| This specification uses terms from the XML Infoset |  | This specification uses terms from the XML Infoset |
| [W3C.REC-xml-infoset-20040204]. However, this specification uses a |  | [W3C.REC-xml-infoset-20040204]. However, this specification uses a |
| shorthand; the phrase "Information Item" is omitted when naming |  | shorthand; the phrase "Information Item" is omitted when naming |
| Element Information Items. Therefore, when this specification uses |  | Element Information Items. Therefore, when this specification uses |
| the term "element," it is referring to an Element Information Item in |  | the term "element," it is referring to an Element Information Item in |
| Infoset terms. |  | Infoset terms. |
| This specification also uses Atom link relations to identify |  | This specification also uses Atom link relations to identify |
| different types of links; see the Atom specification [RFC4287] for |  | different types of links; see the Atom specification [RFC4287] for |
| information about their syntax, and the IANA link relation registry |  | information about their syntax, and the IANA link relation registry |
| for more information about specific values. |  | for more information about specific values. |
|  |  | Note that URI references in link relation values may be relative, and |
|  |  | when they are used they must be absolutised, as described in Section |
|  |  | 5.1 of [RFC3986]. |
| 2. Complete Feeds |  | 2. Complete Feeds |
| A complete feed is a feed document that contains all of the entries |  | A complete feed is a feed document that contains all of the entries |
| of a logical feed; any entry not actually in the feed document SHOULD |  | of a logical feed; any entry not actually in the feed document SHOULD |
| NOT be considered to be part of that feed. |  | NOT be considered to be part of that feed. |
| For example; a feed that represents a ranking that varies over time, |  | For example, a feed that represents a ranking that varies over time |
| such as "Top Twenty Records" or "Most Popular Items" should not have |  | (such as "Top Twenty Records" or "Most Popular Items") should not |
| newer entries displayed alongside older ones. By marking them as |  | have newer entries displayed alongside older ones. By marking this |
| complete feeds, old entries are discarded when the feed is refreshed. |  | type feeds as complete, old entries are discarded when it is |
|  |  | refreshed. |
| The fh:complete element, when present in a feed's head section, |  | The fh:complete element, when present in a feed's head section, |
| indicates that the feed document it occurs in is a complete |  | indicates that the feed document it occurs in is a complete |
| representation of the logical feed's entries. |  | representation of the logical feed's entries. It is an empty |
|  |  | element; this specification does not define any content for it. |
| For example, |  |  |
| <fh:complete/> |  |  |
| 2.1. Examples |  |  |
| Atom-formatted Complete Feed |  | Example: Atom-formatted Complete Feed |
| <?xml version="1.0" encoding="utf-8"?> |  | <?xml version="1.0" encoding="utf-8"?> |
| <feed xmlns="http://www.w3.org/2005/Atom" |  | <feed xmlns="http://www.w3.org/2005/Atom" |
| xmlns:fh="http://purl.org/syndication/history/1.0"> |  | xmlns:fh="http://purl.org/syndication/history/1.0"> |
| <title>NetMovies Queue</title> |  | <title>NetMovies Queue</title> |
| <description>The DVDs you'll receive next.</description> |  | <description>The DVDs you'll receive next.</description> |
| <link href="http://example.org/"/> |  | <link href="http://example.org/"/> |
| <fh:complete/> |  | <fh:complete/> |
| <link rel="self" |  | <link rel="self" |
| href="http://netmovies.example.org/jdoe/queue/index.atom"/> |  | href="http://netmovies.example.org/jdoe/queue/index.atom"/> |
| skipping to change at page 6, line 4 |  | skipping to change at page 5, line 29 |
| </author> |  | </author> |
| <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id> |  | <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id> |
| <entry> |  | <entry> |
| <title>Casablanca</title> |  | <title>Casablanca</title> |
| <link href="http://netmovies.example.org/movies/Casablanca"/> |  | <link href="http://netmovies.example.org/movies/Casablanca"/> |
| <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> |  | <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> |
| <updated>2003-12-13T18:30:02Z</updated> |  | <updated>2003-12-13T18:30:02Z</updated> |
| <summary>Here's looking at you, kid...</summary> |  | <summary>Here's looking at you, kid...</summary> |
| </entry> |  | </entry> |
| </feed> |  | </feed> |
| RSS 2.0-formatted Complete Feed |  |  |
| <?xml version="1.0"?> |  | This specification does not address duplicate entries in complete |
| <rss version="2.0" |  | feeds. |
| xmlns:fh="http://purl.org/syndication/history/1.0"> |  |  |
| <channel> |  |  |
| <title>NetMovies Queue</title> |  |  |
| <link>http://netmovies.example.org/</link> |  |  |
| <description>The DVDs you'll receive next.</description> |  |  |
| <language>en-us</language> |  |  |
| <pubDate>Tue, 10 Jun 2003 04:00:00 GMT</pubDate> |  |  |
| <lastBuildDate>Tue, 10 Jun 2003 09:41:01 GMT</lastBuildDate> |  |  |
| <docs>http://blogs.law.harvard.edu/tech/rss</docs> |  |  |
| <generator>Weblog Editor 2.0</generator> |  |  |
| <managingEditor>editor@netmovies.example.org</managingEditor> |  |  |
| <webMaster>webmaster@netmovies.example.org</webMaster> |  |  |
| <fh:complete/> |  |  |
| <item> |  |  |
| <title>Casablanca</title> |  |  |
| <link>http://netmovies.example.org/movies/Casablanca</link> |  |  |
| <description>Here's looking at you, kid... |  |  |
| </description> |  |  |
| <pubDate>Tue, 03 Jun 2003 09:39:21 GMT</pubDate> |  |  |
| <guid>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</guid> |  |  |
| </item> |  |  |
| </channel> |  |  |
| </rss> |  |  |
| 3. Paged Feeds |  | 3. Paged Feeds |
| A paged feed is a set of linked feed documents that together contain |  | A paged feed is a set of linked feed documents that together contain |
| the entries of a logical feed, without any guarantees about the |  | the entries of a logical feed, without any guarantees about the |
| stability of the documents' contents. |  | stability of the documents' contents. |
| Paged feeds are lossy; that is, it is not possible to guarantee that |  | Paged feeds are lossy; that is, it is not possible to guarantee that |
| clients will be able to reconstruct the contents of the logical feed |  | clients will be able to reconstruct the contents of the logical feed |
| at a particular time. Some entries may be added or changed as the |  | at a particular time. Entries may be added or changed as the pages |
| pages of the feed are accessed, without the client becoming aware of |  | of the feed are accessed, without the client becoming aware of them. |
| them. |  |  |
|  |  | Therefore, clients SHOULD NOT present paged feeds as coherent or |
|  |  | complete, or make assumptions to that effect. |
| Paged feeds can be useful when the number of entries is very large, |  | Paged feeds can be useful when the number of entries is very large, |
| infinite, or indeterminate. Clients can "page" through the feed, |  | infinite, or indeterminate. Clients can "page" through the feed, |
| only accessing a subset of the feed's entries as necessary. |  | only accessing a subset of the feed's entries as necessary. |
| For example, a search engine might make query results available as a |  | For example, a search engine might make query results available as a |
| paged feed, so that queries with very large result sets do not |  | paged feed, so that queries with very large result sets do not |
| overwhelm the server, the network, or the client. |  | overwhelm the server, the network, or the client. |
| The feed documents in a paged feed are tied together with the |  | The feed documents in a paged feed are tied together with the |
| skipping to change at page 7, line 18 |  | skipping to change at page 6, line 19 |
| o "first" - A URI that refers to the furthest preceding document in |  | o "first" - A URI that refers to the furthest preceding document in |
| a series of documents. |  | a series of documents. |
| o "last" - A URI that refers to the furthest following document in a |  | o "last" - A URI that refers to the furthest following document in a |
| series of documents. |  | series of documents. |
| o "previous" - A URI that refers to the immediately preceding |  | o "previous" - A URI that refers to the immediately preceding |
| document in a series of documents. |  | document in a series of documents. |
| o "next" - A URI that refers to the immediately following document |  | o "next" - A URI that refers to the immediately following document |
| in a series of documents. |  | in a series of documents. |
| Paged feed documents MUST have at least one of these link relations |  | Paged feed documents MUST have at least one of these link relations |
| present, and SHOULD contain as many as practical and applicable. |  | present, and should contain as many as practical and applicable. |
| Note that URI references in link relation values may be relative, and |  |  |
| when they are used they must be absolutised, as described in Section |  |  |
| 5.1 of [RFC3986]. |  |  |
| 3.1. Examples |  |  |
| Atom-formatted Paged Feed |  | Example: Atom-formatted Paged Feed |
| <?xml version="1.0" encoding="utf-8"?> |  | <?xml version="1.0" encoding="utf-8"?> |
| <feed xmlns="http://www.w3.org/2005/Atom"> |  | <feed xmlns="http://www.w3.org/2005/Atom"> |
| <title>Example Feed</title> |  | <title>Example Feed</title> |
| <link href="http://example.org/"/> |  | <link href="http://example.org/"/> |
| <link rel="self" href="http://example.org/index.atom"/> |  | <link rel="self" href="http://example.org/index.atom"/> |
| <link rel="next" href="http://example.org/index.atom?page=2"/> |  | <link rel="next" href="http://example.org/index.atom?page=2"/> |
| <updated>2003-12-13T18:30:02Z</updated> |  | <updated>2003-12-13T18:30:02Z</updated> |
| <author> |  | <author> |
| <name>John Doe</name> |  | <name>John Doe</name> |
| </author> |  | </author> |
| <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id> |  | <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id> |
| <entry> |  | <entry> |
| <title>Atom-Powered Robots Run Amok</title> |  | <title>Atom-Powered Robots Run Amok</title> |
| <link href="http://example.org/2003/12/13/atom03"/> |  | <link href="http://example.org/2003/12/13/atom03"/> |
| <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> |  | <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> |
| <updated>2003-12-13T18:30:02Z</updated> |  | <updated>2003-12-13T18:30:02Z</updated> |
| <summary>Some text.</summary> |  | <summary>Some text.</summary> |
| </entry> |  | </entry> |
| </feed> |  | </feed> |
| RSS 2.0-formatted Paged Feed |  |  |
| <?xml version="1.0"?> |  | This specification does not address duplicate entries in paged feeds. |
| <rss version="2.0" |  |  |
| xmlns:atom="http://www.w3.org/2005/Atom"> |  |  |
| <channel> |  |  |
| <title>Liftoff News</title> |  |  |
| <link>http://liftoff.nasa.gov/</link> |  |  |
| <description>Liftoff to Space Exploration.</description> |  |  |
| <language>en-us</language> |  |  |
| <pubDate>Tue, 10 Jun 2003 04:00:00 GMT</pubDate> |  |  |
| <lastBuildDate>Tue, 10 Jun 2003 09:41:01 GMT</lastBuildDate> |  |  |
| <docs>http://blogs.law.harvard.edu/tech/rss</docs> |  |  |
| <generator>Weblog Editor 2.0</generator> |  |  |
| <managingEditor>editor@example.com</managingEditor> |  |  |
| <webMaster>webmaster@example.com</webMaster> |  |  |
| <atom:link rel="next" |  |  |
| href="http://liftof.nasa.gov/index.rss?page=2"/> |  |  |
| <item> |  |  |
| <title>Star City</title> |  |  |
| <link>http://liftoff.nasa.gov/2003/06/news-starcity</link> |  |  |
| <description>How do Americans get ready to work with Russians |  |  |
| aboard the International Space Station? They take a crash course |  |  |
| in culture, language and protocol at Russia's <a |  |  |
| href="http://howe.iki.rssi.ru/GCTC/gctc_e.htm"&gt;Star |  |  |
| City</a>.</description> |  |  |
| <pubDate>Tue, 03 Jun 2003 09:39:21 GMT</pubDate> |  |  |
| <guid>http://liftoff.nasa.gov/2003/06/03.html#item573</guid> |  |  |
| </item> |  |  |
| </channel> |  |  |
| </rss> |  |  |
| 4. Archived Feeds |  | 4. Archived Feeds |
| An archived feed is a set of feed documents that can be combined to |  | An archived feed is a set of feed documents that can be combined to |
| accurately reconstruct the entries of a logical feed. |  | accurately reconstruct the entries of a logical feed. |
| Unlike paged feeds, archived feeds enable clients to do this without |  | Unlike paged feeds, archived feeds enable clients to do this without |
| losing any entries. This is achieved by publishing a single |  | losing entries. This is achieved by publishing a single subscription |
| subscription document and (potentially) many archive documents. |  | document and (potentially) many archive documents. |
| A subscription document is a feed document that always contains the |  | A subscription document is a feed document that always contains the |
| most recently added or changed entries available in the logical feed |  | most recently added or changed entries available in the logical feed. |
| (often, the feed document that should be subscribed to). |  |  |
| Archive documents are feed documents that contain less recent entries |  | Archive documents are feed documents that contain less recent entries |
| in the feed. The set of entries contained in an archive document |  | in the feed. The set of entries contained in an archive document |
| published at a particular URI SHOULD NOT change over time. Likewise, |  | published at a particular URI SHOULD NOT change over time. Likewise, |
| the URI for a particular archive document SHOULD NOT change over |  | the URI for a particular archive document SHOULD NOT change over |
| time. |  | time. |
| These stability requirements allow clients to safely assume that if |  |  |
| they have retrieved an archive document from a particular URI once, |  |  |
| it will not meaningfully change in the future. As a result, if an |  |  |
| archive document's contents are changed, clients may not become aware |  |  |
| of it. |  |  |
| Therefore, if a publisher requires a change to be visible to all |  |  |
| users (e.g., correcting factual errors), they should consider |  |  |
| publishing the revised entry in the subscription feed, in addition to |  |  |
| (or instead of) the appropriate archive feed. Conversely, |  |  |
| unimportant changes (e.g., spelling corrections) might be only |  |  |
| effected in archive feeds. |  |  |
| Typically, a subscription feed will link to a set of archive |  |  |
| documents (also linked together) which contain progressively less |  |  |
| recent entries. |  |  |
| Clients can then "subscribe" to the feed, polling the subscription |  |  |
| document for recent changes. If a client has missed some entries, |  |  |
| the archives can be used to synchronise its state by fetching the |  |  |
| archive documents it has not yet seen. |  |  |
| The following link relations are used to tie subscription and |  | The following link relations are used to tie subscription and |
| archived feeds together: |  | archived feeds together: |
| o "prev-archive" - A URI that refers to the immediately preceding |  | o "prev-archive" - A URI that refers to the immediately preceding |
| archive document. |  | archive document. |
| o "next-archive" - A URI that refers to the immediately following |  | o "next-archive" - A URI that refers to the immediately following |
| archive document. |  | archive document. |
| o "current" - A URI that, when dereferenced, returns a feed document |  | o "current" - A URI that, when dereferenced, returns a feed document |
| containing the most recent entries in the feed. |  | containing the most recent entries in the feed. |
| Subscription documents and archive documents MUST have a "prev- |  | Subscription documents and archive documents MUST have a "prev- |
| archive" link relation, unless there are no archives available. |  | archive" link relation, unless there are no preceding archives |
|  |  | available. Additionally, archive documents SHOULD have "next- |
| Archive documents SHOULD have "next-archive" and "current" link |  | archive" and "current" link relations. |
| relations. |  |  |
| Note that URI references in link relation values may be relative, and |  |  |
| when they are used they must be absolutised, as described in Section |  |  |
| 5.1 of [RFC3986]. |  |  |
| Archive document SHOULD also contain an fh:archive element in their |  | Archive document SHOULD also contain an fh:archive element in their |
| head sections, to indicate that they are archives. |  | head sections to indicate that they are archives. fh:archive is an |
|  |  | empty element; this specification does not define any content for it. |
| For example, |  |  |
| <fh:archive/> |  |  |
| Publishers are not required to make all archive documents available; |  |  |
| they may refuse to serve (e.g., with HTTP status code 403 or 410), or |  |  |
| be unable to serve (e.g., with HTTP status code 404) an archive |  |  |
| document. |  |  |
| Clients SHOULD warn users when they are not able to reconstruct the |  |  |
| complete, logical feed (e.g., by alerting the user that an archive |  |  |
| document is unavailable, or displaying pseudo-entries that inform the |  |  |
| user that some entries may be missing). |  |  |
| 4.1. Examples |  |  |
| Atom-formatted Subscription Document |  | Example: Atom-formatted Subscription Document |
| <?xml version="1.0" encoding="utf-8"?> |  | <?xml version="1.0" encoding="utf-8"?> |
| <feed xmlns="http://www.w3.org/2005/Atom"> |  | <feed xmlns="http://www.w3.org/2005/Atom"> |
| <title>Example Feed</title> |  | <title>Example Feed</title> |
| <link href="http://example.org/"/> |  | <link href="http://example.org/"/> |
| <link rel="self" href="http://example.org/index.atom"/> |  | <link rel="self" href="http://example.org/index.atom"/> |
| <link rel="prev-archive" |  | <link rel="prev-archive" |
| href="http://example.org/2003/11/index.atom"/> |  | href="http://example.org/2003/11/index.atom"/> |
| <updated>2003-12-13T18:30:02Z</updated> |  | <updated>2003-12-13T18:30:02Z</updated> |
| <author> |  | <author> |
| skipping to change at page 11, line 4 |  | skipping to change at page 8, line 27 |
| </author> |  | </author> |
| <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id> |  | <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id> |
| <entry> |  | <entry> |
| <title>Atom-Powered Robots Run Amok</title> |  | <title>Atom-Powered Robots Run Amok</title> |
| <link href="http://example.org/2003/12/13/atom03"/> |  | <link href="http://example.org/2003/12/13/atom03"/> |
| <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> |  | <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> |
| <updated>2003-12-13T18:30:02Z</updated> |  | <updated>2003-12-13T18:30:02Z</updated> |
| <summary>Some text.</summary> |  | <summary>Some text.</summary> |
| </entry> |  | </entry> |
| </feed> |  | </feed> |
| Atom-formatted Archive Document |  |  |
|  |  | Example: Atom-formatted Archive Document |
| <?xml version="1.0" encoding="utf-8"?> |  | <?xml version="1.0" encoding="utf-8"?> |
| <feed xmlns="http://www.w3.org/2005/Atom" |  | <feed xmlns="http://www.w3.org/2005/Atom" |
| xmlns:fh="http://purl.org/syndication/history/1.0"> |  | xmlns:fh="http://purl.org/syndication/history/1.0"> |
| <title>Example Feed</title> |  | <title>Example Feed</title> |
| <link rel="current" href="http://example.org/index.atom"/> |  | <link rel="current" href="http://example.org/index.atom"/> |
| <link rel="self" href="http://example.org/2003/11/index.atom"/> |  | <link rel="self" href="http://example.org/2003/11/index.atom"/> |
| <fh:archive/> |  | <fh:archive/> |
| <link rel="prev-archive" |  | <link rel="prev-archive" |
| href="http://example.org/2003/10/index.atom"/> |  | href="http://example.org/2003/10/index.atom"/> |
| skipping to change at page 12, line 4 |  | skipping to change at page 9, line 4 |
| </author> |  | </author> |
| <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id> |  | <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id> |
| <entry> |  | <entry> |
| <title>Atom-Powered Robots Scheduled To Run Amok</title> |  | <title>Atom-Powered Robots Scheduled To Run Amok</title> |
| <link href="http://example.org/2003/11/24/robots_coming"/> |  | <link href="http://example.org/2003/11/24/robots_coming"/> |
| <id>urn:uuid:cdef5c6d5-gff8-4ebb-assa-80dwe44efkjo</id> |  | <id>urn:uuid:cdef5c6d5-gff8-4ebb-assa-80dwe44efkjo</id> |
| <updated>2003-11-24T12:00:00Z</updated> |  | <updated>2003-11-24T12:00:00Z</updated> |
| <summary>Some text from an old, different entry.</summary> |  | <summary>Some text from an old, different entry.</summary> |
| </entry> |  | </entry> |
| </feed> |  | </feed> |
|  |  | 4.1. Publishing Archived Feeds |
|  |  | The requirement that archive documents be stable allows clients to |
|  |  | safely assume that if they have retrieved one in the past, it will |
|  |  | not meaningfully change in the future. As a result, if an archive |
|  |  | document's contents are changed, some clients may not become aware of |
|  |  | it. |
|  |  | Therefore, if a publisher requires a change to be visible to all |
|  |  | users (e.g., correcting factual errors), they should consider |
|  |  | publishing the revised entry in the subscription feed, in addition to |
|  |  | (or instead of) the appropriate archive feed. Conversely, |
|  |  | unimportant changes (e.g., spelling corrections) might be only |
|  |  | effected in archive feeds. |
|  |  | Publishers SHOULD construct their feed documents in such a way as to |
|  |  | make duplicate removal unambiguous (see Section 4.2). |
|  |  | Publishers are not required to make all archive documents available; |
|  |  | they may refuse to serve (e.g., with HTTP status code 403 or 410), or |
|  |  | be unable to serve (e.g., with HTTP status code 404) an archive |
|  |  | document. |
|  |  | 4.2. Consuming Archived Feeds |
|  |  | Typically, clients will "subscribe" to an archived feed by polling |
|  |  | the subscription document for recent changes. If URI contained in |
|  |  | the prev-archive link relation has not been processed in the past, |
|  |  | the client can "catch up" with any missed entries by dereferencing it |
|  |  | and adding the contained entries to the logical feed. This process |
|  |  | should be repeated recursively until the client encounters a prev- |
|  |  | archive link relation that has been processed, the end of the archive |
|  |  | is indicated by a missing prev-archive link relation, or an error is |
|  |  | encountered. |
|  |  | If duplicate entries are found, clients SHOULD consider only the most |
|  |  | recently updated entry to be part of the logical feed. If duplicate |
|  |  | entries have the same update time-stamp, or none is available, the |
|  |  | entry sourced from the most recently updated feed document SHOULD |
|  |  | replace all other duplicates of that entry. |
|  |  | In Atom-formatted archived feeds, two entries are duplicates if they |
|  |  | have the same atom:id element. The update time of an entry is |
|  |  | determined by its atom:updated element, and likewise the update time |
|  |  | of a feed document is determined by its feed-level atom:updated |
|  |  | element. |
|  |  | Clients SHOULD warn users when they are not able to reconstruct the |
|  |  | entire logical feed (e.g., by alerting the user that an archive |
|  |  | document is unavailable, or displaying pseudo-entries that inform the |
|  |  | user that some entries may be missing). |
|  |  | 5. IANA Considerations |
|  |  | The "previous", "next" and "current" link relations have been |
|  |  | previously registered, and no IANA action regarding them is required. |
|  |  | This specification defines the following link relations: |
|  |  | o Attribute Value: prev-archive |
|  |  | o Description: A URI that refers to the immediately |
|  |  | preceding archive document. |
|  |  | o Expected display characteristics: none |
|  |  | o Security considerations: See [ this document ] |
|  |  | o Attribute Value: next-archive |
|  |  | o Description: A URI that refers to the immediately |
|  |  | following archive document. |
|  |  | o Expected display characteristics: none |
|  |  | o Security considerations: See [ this document ] |
|  |  | 6. Security Considerations |
|  |  | Feeds using these mechanisms could be crafted in such a way as to |
|  |  | cause a client to initiate excessive (or even an unending sequence |
|  |  | of) network requests, causing denial of service (either to the |
|  |  | client, the target server, and/or intervening networks). Clients can |
|  |  | mitigate this risk by requiring user intervention after a certain |
|  |  | number of requests, or by limiting requests either according to a |
|  |  | hard limit, or with heuristics. |
|  |  | Clients should be mindful of resource limits when storing feed |
|  |  | documents. To reiterate, they are not required to always store or |
|  |  | reconstruct the feed when conforming to this specification; they only |
|  |  | need inform the user when the reconstructed feed is not complete. |
|  |  | 7. References |
|  |  | 7.1. Normative References |
|  |  | [RFC2119] Bradner, S., "Key words for use in |
|  |  | RFCs to Indicate Requirement Levels", |
|  |  | BCP 14, RFC 2119, March 1997. |
|  |  | [RFC3986] Berners-Lee, T., Fielding, R., and L. |
|  |  | Masinter, "Uniform Resource |
|  |  | Identifier (URI): Generic Syntax", |
|  |  | STD 66, RFC 3986, January 2005. |
|  |  | [RFC4287] Nottingham, M. and R. Sayre, "The |
|  |  | Atom Syndication Format", RFC 4287, |
|  |  | December 2005. |
|  |  | [W3C.REC-xml-infoset-20040204] Cowan, J. and R. Tobin, "XML |
|  |  | Information Set (Second Edition)", |
|  |  | W3C REC REC-xml-infoset-20040204, |
|  |  | February 2004. |
|  |  | [W3C.REC-xml-names-19990114] Bray, T., Hollander, D., and A. |
|  |  | Layman, "Namespaces in XML", W3C |
|  |  | REC REC-xml-names-19990114, |
|  |  | January 1999. |
|  |  | 7.2. Informative References |
|  |  | [RSS2] Winer, D., "RSS 2.0 Specification", 2005, |
|  |  | <http://blogs.law.harvard.edu/tech/rss>. |
|  |  | Appendix A. Acknowledgements |
|  |  | The author would like to thank the following people for their |
|  |  | contributions, comments and help: Danny Ayers, Thomas Broyer, Lisa |
|  |  | Dusseault, Stefan Eissing, David Hall, Bill de Hora, Aristotle |
|  |  | Pagaltzis, John Panzer, Dave Pawson, Garrett Rooney, Robert Sayre, |
|  |  | James Snell, Henry Story. |
|  |  | Any errors herein remain the author's, not theirs. |
|  |  | Appendix B. Use in RSS 2.0 |
|  |  | As previously noted, while this specification's extensions are |
|  |  | described in terms of the Atom feed format, they are also useful in |
|  |  | similar formats. This informative appendix demonstrates how they can |
|  |  | be used in an RSS 2.0-formatted [RSS2] feed. |
|  |  | In RSS 2.0-formatted feeds, two entries are duplicates if they have |
|  |  | the same guid element. The update time of an entry is not defined by |
|  |  | RSS 2.0, but the feed-level update time can be determined by the |
|  |  | pubDate element. |
|  |  | RSS 2.0-formatted Complete Feed |
|  |  | <?xml version="1.0"?> |
|  |  | <rss version="2.0" |
|  |  | xmlns:fh="http://purl.org/syndication/history/1.0"> |
|  |  | <channel> |
|  |  | <title>NetMovies Queue</title> |
|  |  | <link>http://netmovies.example.org/</link> |
|  |  | <description>The DVDs you'll receive next.</description> |
|  |  | <language>en-us</language> |
|  |  | <pubDate>Tue, 10 Jun 2003 04:00:00 GMT</pubDate> |
|  |  | <lastBuildDate>Tue, 10 Jun 2003 09:41:01 GMT</lastBuildDate> |
|  |  | <docs>http://blogs.law.harvard.edu/tech/rss</docs> |
|  |  | <generator>Weblog Editor 2.0</generator> |
|  |  | <managingEditor>editor@netmovies.example.org</managingEditor> |
|  |  | <webMaster>webmaster@netmovies.example.org</webMaster> |
|  |  | <fh:complete/> |
|  |  | <item> |
|  |  | <title>Casablanca</title> |
|  |  | <link>http://netmovies.example.org/movies/Casablanca</link> |
|  |  | <description>Here's looking at you, kid... |
|  |  | </description> |
|  |  | <pubDate>Tue, 03 Jun 2003 09:39:21 GMT</pubDate> |
|  |  | <guid>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</guid> |
|  |  | </item> |
|  |  | </channel> |
|  |  | </rss> |
|  |  | RSS 2.0-formatted Paged Feed |
|  |  | <?xml version="1.0"?> |
|  |  | <rss version="2.0" |
|  |  | xmlns:atom="http://www.w3.org/2005/Atom"> |
|  |  | <channel> |
|  |  | <title>Liftoff News</title> |
|  |  | <link>http://liftoff.nasa.gov/</link> |
|  |  | <description>Liftoff to Space Exploration.</description> |
|  |  | <language>en-us</language> |
|  |  | <pubDate>Tue, 10 Jun 2003 04:00:00 GMT</pubDate> |
|  |  | <lastBuildDate>Tue, 10 Jun 2003 09:41:01 GMT</lastBuildDate> |
|  |  | <docs>http://blogs.law.harvard.edu/tech/rss</docs> |
|  |  | <generator>Weblog Editor 2.0</generator> |
|  |  | <managingEditor>editor@example.com</managingEditor> |
|  |  | <webMaster>webmaster@example.com</webMaster> |
|  |  | <atom:link rel="next" |
|  |  | href="http://liftof.nasa.gov/index.rss?page=2"/> |
|  |  | <item> |
|  |  | <title>Star City</title> |
|  |  | <link>http://liftoff.nasa.gov/2003/06/news-starcity</link> |
|  |  | <description>How do Americans get ready to work with Russians |
|  |  | aboard the International Space Station? They take a crash course |
|  |  | in culture, language and protocol at Russia's <a |
|  |  | href="http://howe.iki.rssi.ru/GCTC/gctc_e.htm"&gt;Star |
|  |  | City</a>.</description> |
|  |  | <pubDate>Tue, 03 Jun 2003 09:39:21 GMT</pubDate> |
|  |  | <guid>http://liftoff.nasa.gov/2003/06/03.html#item573</guid> |
|  |  | </item> |
|  |  | </channel> |
|  |  | </rss> |
| RSS 2.0-formatted Subscription Document |  | RSS 2.0-formatted Subscription Document |
| <?xml version="1.0"?> |  | <?xml version="1.0"?> |
| <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"> |  | <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"> |
| <channel> |  | <channel> |
| <title>Liftoff News</title> |  | <title>Liftoff News</title> |
| <link>http://liftoff.nasa.gov/</link> |  | <link>http://liftoff.nasa.gov/</link> |
| <description>Liftoff to Space Exploration.</description> |  | <description>Liftoff to Space Exploration.</description> |
| <language>en-us</language> |  | <language>en-us</language> |
| <pubDate>Tue, 10 Jun 2003 04:00:00 GMT</pubDate> |  | <pubDate>Tue, 10 Jun 2003 04:00:00 GMT</pubDate> |
| skipping to change at page 13, line 46 |  | skipping to change at page 16, line 5 |
| <description>Before man travels to Mars, NASA hopes to |  | <description>Before man travels to Mars, NASA hopes to |
| design new engines that will let us fly through the Solar |  | design new engines that will let us fly through the Solar |
| System more quickly. The proposed VASIMR engine would do |  | System more quickly. The proposed VASIMR engine would do |
| that.</description> |  | that.</description> |
| <pubDate>Tue, 27 May 2003 08:37:32 GMT</pubDate> |  | <pubDate>Tue, 27 May 2003 08:37:32 GMT</pubDate> |
| <guid>http://liftoff.nasa.gov/2003/05/27.html#item571</guid> |  | <guid>http://liftoff.nasa.gov/2003/05/27.html#item571</guid> |
| </item> |  | </item> |
| </channel> |  | </channel> |
| </rss> |  | </rss> |
| 5. IANA Considerations |  |  |
| The "previous", "next" and "current" link relations have been |  |  |
| previously registered, and no IANA action regarding them is required. |  |  |
| This specification defines the following link relations: |  |  |
| o Attribute Value: prev-archive |  |  |
| o Description: A URI that refers to the immediately |  |  |
| preceding archive document. |  |  |
| o Expected display characteristics: none |  |  |
| o Security considerations: See [ this document ] |  |  |
| o Attribute Value: next-archive |  |  |
| o Description: A URI that refers to the immediately |  |  |
| following archive document. |  |  |
| o Expected display characteristics: none |  |  |
| o Security considerations: See [ this document ] |  |  |
| 6. Security Considerations |  |  |
| Feeds using the mechanisms described here could be crafted in such a |  |  |
| way as to cause a client to initiate excessive (or even an unending |  |  |
| sequence of) network requests, causing denial of service (either to |  |  |
| the client, the target server, and/or intervening networks). Clients |  |  |
| can mitigate this risk by requiring user intervention after a certain |  |  |
| number of requests, or by limiting requests either according to a |  |  |
| hard limit, or with heuristics. |  |  |
| Clients should be mindful of resource limits when storing feed |  |  |
| documents. To reiterate, they are not required to always store or |  |  |
| reconstruct the feed when conforming to this specification; they only |  |  |
| need inform the user when the reconstructed feed is not complete. |  |  |
| 7. Normative References |  |  |
| [RFC2119] Bradner, S., "Key words for use in |  |  |
| RFCs to Indicate Requirement Levels", |  |  |
| BCP 14, RFC 2119, March 1997. |  |  |
| [RFC3986] Berners-Lee, T., Fielding, R., and L. |  |  |
| Masinter, "Uniform Resource |  |  |
| Identifier (URI): Generic Syntax", |  |  |
| STD 66, RFC 3986, January 2005. |  |  |
| [RFC4287] Nottingham, M. and R. Sayre, "The |  |  |
| Atom Syndication Format", RFC 4287, |  |  |
| December 2005. |  |  |
| [W3C.REC-xml-infoset-20040204] Cowan, J. and R. Tobin, "XML |  |  |
| Information Set (Second Edition)", |  |  |
| W3C REC REC-xml-infoset-20040204, |  |  |
| February 2004. |  |  |
| [W3C.REC-xml-names-19990114] Bray, T., Hollander, D., and A. |  |  |
| Layman, "Namespaces in XML", W3C |  |  |
| REC REC-xml-names-19990114, |  |  |
| January 1999. |  |  |
| Appendix A. Acknowledgements |  |  |
| The author would like to thank the following people for their |  |  |
| contributions, comments and help: Danny Ayers, Thomas Broyer, Stefan |  |  |
| Eissing, David Hall, Bill de Hora, Aristotle Pagaltzis, John Panzer, |  |  |
| Dave Pawson, Garrett Rooney, Robert Sayre, James Snell, Henry Story. |  |  |
| Any errors herein remain the author's, not theirs. |  |  |
| Appendix B. Reconstructing Archived Feeds |  |  |
| One algorithm for reconstructing an archived feed into a complete, |  |  |
| logical feed (S), give the subscription document (D) follows. |  |  |
| 1. Create an empty list L. |  |  |
| 2. Consider the URI of the last archive document successfully stored |  |  |
| to local store S as A. |  |  |
| 3. Consider the set of entries in document D as E. |  |  |
| 4. If the document D has a "prev-archive" link relation value P in |  |  |
| its head section, and P is not A, |  |  |
| 1. Append P to L. |  |  |
| 2. Dereference P and use the resulting feed document as D. |  |  |
| 5. Repeat the previous step until no new P is found. |  |  |
| 6. Add all of document D's entries to the local store S, replacing |  |  |
| any entries with the same identity. |  |  |
| 7. Pop the last "prev-archive" link relation from L, dereference its |  |  |
| value and use the resulting feed document as D. |  |  |
| 8. Repeat the previous two steps until L is empty. |  |  |
| 9. Add the entries E to the local store S, replacing any entries |  |  |
| with the same identity. |  |  |
| In these instructions, the concept of an entry's identity is format- |  |  |
| specific; e.g., in Atom, it is conveyed by the atom:id element; in |  |  |
| RSS 2, it is indicated by the guid element. |  |  |
| Author's Address |  | Author's Address |
| Mark Nottingham |  | Mark Nottingham |
| EMail: mnot@pobox.com |  | EMail: mnot@pobox.com |
| URI: http://www.mnot.net/ |  | URI: http://www.mnot.net/ |
| Full Copyright Statement |  | Full Copyright Statement |
| Copyright (C) The Internet Society (2006). |  | Copyright (C) The Internet Society (2006). |
End of changes. 32 change blocks.
| 256 lines changed or deleted |  | 263 lines changed or added |
This html diff was produced by rfcdiff 1.33. The latest version is available from http://tools.ietf.org/tools/rfcdiff/