TrackBack Technical Documentation


NAME

mttrackback - TrackBack Technical Documentation


SYNOPSIS

This document describes the TrackBack framework, including the format of the TrackBack ping requests and responses. Non-technical discussion of TrackBack is available in the Movable Type manual, at http://www.movabletype.org/docs/mtmanual_trackback.html.


TRACKBACK PING FORMAT

TrackBack uses a REST model for its pings in order to ensure that each TrackBack item has a unique URL (by the numeric ID of the TrackBack item).

Request: Sending a ping

A request is made through HTTP GET to the ping URL, which generally looks like this:

http://foo.com/mt/mt-tb.cgi?tb_id=ID

where ID is the numeric ID of the TrackBack item. The request parameters are added on to the end of that URL, like this:

http://foo.com/mt/mt-tb.cgi?tb_id=ID&title=TITLE&url=URL

etc. The possible query parameters are:

In the Movable Type implementation, of the above parameters only url is required. If title is not provided, the value for url will be set as the title.

A sample ping URL, with parameters included, might look like this:

http://www.movabletype.org/mt/mt-tb.cgi?tb_id=5&title=Foo+Bar&url=http://www.foo.com/archives/000016.shtml&blog_name=My+Blog

Response

The response to the above query is in a simple XML format to enable application-level error detection (HTTP-level errors will be returned as such--for example, if the TrackBack URL points to a non-existent location on the server, a 404 error will be returned from the ping).

A successful ping will return the following response:

<?xml version="1.0" encoding="iso-8859-1"?>
<response>
<error>0</error>
</response>

A failed ping will return the following response:

<?xml version="1.0" encoding="iso-8859-1"?>
<response>
<error>1</error>
<message>The error message</message>
</response>

Applications should, of course, allow for the future addition of fields, if necessary. But the XML structure of the response will remain the same.


RETRIEVING PINGS IN RSS FORMAT

Request: Retrieving Pings

To retrieve a list of pings made on a particular TrackBack item, use a URL in this format:

http://foo.com/mt/mt-tb.cgi?tb_id=ID&__mode=rss

where ID is the numeric ID of the TrackBack item.

A sample URL might look like this:

http://www.movabletype.org/mt/mt-tb.cgi?tb_id=5&__mode=rss

Response

The response to this request will either be an error in the same format as returned from the above request, or the list of TrackBack pings for that item in RSS markup, wrapped in <response> tags.

For example:

<?xml version="1.0" encoding="iso-8859-1"?>
<response>
<error>0</error>
<rss version="0.91"><channel>
<title>TrackBack Test</title>
<link>http://this.is/the/trackback/item/link/</link>
<description>Description of the TrackBack item</description>
<language>en-us</language>
<item>
<title>TrackBack Demo</title>
<link>http://this.is/the/permalink/</link>
<description>Excerpt</description>
</item>
</channel>
</rss></response>

The portions between <rss> and </rss> are the actual RSS data; the rest is simply the response wrapper, and can be discarded.


TRACKBACK RDF

When you publish an entry that is TrackBack-enabled in Movable Type, the system embeds RDF data into your HTML page. This RDF data can then be used by programs to extract a list of TrackBack-enabled entries on the page, along with their TrackBack ping URLs. The Movable Type bookmarklet uses the RDF data to do just this: if you click on the bookmarklet while on a page with TrackBack-enabled entries, the bookmarklet will present you with a list of entries, from which you can select an entry to ping.

If you develop a TrackBack implementation such that posts on your site can receive pings, you may wish to add the necessary RDF to your pages so that people using the bookmarklet can automatically grab the list of entries.

The RDF looks like this:

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:dc="http://purl.org/dc/elements/1.1/">
<rdf:Description
    about="http://www.foo.com/path/to/trackback?tb_id=ID"
    dc:title="Title of Entry"
    dc:identifier="http://www.foo.com/permalink"
    dc:subject="Category of Entry"
    dc:description="Excerpt / Description"
    dc:creator="Author of Entry"
    dc:date="Date of Entry" />
</rdf:RDF>

The dc: elements are standard Dublin Core elements. The dc:date element should be in YYYY-MM-DDTHH:MM:SS[-]TZ format, where TZ is the timezone in HH:MM offset format.

Sample RDF might look like this:

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:dc="http://purl.org/dc/elements/1.1/">
<rdf:Description
    about="http://www.foo.com/mt/mt-tb.cgi?tb_id=1"
    dc:title="Foo Bar"
    dc:identifier="http://www.foo.com/archives/000016.shtml"
    dc:subject="Links"
    dc:description="This is an entry on my site."
    dc:creator="Ben"
    dc:date="2002-07-24T22:21:05-08:00" />
</rdf:RDF>

Movable Type only uses about, dc:title, and dc:identifier currently (although it emits all of the above data). So from that standpoint, only those attributes are required, which would make the following perfectly acceptable:

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:dc="http://purl.org/dc/elements/1.1/">
<rdf:Description
    about="http://www.foo.com/mt/mt-tb.cgi?tb_id=1"
    dc:title="Foo Bar"
    dc:identifier="http://www.foo.com/archives/000016.shtml" />
</rdf:RDF>


SAMPLE IMPLEMENTATION

To aid perspective developers in implementing TrackBack in their own systems, we are releasing a standalone implementation of TrackBack that is not dependent on Movable Type. It accepts pings sent through HTTP requests, stores the pings locally in the filesystem, and can return a list of pings sent on a particular TrackBack item in RSS format. It also generates RSS files statically, if you want it to. This can be useful for including a list of the last 15 TrackBack pings on a sidebar on your site, for example.

The standalone implementation can be downloaded from http://www.movabletype.org/downloads/tb-standalone.tar.gz.

It is released under the Artistic License. The terms of the Artistic License are described at http://www.perl.com/language/misc/Artistic.html.

Installation and usage instructions are at http://www.movabletype.org/docs/tb-standalone.html.


Copyright © 2001, 2002 Ben Trott and Mena Trott. All Rights Reserved.