Wikidot Api

(Original Page= http://www.wikidot.com/doc:api)

Notice

This page is kept for historical purposes only. Please visit developer.wikidot.com for updated information about the Wikidot API and for help with using it!

THIS IS A DRAFT

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 for some user. 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 key of user

API key

Users that want to test API, need to have their unique key generated by Wikidot. If you want to have one, comment on this page and ask for one!

Notice

This page is kept for historical purposes only. Please visit developer.wikidot.com for updated information about the Wikidot API and for help with using it!

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.

We will now show how to use Wikidot API with Python (installing Python is out of scope of this document).

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: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', 'site.pages', 'site.categories', 'page.get', 'page.files', 'page.save', 'user.valid', 'user.sites']

If you get an exception instead:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/lib/python2.5/xmlrpclib.py", line 1147, in __call__
    return self.__send(self.__name, args)
  File "/usr/lib/python2.5/xmlrpclib.py", line 1437, in __request
    verbose=self.__verbose
  File "/usr/lib/python2.5/xmlrpclib.py", line 1191, in request
    headers
xmlrpclib.ProtocolError: <ProtocolError: 401 Unauthorized>

… this means, that probably you supplied wrong API key.

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 site.pages, just issue:

>>> s.site.pages({'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 category system, issue:

>>> s.site.pages({'site': 'my-wiki', 'category': 'system'})

The order of keys in array is irrelevant.

If you are an administrator of this site, you'll get the list of pages.

Each item in the resulting list is a dictionary (associative array) of different properties of pages. This is another convention. Each return value in Wikidot XML-RPC API is a dictionary or list of dictionaries. Keys should be self-explanatory.

An example result of the previous command:

>>> s.site.pages({'site': 'my-wiki', 'category': 'system'})
[{'category': 'system',
  'date_created': '2009-01-12T23:12:13+00:00',
  'date_edited': '2009-01-12T23:12:13+00:00',
  'full_name': 'system:join',
  'name': 'join',
  'parent_page': None,
  'site': 'my-site',
  'tag_array': ['some-tag', 'other-tag'],
  'tag_string': 'some-tag other-tag',
  'title': 'How to join?',
  'title_or_unix_name': 'How to join?',
  'title_shown': 'How to join?',
  'user_created': 'Some user',
  'user_edited': None},
 {'category': 'system',
  'date_created': '2009-01-12T23:12:13+00:00',
  'date_edited': '2009-01-12T23:12:13+00:00',
  'full_name': 'system:members',
  'name': 'members',
  'parent_page': None,
  'site': 'my-site',
  'tag_array': [],
  'tag_string': '',
  'title': 'Members',
  'title_or_unix_name': 'Members',
  'title_shown': 'Members',
  'user_created': 'Some user',
  'user_edited': None}]

For example, you can save the list to a variable and use a loop, to print a title and tags of each page:

>>> pages = s.site.pages({'site': 'my-wiki'})
>>> for page in pages:
>>>     print page['title'], page['tag_string']

As you see, we supply various formats for field tag. Also there are as much as three different title fields:

  • title: the title set by user
  • title_or_unix_name: the title if not empty, the unix name otherwise
  • title_shown: the title shown. This includes autonumbering pattern

At most cases these three will be the same unless the title is empty or the autonumbering of pages is enabled.

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

Comments

To apply for testing, please comment!

Notice

This page is kept for historical purposes only. Please visit developer.wikidot.com for updated information about the Wikidot API and for help with using it!

Add a New Comment

Notice

This page is kept for historical purposes only. Please visit developer.wikidot.com for updated information about the Wikidot API and for help with using it!


Bookmark and Share

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License