ParticleWave is a proposal for the Atom "API" and format that is based on simple best practices of the web and common web formats, with a little hinting available for Atom-specific clients to provide a better user experience.
The Atom Model is the Web Model
The web model is one of identification (URIs), interaction (using a URI to access a resource), and formats. (Architecture of the World Wide Web)
Resources on a web site are "web accessible" when they can be retrieved using their URI. Some resources may also be modified or removed using their URI, or in the case of a templated page, a related URI given for the purpose of maintenance.
The most common protocol for interacting with a URI is HTTP. The HTTP GET method is used to retrieve a resource, the POST and PUT methods to modify, create, or replace the resource, and the DELETE method for deleting a resource. Also common in web site maintenance is the FTP protocol. Advanced web sites may use the WebDav HTTP extension.
In creating or browsing a web site, formats like HTML, XHTML, PNG, XML, XSL, and CSS are used. This specification also introduces some Atom-specific formats and extensions for maintaining a web site.
A web server or publishing application controls the "layout" and allowed URIs and formats of the web site. A site may be as simple as a directory of resources on a server edited entirely "by hand", a directory of resources edited by hand but presented through a simple front-end (blosxom, wiki), a "weblogging" application, or a ContentManagementSystem. Atom provides some hints as to where common resources will be used (for example, creating new entries or comments, or uploading templates) but also allows complete freedom for a server or application to define URI locations.
Common extension format for HTML
For Atom extensions to HTML, the HTML <meta> and <link> tags are used.
Common minimal format for HTML
In several interactions it is convenient for Atom-enabled tools to use a minimal HTML format that contains only the "content" of a resource. Atom tools may extract the information in <head> and use the content of <body> on the web site. No restrictions on the HTML format are given in this specification but it is expected that Atom servers may "tidy" the HTML or restrict usage of HTML tags. Minimal HTML should not include structural HTML that would propagate "outside" of the body when displayed along with other content items.
- browser or browser client
a common web browser, like Netscape or Internet Explorer
- atom client
a client enhanced with support for Atom specific hints and formats
the initiator of actions to a server, may be a browser, an atom client, or other tool or library; sometimes called an agent or user agent
the receiver of requests from a client, often refers both to a web server (like Apache) and to applications responding to requests (via the web server)
- atom server
a server or server-based application enhanced with support for Atom specific hints and formats
- publishing system
in the Atom context, a server-based application for publishing a site (in contrast to "desktop" publishing systems)
as used in this document also includes XHTML
- minimal HTML
HTML that is expected to be manipulated by an Atom client or server. Commonly, the body portion of minimal HTML will be extracted and fed into templates to produce the web site.
- plain text
as used in this document also includes plain text that contains plain text markup (like wiki or textile markup)
The following sections describe the most commonly used resources in an episodic website. The common formats used are referenced or defined. Typical interactions and common error conditions are described. In some cases, specific interactions or formats are given to allow Atom-enabled clients to provide better user interaction with Atom-enabled servers.
WebLog Main Page
A Weblog page is the "top-level" resource for an episodic web site. In some cases, the weblog page may also be the site's "Home Page". Some sites often have multiple weblog pages organized into categories; Category pages will often have the same Atom-hints as weblog pages.
Typical interaction and format
In most cases, the weblog page is only retrieved, rarely maintained directly except in the case of hand-edited sites. The most common format for weblog pages is HTML.
<link rel="alternate" type="application/rss+xml" title="RSS" href="http://rss.news.yahoo.com/rss/tech" /> <link rel="atom.create-entry" href="URI" title="Create Entry" /> <link rel="atom.entry.base" href="baseURI" title="Base URI for Entries" /> <link rel="atom.templates.base" href="baseURI" title="Base URI for Templates" /> <link rel="atom.search" href="URI" title="Search URI" /> <link rel="atom.categories" type="text/plain" href="URI" title="List of categories" /> <link rel="atom.preferences" type="application/xml" href="URI" title="User preferences" /> <link rel="atom.static.base" href="baseURI" title="Base URI for static files" />
atom.create-entry accepts a POSTed resource containing the new entry. Servers commonly accept plain text or minimal HTML. HTTP servers returns the new URI for the entry in the Location: header.
atom.entry.base gives the base URI for "entries". Entries are commonly plain text or minimal HTML.
Suggestion: A user is browsing our website using a standard browser. He is reading an HTML page and wants to correct something on the page. How does he (his browser) get the Atom representation of it for editing? I don't see a clear path above to get from the HTML representation of a page to its correct Atom URL without a fair bit guess work and assumptions, so why not allow <link rel="atom.edit" href="/somepath/to/AtomEntry" title="Atom representation of this page" />. For example: I have an html representation of a page at http://www.example.com/category/page.html, and the Atom representation at http://www.example.com/category/page.atom, so I'd like to insert the latter URL as a link rel in page.html: <link rel="atom.edit" href="/category/page.atom" title="Atom entry point for this page" />, rather than force the Atom client to figure it. [MikeDavies]
@@can 'type' specify multiple supported types? maybe a atom.entry.types
A Feed contains information about the weblog, category, or other episodic information and a list of the most recent entries.
@@Feeds may be superseded or enhanced by a technique for efficiently retrieving a site resource index, including "most recent entries" or some other notification mechanism.
Typical interaction and format
Feeds are polled (retrieved or checked) on a regular basis to provide a list of new entries. Feeds generally contain a link to the entry, a title, a summary or description, a modification date, and an ID. Feeds are rarely maintained by users directly.
Common formats are RSS and Atom.
For an Atom-enabled server, the "content" of an entry is available at the entry link and the feed itself only contains overview information.
In an RSS feed, an Atom-enabled server is indicated by @@something. Includes Atom URIs for entry editing and comment posting.
Entries and Comments
Comments and entries are smaller "content items" of a web site, usually maintained individually and presented by a publishing system. An episodic web site is generally organized such that most recent entries are on the "weblog page" and older entries are available through an archive or back-links. Entries commonly allow comments to be added to the entry, and some sites allow comments to be directed, or reply to, other comments.
Typical interaction and format
When browsing, entries and comments are usually formatted by the server and presented on a pages with groups of entries or comments.
When editing, entries and comments are maintained at an "edit URI", either provided by the server in response to a newly created entry or selected by the user underneath a base URI. Hints in the weblog page, entry page, or comment page will indicate which technique a server supports.
After an entry or comment is created, it can then be modified, replaced, or deleted as the server permits. Using HTTP, the PUT method will replace the entry and DELETE will delete the entry.
The common formats for entries and comments are plain text and minimal HTML. A common format for comments is TrackBack www-form-encoded.
A weblog or category page, entry, or comment will have an atom.create-entry URI if the server accepts an HTTP POST of a new entry -- the edit URI is returned in the Location: header of the HTTP response @@see also FTP STOU. A weblog will have an atom.entry.base base-URI if the user can select a URI within that space to create their entry, typically using HTTP PUT or FTP STOR.
A weblog page will have the hint for creating new "main entries" in the header of the page. Each entry or comment on a page may also have a hint with that entry's edit URI (atom.entry.uri), reply URI (atom.create-entry), or identifier URI (atom.entry.id). @@exact technique TBD -- most likely like trackback
Feed formats will also include edit, reply, and identifier URIs for an entry.
Preferences, Templates, static files, and other resources
Other web site resources are maintained directly.
Typical interaction and format
Most "static file" resources on a site are created, modified or replaced, or deleted at a user selected URI usually beneath a base URI.
Some resources are pre-determined by the server application. A user may be able to create them if they do not already exist, but may not be able to select a URI for those resources.
@@full list TBD