© Copyright 2002 Stuart Langridge and Ian Hickson.
Pingback is a method for web authors to request notification when somebody links to one of their documents. Typically, web publishing software will automatically inform the relevant parties on behalf of the user, allowing for the possibility of automatically creating links to referring documents.
For example, Alice writes an interesting article on her Web log. Bob then reads this article and comments about it, linking back to Alice's original post. Using pingback, Bob's software can automatically notify Alice that her post has been linked to, and Alice's software can then include this information on her site.
This is a stable specification. Comments are welcome on the blogite mailing list (archived).
There are currently six known separate implementations of this specification, although no formal testing has been done to check how compliant they are:
Authors are encouraged to pingback
http://www.hixie.ch/specs/pingback/pingback to register
their implementations.
The English version of this specification is the only normative version. However, for translations of this document, see http://www.hixie.ch/specs/pingback/translations/. Currently available translations are:
This section was added after the final publication date of the specification.
(2007-01-16) In order to avoid susceptibility to denial of service attacks, pingback servers that fetch the specified source document (as described in section 3) are urged to impose limits on the size of the source document to be examined and the rate of data transfer. Thanks to Blake Matheny for bringing this issue to our attention.
The pingback system is a way for a blog to be automatically notified when other Web sites link to it. It is entirely transparent to the linking author, requiring no user intervention to work, and operates on principles of automatic discovery of everything that it needs to know. A sample blog post involving pingback might go like this:
It enables reverse linking — a way of going back up a chain of links rather than merely drilling down.
The pingback mechanism uses an HTTP header and an HTML or XHTML
<link> element for autodiscovery, and uses a
single XML-RPC call for notifying the target site of the link on the
source site.
It is intended that compliant pingback clients and pingback servers be implementable with minimal effort using libraries typically available in CGI environments. For this reason, the requirements on parsing HTTP headers and HTML documents have been kept to a strict minimum.
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 [RFC 2119].
There are two mechanisms for the automatic discovery of pingback
servers: HTML (or XHTML) <link> elements and HTTP
headers. A pingback-enabled
resource MUST either be served with an X-Pingback HTTP header or contain a
<link> element, or both.
Pingback-enabled HTML and XHTML pages MUST be valid. Clients MAY
refuse to search invalid pages for pingback information.
Note that how the client is told of the source and target URIs is out of the scope of this specification. Typically blogs will extract external links from posts being made to find the target URIs.
Pingback-enabled
resources MAY be returned with a X-Pingback HTTP
header. For example, a PNG image served with the following headers
would be pingback-enabled:
HTTP/1.1 200 OK Date: Sun, 08 Sep 2002 15:05:37 GMT Server: Apache/1.3.26 (Unix) Last-Modified: Thu, 28 Dec 2000 03:18:26 GMT ETag: "65044-15b9c-3a4ab102" Accept-Ranges: bytes Content-Length: 88988 Connection: close Content-Type: image/png X-Pingback: http://charlie.example.com/pingback/xmlrpc .PNG...
The value of the X-Pingback header MUST be the
absolute URI of the pingback XML-RPC server.
Pages MUST NOT include more than one such header. HTML and XHTML
documents MAY include a <link>
element in addition to an HTTP header, although this is
discouraged. If included, the header SHOULD have exactly the same
value as the <link> element. In the case of a
discrepancy, the HTTP header SHALL override the
<link> element, however, authors should be aware
that some clients will not process HTTP headers due to limitations
of their environment.
Pingback-enabled resources MUST NOT use the HTTP
Link header for advertising pingback servers. HTTP
Link headers require non-trivial parsing, and were
therefore deemed too heavy-duty for the purposes of pingback server
autodiscovery.
An HTML or XHTML pingback-enabled page MAY contain a
<link> element in one of the following two
forms:
<link rel="pingback" href="pingback server">
<link rel="pingback" href="pingback server" />
If used, the link element MUST match the appropriate form exactly (including the whitespace before the slash, for instance).
Pages MUST NOT include more than one such element, and MUST NOT include such a string matching the pattern described below unless it is intended to be the link element.
The pingback server placeholder MUST be replaced by
the absolute URI of the pingback XML-RPC server. This URI
MUST NOT include entities other than &,
<, >, and
". Other characters that would not be valid in
the HTML document or that cannot be represented in the document's
character encoding MUST be escaped using the %xx
mechanism as described in [RFC2396].
These strict requirements are intended to drastically reduce the requirements on clients implementing server autodiscovery, as it was deemed that requiring clients to implement an HTML parser in addition to an XML parser was a too heavy burden, given how easy it would be for page authors to comply to the restrictions described above.
Pingback clients, given a source URI and a target URI, SHOULD fetch the target URI and follow the following steps to find the pingback server URI.
X-Pingback headers then the first such header's value
should be used as the pingback server URI. Clients MUST examine the
HTTP headers if they are able to. If for some reason the HTTP
headers are not available to the implementation then this step MAY
be skipped, however, implementers should be aware that this will
reduce the usefulness of their application as link elements cannot
be used for resources that are neither HTML nor XHTML, and HTTP
headers are defined to override link elements when they
differ.<link rel="pingback" href="([^"]+)" ?/?>
& for
&, < for <,
> for >, and
" for ").Having extracted this pingback server URI, it SHOULD be used to send an XML-RPC request as described below.
If the there is no X-Pingback header and the regular
expression does not match, then the target in question does not
support pingback as defined by this specification and the client MAY
do whatever it likes. However, it is RECOMMENDED that clients do
not attempt to be more lenient (e.g. by correctly parsing the
HTML and looking for <link> elements that look
like pingback links from an HTML point of view) because this will
lead to some systems recognising the link and others ignoring
it.
Clients MAY optimise the search. For example:
<link> elements may only appear in the
document's head, clients MAY abort when the strings
</head> or <body> are seen
(e.g. if the client reads the content one line at a time).Content-Range header to only fetch the first few
kilobytes of the target URI.Note, however, that these optimisations are prone to being caught out by legitimate documents, for example those having comments containing the strings given above, or those with large inline stylesheets appearing before the pingback link. Authors are encouraged to take these possible optimisations into account when deciding where to place their pingback links.
Pingback clients, having discovered a pingback
server, SHOULD send the server an XML-RPC request with the method
name pingback.ping and two arguments, the source URI
and the target URI respectively. [XML-RPC]
pingback.pingstringstringstring, as described below.Servers MUST respond to this function call either with a single string or with a fault code.
If the pingback request is successful, then the return value MUST be a single string, containing as much information as the server deems useful. This string is only expected to be used for debugging purposes.
If the result is unsuccessful, then the server MUST respond with an RPC fault value. The fault code should be either one of the codes listed above, or the generic fault code zero if the server cannot determine the correct fault code.
Clients MAY ignore the return value, whether the request was successful or not. It is RECOMMENDED that clients do not show the result of successful requests to the user.
Upon receiving a request, servers MAY do what they like. However, the following steps are RECOMMENDED:
To claim conformance to this specification a pingback client MUST support server autodiscovery as described in this specification and MUST correctly send pingback XML-RPC calls.
To claim conformance to this specification a pingback server MUST be able to receive pingback XML-RPC calls and MUST always return results that conform to the allowed return values. Returning detailed (non-zero) fault codes is OPTIONAL.
Note that some pingback servers may not have associated pages.
For example, a pingback gateway server could be standalone, and
other pages would then use the link element to link to this gateway
server instead of providing a server of their own. To claim
conformance to this specification a pingback-enabled
resource MUST have either an HTTP
X-Pingback header or a link
element in order to allow for server autodiscovery.
To claim conformance to this specification a pingback
user agent MUST support server
autodiscovery as described in this specification, MUST correctly
send pingback XML-RPC calls, MUST be able to
receive pingback XML-RPC calls, MUST always
return results that conform to the allowed return
values (returning detailed (non-zero) fault codes is OPTIONAL),
and MUST have either an HTTP
X-Pingback header or a link
element on all potential target pages in order to allow for
server autodiscovery.
Here is a more detailed look at what could happen between Alice and Bob during the example described in the introduction.
http://alice.example.org/#p123, and the URL of the
link to Bob's blog is
http://bob.example.net/#foo.http://bob.example.net/#foo.X-Pingback header, but fails to
find one.<link rel="pingback" href="http://bob.example.net/xmlrpcserver">If this tag had not been contained in the page, then Bob's blog would not support pingback, so Alice's software would have given up here (moving on to the next link found in step 2).
http://bob.example.net/xmlrpcserver:
pingback.ping('http://alice.example.org/#p123', 'http://bob.example.net/#foo')
There ends the work undertaken by Alice's system. The rest of the work is performed by Bob's blog.
http://alice.example.org/#p123
(the site linking to Bob) and
http://bob.example.net/#foo (the page Alice linked
to).http://bob.example.net/#foo is in fact a post on this
blog.http://alice.example.org/#p123 and checks the
Content-Type of the entity returned to make sure it is text of some
sort.http://bob.example.net/#foo (to prevent spamming of
pingbacks).