The Well-Formed Web

Ok, there are a lot of interfaces now circulating TrackBack, Ping-Back, Post-It. All of these are a way of commenting on an item. The only thing missing from the mix is a way to do 'comments' themselves. That is where this specification enters. It is intended to be a roll-up of all the above specifications and to cover comments as well.

As usual I am going to try to re-use as much prior art as possible. In this case I am going to re-use RSS 2.0 and have the payload for this type of message be an 'item' fragment from an RSS 2.0 feed.

If you want to add a comment to a story you just POST an RSS 'item' fragment to the URL specified for comments. How to find that URL is covered later in this document.

POST /news/comments/5 HTTP/1.1
Content-Type: text/xml

<?xml version="1.0" encoding='iso-8859-1'?>
<item>
  <title>Foo Bar</title>
  <author>[email protected]</author>
  <link>http://www.bar.com/</link>
  <description>My Excerpt</description>
</item>

The only response required from the server is the HTTP status code:

HTTP/1.1 200 OK

Note that any appropriate status code can be returned. For example, a 303 may be returned with a Location: header pointing to the URL of the newly created comment.

Further note that the contents of the 'item' element are guided by the RSS 2.0 specification, which states that all elements are optional, but requires that at least one of 'title' or 'description' are present.

Examples

Examples are worth a thousand words, so here are examples of TrackBack, Ping-Back and Post-It items all re-factored into CommentAPI format.

Post-It

Here is an example of a Post-It. Note that line breaks have been inserted for readability.

POST http://www.foo.com/mt-tb.cgi/5
Content-Type: application/x-www-form-urlencoded

comment=My+Excert
[email protected]
&name=Foo+Bar
&url=http://www.bar.com/
&agent=send-cb.pl+(Version+0.1)

In the Comment API this becomes:

POST /news/comments/5 HTTP/1.1
Content-Type: text/xml

<item>
  <title>Foo Bar</title>
  <author>[email protected]</author>
  <link>http://www.bar.com/</link>
  <description>My Excerpt</description>
</item>

TrackBack

Here is an example of TrackBack. Note that line breaks have been inserted for readability.

POST http://www.foo.com/mt-tb.cgi/5
Content-Type: application/x-www-form-urlencoded

title=Foo+Bar
&url=http://www.bar.com/
&excerpt=My+Excerpt
&blog_name=Foo

In the Comment API this becomes:

POST /news/comments/5 HTTP/1.1
Content-Type: text/xml

<item>
  <title>Foo Bar</title>
  <link>http://www.bar.com/</link>
  <description>My Excerpt</description>
  <source>Foo</source>
</item>

Ping-Back

Here is an example of Ping-Back.

POST /news HTTP/1.1
Content-Type: text/xml


<methodCall>
  <methodName>pingback.ping</methodName>
  <params>
    <param>
      <value>http://www.bar.com/</value>
      <name>sourceURI</value>
    </param>
    <param>
      <value>http://www.somebar.com/news</value>
      <name>targetURI</value>
    </param>
  </params>
</methodCall>

In the Comment API becomes

POST /news/comments/5 HTTP/1.1
Content-Type: text/xml

<item>
  <link>http://www.bar.com/</link>
</item>

In this case the targetURI doesn't appear since it is implicitly embedded in the URI given for the Comment to be posted to.

Summary Table

Here is a summary of all the above interfaces and how they map to RSS 'item' child elements. Also included in the last column is the elements that are used when posting a comment.

Table 1
How other interfaces map to the CommentAPI

CommentAPI Element	Ping-back	Track-back	Post-It	A Comment
title		title	name	name title
link	sourceURI	url	url	Link to home page of the comment author.
description		excerpt	comment	The text of the comment.
author			email	email
source		blog_name
dc:creator				name

When looking at the above table it is important to keep in mind the context of the data. That is, remember that this is what the data looks like when it arrives at the server. This is no way constrains the CommentAPI server as to how to interpret the data. For example, if you produce an RSS feed of the last 20 comments on your site, then there should be no expectation that the 'item's in that RSS feed be exactly formatted as they arrived. That is because they appear in a different context.

Notes

1. XML-RPC makes it akward to refer to stuff, what this entry means is that the 'value' of the 'sourceURI' element pair is what is submitted in the 'link' element.

Auto-Discovery

Two mechanims are available for discovering the URI that is the target of the POST. The first is a way to put that information in HTML, the second is a way to embed that information in an RSS feed.

HTML

Lot's of options here but the <link> element has been so successful in finding RSS feeds that I'm going to use it here for discovering the Comment interface URI in HTML pages. In this case the form is:

<link rel="service.comment" type="text/xml" href="url goes here" title="Comment Interface">

Where href should be set to the URL that understands the CommentAPI. Applications looking for a comment URI need to parse out the headers of the web page and look for a link tag that has a relation rel of "comment" and a mime-type of "text/xml".

N.B. The URI given is not the URI of the web page that will present an HTML form for posting but instead it is the URI that will take POSTs of RSS 2.0 'item' fragments and will interpret them as comments.

RSS

A new item level element named 'comment' in the namespace /CommentAPI/ is used to provide the location of the CommentAPI endpoint to aggregator software. This is providing the same information as the link tag does in HTML. Here is an example:

<wfw:comment xmlns:wfw="/CommentAPI/">
  /news/comments/52
</wfw:comment>

N.B. Just like was stated for the Link tag, the URI given is not the URI of the web page that will present an HTML form for posting but instead it is the URI that will take a POST of an RSS 2.0 'item' fragment and will interpret it as a comment.

Revision History

13-March-2003

Added anchors for each section. Also updated the RSS Auto-find to include suggestions from this discussion.

20-March-2003

Changed the namespace URI for wfw to be more specific.