WikiPing specifications

These are the specifications for WikiPing. The following is a copy from the original site http://recentchanges.net/WikiPing (no longer active, retrieved from archive.org).

WikiPing specifications

please note that the following specifications are experimental. refer to the wikiping discussion if you have any suggestion how to improve the basic mechanism. whenever the wikiping becomes a standard, this will be announced here.

this specs define how to exchange data with mindWiki's WikiPing server over a xml-rpc interface. WikiPing is a standard to announce changes made in any wiki that supports this standard. therefore the wiki acts as a client that sends an xml-formatted request to a central server (like recentchanges.net), which contains data describing the change and triggers the server to save the description in a database (this is called a "remote procedure call", or short rpc). the xml-rpc engine of this server can be reached with the url

http://recentchanges.net/wikiping/rpc.xml

the wikiping server accepts xml-rpc requests similar to the weblogUpdates.ping introduced by weblogs.com and uses the received data to compile a kind of "global recentchanges" list similar to those lists most wikis provide in a local scope. differing from the weblogs.com specs the wikiping needs named parameters (which are called "structs" in the xml-rpc specification) because most of the fields are optional and thus need to be identified.

if you want to develop a ping agent for your wiki engine, you are encouraged to use the ping server http://sandbox.recentchanges.net/wikiping/rpc.xml until your agent works. the sandbox server responds with more information on the request to ease your debugging task and it is not considered to hold live data. a good starting point may be the sample implementation written in php, which should work "out of the box" for the most wakkawiki clones and hopefully may be traceable for any other wiki engine, as the main structure of a wiki usually only differs slightly.

after your first ping you may visit the recentchanges list to check your fresh entry. the name of your wiki should show up in red (if not, your wiki's name might clash with another wiki, that is already known to the wikiping server). click on the name of the wiki to drop some basic notes about your wiki, its purpose and why the world will be unhappy without it.

the following fields (so far) are recognized by the wikiping server:

tag (required) the name (or title) of the page which has been changed

url (required) the url assigned to that page

wiki (required) the wiki on which the page is hosted

interwikiname (optional) charset for this field is limited to alphanumeric charakters in us-ascii (i.e. [a-zA-Z0-9])

history (optional) an url pointing to the revision-list (page history) of the page

author (optional) name of the editor who performed the change

authorpage (optional) wikipage of the author. most wikis dedicate a wikipage to its registered users on which they can profile themselves. it can either be any url associated with the author.

changelog (optional) some wikis provide a textfield in which the author can drop a short note, that describes what kind of changes have been made.

language (optional) two letter code (iso 639-1) of the used language. it's the first two letters of a locale string.

callback (optional) url of the clients rpc-interface. the presence of this field indicates the capability of the client to serve WikiRPC calls itself. the ping server can "callback" and request additional information using the mind.getProfile method.

fieldnames are case-insensitive, i.e. InterWikiName refers to the same information as interwikiname.

if any of the fields flagged as "required" is missing in the request, the server will drop the request and respond with an error message.

an xml-rpc request with these data looks like this:

<?xml version="1.0"?>
<methodCall>
<methodName>wiki.ping</methodName>
<params>
<param>
<value>
<struct>
<member>
<name>tag</name>
<value>HomePage</value>
</member>
<member>
<name>url</name>
<value>http://mindwiki.de/HomePage</value>
</member>
<member>
<name>wiki</name>
<value>mindWiki</value>
</member>
<member>
<name>interwikiname</name>
<value>mindWiki</value>
</member>
<member>
<name>history</name>
<value>http://mindwiki.de/HomePage/revisions</value>
</member>
<member>
<name>author</name>
<value>sebastian</value>
</member>
<member>
<name>authorpage</name>
<value>http://mindwiki.de/sebastian</value>
</member>
<member>
<name>changelog</name>
<value>just an example!</value>
</member>
</struct>
</value>
</param>
</params>
</methodCall>

if the server doesn't have any complaints with such a request, it will answer with the following xml-response:

<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>error</name>
<value>
<boolean>0</boolean>
</value>
</member>
<member>
<name>message</name>
<value>Thanx for supporting mindwiki's wikiping!</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>

if something went wrong with the request, the boolean value named "error" turns into a "1" and the message field contains details about the error that has been trapped.

<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>error</name>
<value>
<boolean>1</boolean>
</value>
</member>
<member>
<name>message</name>
<value>wiki name required</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>

this message ("wiki name required") indicates that the client didn't send the name of its site (or probably misspelled the field that holds this information in the rpc request).

CategoryReference

Wikka Documentation : WikiPingSpecifications

WikiPing specifications

WikiPing specifications