Atom Implementation Guide

Atom Implementation Guide IBM

4400 Silicon Drive Durham NC 27713 US

This document provides advice to implementers of the Atom Syndication Format and the Atom API. To provide feedback on this Internet-Draft, join the atom-syntax mailing list (http://www.imc.org/atom-syntax/index.html).

Atom is an XML-based format intended to allow lists of information, known as "feeds", to be synchronised between publishers and consumers. The primary use case that Atom addresses is for syndicating web content such as weblogs and news headlines to other web sites and directly to consumers. The most popular way to publish Atom feeds is over Hypertext Transfer Protocol (HTTP) . However, nothing precludes it from being used for other purposes and types of content, or being sent over other protocols. There are a number of subtleties to HTTP and XML that have historically been overlooked by implementers, both publishers and consumers. Due to the repetitive polling model that most Atom-enabled consumers employ, small bugs in HTTP implementations can quickly waste large amounts of bandwidth and cause network congestion. Due to the complexity of XML and its interaction with other standards, bugs in XML implementations can easily cause loss of interoperability. This document contains separate sections for publishers and consumers, since it is assumed that few developers will be interested in both. In many cases, the guidelines for publishers and consumers are symmetrical, because many best practices require cooperation from both sides. If there are guidelines telling publishers how to support -- and advertise their support for -- a particular feature, there are also guidelines telling consumers how to recognize and take advantage of the feature.

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 .

Some data changes all the time. The feed of a popular news site might be updated every few minutes. On the other hand, the feed of a monthly newsletter would only change once a month when a new edition is published. Since the most popular design pattern of Atom feed consumers is to repeatedly poll the feed for changes, this could result in a lot of unnecessary bandwidth consumption by downloading the same data over and over again. HTTP provides a solution to this problem. When a web server receives a request for a feed, it can send the feed, and it can also send the date the feed was last modified, in the Last-Modified HTTP header. When the same client requests the same feed a second time, it includes in its request the last-modified date that it received in the previous request, in the If-Modified-Since header. If the feed hasn't changed since the previous request, the web server responds with a special HTTP status code, 304 ("Not Modified"). Why is this an improvement? Because when the web server sends a 304 status code, it doesn't re-send the data. All the client gets is the status code. So clients don't need to download the same data over and over again if it hasn't changed. Publishers SHOULD send a Last-Modified HTTP header every time they serve an Atom feed. Many web servers do this by default for static files. Programs that generate feeds dynamically will most likely need to add the header themselves. The format of the Last-Modified header is given in Section 14.29 of . Publishers SHOULD check each request for the existence of the If-Modified-Since HTTP header, and follow the procedure outlined in Section 14.25 of for sending the HTTP 304 "Not Modified" status code. Again, many web servers do this by default for static files. Programs that generate feeds dynamically will most likely need to check the If-Modified-Since header and do the date math themselves. (Savvy readers may notice that when the feed does finally change, it will likely change very little. For example, in a feed of 10 entries, one entry might be added at the top, one entry removed from the bottom, and the other nine entries are unchanged. So there is still a fair amount of redundant data being downloaded whenever the feed changes, since it usually only changes a little bit at a time. HTTP status code 304 will not help in this case; it only saves bandwidth when there have been no changes at all. There is a way to save bandwidth by serving partial feeds to clients who support it; see for that.)

[[ TODO ]]

[[ TODO - RFC 3229 stuff ]]

All resources served over HTTP are supposed to be served with a Content-Type header, which indicates the media type of the resource. For example, HTML pages are served as "Content-Type: text/html", PNG images are served as "image/png", and so forth.

The registered media type for Atom feeds is "application/atom+xml". Publishers SHOULD serve all Atom feeds with this media type, by returning a Content-Type HTTP header that looks like this: Content-Type: application/atom+xml [[TODO - application/xml]] [[TODO - text/xml]] [[TODO - cross-reference character encoding section w.r.t. text/xml]] [[TODO - no media types other than the ones listed in RFC 3023, specifically MUST NOT use text/plain]]

[[ TODO (note difference from temporary redirects) ]]

In certain cases, a publisher may wish to indicate that an Atom feed is no longer available. For example, a feed for a weblog that the author has ceased writing, or a feed that once offered news about a one-time event that is now over. For whatever reason, if a feed used to exist, and it no longer exists at any URI, the publisher SHOULD return an HTTP status code 410 ("Gone") on all requests for the feed.

Atom feeds MUST use XML 1.0 . No other version of XML is supported.

To declare your feed as XML 1.0, use this XML declaration as the first line of your feed: <?xml version="1.0"?> Make sure there are no leading spaces or blank lines before the XML declaration.

If you use a character encoding other than UTF-8, you SHOULD declare that in the XML declaration as well: <?xml version="1.0" encoding="iso-8859-15"?> [[TODO - rework/move this section, not sure how to approach this without introducing character encoding too]]

[[ TODO intro about character encoding, two places to declare it, etc. ]] [[ TODO SHOULD declare it in XML declaration ]] The Content-Type HTTP header (see ) can contain an optional charset parameter which indicates the character encoding of the feed. If present, the charset parameter always takes precedence over the character encoding declared in the XML declaration on the first line of the feed. Therefore, it is important not to get it wrong. [[TODO - example scenarios to illustrate when it is safe to declare character encoding in HTTP header -- basically, whenever the software that is outputting the HTTP header is aware of the actual encoding...]]

[[ TODO - UTF-8 or UTF-16 are the only encodings guaranteed to be supported ]]

[[ TODO ]]

There are a number of characters that are commonly produced by software running on Microsoft Windows, ranging from 0x80 through 0x9F in the Cp-1252 character encoding (also known as "Windows-1252"). These characters are used to denote common typographical symbols such as a curly apostrophe or a trademark symbol. Unfortunately, few people are aware that these characters mean different things in different character encodings, and therefore may not display as intended. For example, in the Cp-1252 character encoding, a curly apostrophe can be written as the byte 0x92, or as the character reference "" or "". If your Atom feed is specifically declared as "Cp-1252" or "Windows-1252", these will be displayed as a curly apostrophe. However, if your feed is declared as "iso-8859-1", the byte 0x92 is an unprintable control character, and may be displayed as a box, a question mark, or nothing at all (depending on the display device). And if your feed is declared as "utf-8", 0x92 does not map to anything at all, and its presence will make your feed ill-formed XML. Replacing the byte 0x92 with the character reference "" or "" does not solve this problem, since an XML parser will treat all three identically. The problem is not whether you are using raw bytes or character references; the problem is that, unless you have explicitly declared your feed as "Cp-1252", you are using the wrong character to denote a curly apostrophe. Atom feed publishers SHOULD replace the following problematic characters and character references with their Unicode equivalents, which display correctly in every character encoding: Instead of 0x80 or "" or "", use U+20AC or "€" Instead of 0x82 or "" or "", use U+201A or "‚" Instead of 0x83 or "" or "", use U+0192 or "ƒ" Instead of 0x84 or "" or "", use U+201E or "„" Instead of 0x85 or "" or "", use U+2026 or "…" Instead of 0x86 or "" or "", use U+2020 or "†" Instead of 0x87 or "" or "", use U+2021 or "‡" Instead of 0x88 or "" or "", use U+02C6 or "ˆ" Instead of 0x89 or "" or "", use U+2030 or "‰" Instead of 0x8A or "" or "", use U+0160 or "Š" Instead of 0x8B or "" or "", use U+2039 or "‹" Instead of 0x8C or "" or "", use U+0152 or "Œ" Instead of 0x8E or "" or "", use U+017D or "Ž" Instead of 0x91 or "" or "", use U+2018 or "‘" Instead of 0x92 or "" or "", use U+2019 or "’" Instead of 0x93 or "" or "", use U+201C or "“" Instead of 0x94 or "" or "", use U+201D or "”" Instead of 0x95 or "" or "", use U+2022 or "•" Instead of 0x96 or "" or "", use U+2013 or "–" Instead of 0x97 or "" or "", use U+2014 or "—" Instead of 0x98 or "" or "", use U+02DC or "˜" Instead of 0x99 or "" or "", use U+2122 or "™" Instead of 0x9A or "" or "", use U+0161 or "š" Instead of 0x9B or "" or "", use U+203A or "›" Instead of 0x9C or "" or "", use U+0153 or "œ" Instead of 0x9E or "" or "", use U+017E or "ž" Instead of 0x9F or "" or "", use U+0178 or "Ÿ"

[[ TODO ]]

The User-Agent HTTP header, defined in Section 14.43 of , is a simple way for a client to identify itself to a server when requesting resources. Every time an Atom client requests a feed, the client should identify itself as specifically as possible. This allows the server administrator to get in touch with the client-side developer if anything is going fantastically wrong. It is also possible that a user on a shared web server could start publishing an Atom feed without the server administrator's knowledge. When the administrator looks at their web server access logs, they will see repeated requests for a single resource. If the administrator is unfamiliar with the concept of Atom feeds, this client activity may seem unusual or suspicious. Therefore, clients should include in their User-Agent string a URL of a page that explains the product. This can be the product's home page, or a separate page speifically designed to explain the product to wary server administrators.

The User-Agent string SHOULD contain the product application name, the version number, and a URL to the product home page or other explanatory page. For example: MyAtomClient/1.3 +http://www.example.com/myatomclient/ Clients MAY include other information in the User-Agent string, such as the operating system the client is running on. This can be helpful in troubleshooting problems, especially if the same product runs on multiple operating systems.

[[ TODO ]]

[[ TODO - RFC 3229 stuff ]]

[[ TODO ]]

As noted in , Atom feeds can disappear forever for a variety of reasons. Publishers indicate this permanent condition by returning an HTTP status code 410 ("Gone"). If a client requests an Atom feed and receives an HTTP status code 410, the client SHOULD NOT request the feed ever again. If the client interacts with an end user, it MAY inform the end user that the feed is gone. The client MAY retain any cached data it retrieved prior to the feed being marked gone.

defines the interaction between XML and HTTP as it relates to character encoding. XML and HTTP have different ways of specifying character encoding and different defaults in case no encoding is specified, and determining which value takes precedence depends on a variety of factors.

In XML, the character encoding is optional and may be given in the XML declaration in the first line of the document, like this: <xml version="1.0" encoding="iso-8859-1"?> If no encoding is given, XML supports the use of a Byte Order Mark to identify the document as some flavor of UTF-32, UTF-16, or UTF-8. Section F of outlines the process for determining the character encoding based on unique properties of the Byte Order Mark in the first two to four bytes of the document. If no encoding is specified and no Byte Order Mark is present, XML defaults to UTF-8.

HTTP uses MIME to define a method of specifying the character encoding, as part of the Content-Type HTTP header, which looks like this: Content-Type: text/html; charset="utf-8" If no charset is specified, HTTP defaults to iso-8859-1, but only for text/* media types. For other media types, the default encoding is undefined, which is where RFC 3023 comes in. According to RFC 3023, if the media type given in the Content-Type HTTP header is "application/xml", "application/xml-dtd", "application/xml-external-parsed-entity", or any one of the subtypes of application/xml such as "application/atom+xml", then the encoding is the encoding given in the charset parameter of the Content-Type HTTP header, or the encoding given in the encoding attribute of the XML declaration within the document, or utf-8 On the other hand, if the media type given in the Content-Type HTTP header is "text/xml", "text/xml-external-parsed-entity", or a subtype like "text/AnythingAtAll+xml", then the encoding attribute of the XML declaration within the document is ignored completely, and the encoding is the encoding given in the charset parameter of the Content-Type HTTP header, or us-ascii Clients MUST use the procedure described in RFC 3023 to correctly determine the character encoding of an Atom feed.

[[ TODO ]]

This document relies on the registration of the Atom media type, which is defined in .

[[ TODO ]]

&rfc2119; &rfc2616; &xml; &rfc3023; The Atom Syndication Format

mnot@pobox.com

This specification describes Atom, an XML-based Web content and metadata syndication format. Atom Feed Autodiscovery

pilgrim@gmail.com

This document specifies a machine-readable method of linking to an Atom feed from a HyperText Markup Language (HTML) or Extensible HyperText Markup Language (XHTML) document.

The following people contributed to this specification's content: [[TODO]]

Outline