API

We would like to introduce a new feature for Wikidot users: Wikidot API.

Basic concept

Wikidot API is a way computer programs and automated system can access and interact with Wikidot on behalf of users. Users must "authorize" applications to use their identity by supplying them their unique key Wikidot generates for them.

Technical details

Wikidot API is technically an XML-RPC service, with endpoint being this URL:

https://www.wikidot.com/xml-rpc-api.php

You must use HTTP Basic Authorization with the following credentials:

  • user: the name of application that connects to API
  • password: the unique API key of a user

API key and authentication

API keys are unique and secure strings that:

  1. uniquely identify a user
  2. authenticate a user

If an application uses a user's key, it can act on behalf of the user and have access to sites, pages and eventually all user data.

It is important to share the key only with trust-worthy application, and never share the key publicly. This would be the same as giving someone username and password.

Users may find their API keys at My Account » Settings » API access.

Users can also re-generate the key.

On using XML-RPC service

To use XML-RPC service, you need to have XML-RPC client that is usually a library for a programming language. The language needs to support secure SSL connections too.

We will now show how to use Wikidot API with Python (installing Python is out of scope of this document). Using XML-RPC in other languages is very similar and you can get the idea how RPC works by looking at the code below.

Run Python interactive console:

$ python
Python 2.5.2 (r252:60911, Oct  5 2008, 19:29:17) 
[GCC 4.3.2] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>

You need to import the XML-RPC library for Python (in most cases it is already installed with the default installation of Python):

>>> from xmlrpclib import ServerProxy

Supply the URL, user (application name) and password (your API key) and construct a server object proxy and list all methods, that API provides:

>>> s = ServerProxy('https://your-app-name:your-key@www.wikidot.com/xml-rpc-api.php')
>>> s.system.listMethods()

You should get a list like this:

['system.listMethods', 'system.methodHelp', 'system.methodSignature', 'system.multicall', 'categories.select', 'tags.select', 'pages.select', 'pages.get_meta', 'pages.get_one', 'pages.save_one', 'files.select', 'files.get_meta', 'files.get_one', 'files.save_one', 'users.get_me', 'posts.select', 'posts.get']

Explore the API methods

The full method list is located in a separate document.

Each method gets a dictionary (associative array) as an only parameter. To use pages.select, just write:

>>> s.pages.select({'site': 'my-wiki'})

{'site': 'my-wiki'} is a dictionary with one item labeled site with value "my-wiki". In Wikidot API passing this dictionary to method site.pages means that you want to get pages of wiki my-wiki.

To get only pages in categories system and _default, write:

>>> s.pages.select({'site': 'my-wiki', 'categories': ['_default', 'system']})

If the site has API access enabled for you, you'll get the list of pages.

An example result of the previous command:

>>> s.pages.select({'site': 'my-wiki', 'categories': ['_default', 'system']})
['system:join', 'system:members', 'system:list-all-pages', 'system:recent-changes', 'system:page-tags', 'what-is-wiki', 'how-to-edit-pages', 'start', 'contact']

You can use pages.get_meta method to get meta-information about a few pages (up to 10):

>>> pages_info = s.pages.get_meta({'site': 'my-wiki', 'pages': ['system:join', 'system:members', 'system:list-all-pages', 'system:recent-changes', 'system:page-tags', 'what-is-wiki', 'how-to-edit-pages', 'start', 'contact']})
>>> for page_name in pages_info:
>>>     page_info = pages_info[page_name]
>>>     print page_name, page_info['title'], page_info['tags']

We're using the way pages.get_meta returns information about pages. The return value is a dictionary of pages (key being page name, value being a dictionary of its properties, like title of tags). You can get the source of a page by calling pages.get_one method and extracting content property:

>>> page = s.pages.get_one({'site': 'my-site', 'page': 'system:recent-changes'})
>>> print page['content']
[[module SiteChanges]]

Using languages other than Python

To use the API in Ruby you need to set a configuration option on XML-RPC library to let it support the <nil/> value, that we use (that is an extension of XML-RPC).

There is a Ruby library called wikidot-api that wraps XMLRPC methods for convenience. Take a look at http://github.com/michalf/wikidot-api