[转]TrackBack Technical Specification
TrackBack Technical Specification
- NAME
- Authors
- Version
- Description
- Sending a TrackBack Ping
- Retrieving TrackBack Pings
- Auto-Discovery of TrackBack Ping URLs
- Examples
- Changes
- Credits
NAME
mttrackback - TrackBack Technical Specification
Authors
Benjamin and Mena Trott, movabletype.org
Version
1.1
Description
This document describes TrackBack, a framework for peer-to-peer communication and notifications between web sites. The central idea behind TrackBack is the idea of a TrackBack ping, a request saying, essentially, ``resource A is related/linked to resource B.'' A TrackBack ``resource'' is represented by a TrackBack Ping URL, which is just a standard URI.
Using TrackBack, sites can communicate about related resources. For example, if Weblogger A wishes to notify Weblogger B that he has written something interesting/related/shocking, A sends a TrackBack ping to B. This accomplishes two things:
- Weblogger B can automatically list all sites that have referenced a particular post on his site, allowing visitors to his site to read all related posts around the web, including Weblogger A's.
- The ping provides a firm, explicit link between his entry and yours, as opposed to an implicit link (like a referrer log) that depends upon outside action (someone clicking on the link).
Sending a TrackBack Ping
TrackBack uses a REST model, where requests are made through standard HTTP calls. To send a TrackBack ping, the client makes a standard HTTP request to the server, and receives a response in a simple XML format (see below for more details).
In the TrackBack system, the URL that receives TrackBack pings is the TrackBack Ping URL. A typical TrackBack Ping URL looks like http://www.foo.com/mt-tb.cgi/5, where 5
is the TrackBack ID. Server implementations can use whatever format makes sense for the TrackBack Ping URL; client implementations should not depend on a particular format.
To send a ping, the client sends an HTTP POST request to the TrackBack Ping URL. The request contents should be of the content type application/x-www-form-urlencoded
. For example, a ping request to the URL http://www.foo.com/mt-tb.cgi/5 might look like this:
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
The possible parameters are:
- title
The title of the entry. - excerpt
An excerpt of the entry. In the Movable Type implementation, if this string is longer than 255 characters, it will be cropped to 252 characters, and...
will be added to the end. - url
The permalink for the entry. Like any permalink, this should point as closely as possible to the actual entry on the HTML page, as it will be used when linking to the entry in question. - blog_name
The name of the blog in which the entry is posted.
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.
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 TrackBack Pings
To retrieve the list of pings sent to a particular TrackBack Ping URL, send an HTTP GET request to the TrackBack Ping URL with the query string ?__mode=rss. In future revisions of the specification--once the grace period for switching to GET from POST has passed--this may be simplified such that sending a GET request to the TrackBack Ping URL will return the list of pings.
A sample GET request might look like this:
GET http://192.168.1.103/mt/mt-tb.cgi/3?__mode=rss
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.
Auto-Discovery of TrackBack Ping URLs
TrackBack clients need a method of determining the TrackBack Ping URL for a particular URL or weblog entry. Server implementations should include embedded RDF in the pages they produce; the RDF represents metadata about an entry, allowing clients to auto-discover the TrackBack Ping URL.
Sample 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/" xmlns:trackback="http://madskills.com/public/xml/rss/module/trackback/"> <rdf:Description rdf:about="http://www.foo.com/archive.html#foo" dc:identifier="http://www.foo.com/archive.html#foo" dc:title="Foo Bar" trackback:ping="http://www.foo.com/tb.cgi/5" /> </rdf:RDF>
Note: because current validators choke on RDF embedded in XHTML, if you want your pages to validate you may wish to enclose the above RDF in HTML comments:
<!-- <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" ... </rdf:RDF> -->
This is not a perfect solution, but it works as a temporary fix.
The dc: elements are standard Dublin Core elements; the trackback:ping element comes from the TrackBack Module for RSS 1.0/2.0 at http://madskills.com/public/xml/rss/module/trackback/.
Given a URL my_url, clients should follow these steps:
- Send an HTTP GET request to retrieve the contents of the page at my_url.
- Scan the page contents for embedded RDF. Pages can contain multiple instances of embedded RDF--clients should pick the block whose dc:identifier matches my_url.
- Extract the trackback:ping value from the block of RDF. This is the TrackBack Ping URL.
Once the client has determined the TrackBack Ping URL, it can send a TrackBack ping (see Sending a TrackBack Ping).
Example auto-discovery code is below in Examples.
Examples
Sample TrackBack 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.
Sample Auto-Discovery
use LWP::UserAgent; sub discover_tb { my $url = shift; my $ua = LWP::UserAgent->new; $ua->agent('TrackBack/1.0'); $ua->parse_head(0); ## So we don't need HTML::HeadParser $ua->timeout(15); ## 1. Send a GET request to retrieve the page contents. my $req = HTTP::Request->new(GET => $url); my $res = $ua->request($req); return unless $res->is_success; ## 2. Scan te page contents for embedded RDF. my $c = $res->content; (my $url_no_anchor = $url) =~ s/#.*$//; my $item; while ($c =~ m!(<rdf:RDF.*?</rdf:RDF>)!sg) { my $rdf = $1; my($perm_url) = $rdf =~ m!dc:identifier="([^"]+)"!; next unless $perm_url eq $url || $perm_url eq $url_no_anchor; ## 3. Extract the trackback:ping value from the RDF. ## We look for 'trackback:ping', but fall back to 'about' if ($rdf =~ m!trackback:ping="([^"]+)"!) { return $1; } elsif ($rdf =~ m!about="([^"]+)"!) { return $1; } } }
This Perl code defines a subroutine discover_tb. Given a URL, it attempts to discover the TrackBack Ping URL corresponding to that URL. If it finds it, it returns the TrackBack Ping URL; otherwise it returns undef
.
Changes
1.1 (October 10, 2002)
- TrackBack pings should now be sent using HTTP POST instead of GET. The old behavior is deprecated, and support for GET will be removed in January 2003.
- In the RDF, the TrackBack Ping URL should now be stored in the trackback:ping element, rather than rdf:about.
- Changed the format of the sample TrackBack Ping URL to use the PATH_INFO instead of the query string.
- The embedded RDF used for auto-discovery no longer causes pages to fail validation.
- Added sample code for auto-discovery.
1.0 (August 28, 2002)
Initial release.
Credits
Thanks to Paul Prescod and others for their guidance on making TrackBack more REST-like.