Wikidot XML-RPC API

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!

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:[e-mail]/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).

Comments

To apply for testing, please comment!

OK - I will give it a try..

Helmuti_pdorf 1236797854|%e %b %Y, %H:%M %Z|agohover

Hi Piotr,
my python is running …

Can you send me my own unique API Key ?
( PM ?)

---

Service is my success. My webtips:www.blender.org, www.zusi.de (Demo-Video)

Wollen Sie Wikidot helfen im deutschen » Handbuch ?

Fine , it works...!

Helmuti_pdorf 1236841476|%e %b %Y, %H:%M %Z|agohover

I have it running - now I can explore all the methods and functions..

Thanks again!

PS: the example loop printing titles shows me "every second" a page title of my wiki…. :)

PPS: to explain for other user: where I was stopped for a while - is the name giving process for the "user API":

I used "s = ServerProxy('https://helmuti_pdorf:3462.....(my long key)[e-mail]/xml-rpc-api.php')

Not sure - but I think - I have to ,make a "unique name" inside wikidot "xml.rpc-api" . if this is not neccessary - than it does not disturb

---

Service is my success. My webtips:www.blender.org, www.zusi.de (Demo-Video)

Wollen Sie Wikidot helfen im deutschen » Handbuch ?

last edited on 1236932918|%e %b %Y, %H:%M %Z|agohover by Helmuti_pdorf + show more

Please Send Unique Key

ErichSteinboeck 1236876261|%e %b %Y, %H:%M %Z|agohover

> 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!

Please send me my unique key — thanks!

I'd like a key too

Ed Johnson 1237002455|%e %b %Y, %H:%M %Z|agohover

Please send me a key too. I'd like to take a crack at this.

Thanks,
Ed

---

Free Wikidot Applications · Your Shared Photo Gallery · Your Personal Blog

That makes the 4 of us ;D

James Kanjo 1237118475|%e %b %Y, %H:%M %Z|agohover

Yes please!

---

λ James Kanjo | blog | photos | contact

For Windows Users

Ed Johnson 1237215494|%e %b %Y, %H:%M %Z|agohover

I'm having good luck accessing the API with Python v2.6.1 for Windows and Mark Hammond's Python Extensions for Windows.

I installed version 2.6.1 (http://www.python.org/download/) for this reason:

Note that both Python 2.6 and 3.0 are considered stable production releases, but if you don't know which version to use, start with Python 2.6 since more existing third party software is compatible with Python 2 than Python 3 right now.

Mark Hammond's Extensions are available here: http://sourceforge.net/project/platformdownload.php?group_id=78018

Any news on when we might see a working system.methodHelp or other documentation? The examples help, but it's kind of hard to figure things out with limited documentation.

Thanks,
-Ed

---

Free Wikidot Applications · Your Shared Photo Gallery · Your Personal Blog

system.methodHelp

Gabrys 1237216221|%e %b %Y, %H:%M %Z|agohover

We figured out, that what we came across is not a Zend Framework bug, rather a PHP one (we tested on 64 bit Ubuntu, and it worked well). We're not going to fix this, but instead provide better online documentation of methods.

---

Piotr Gabryjeluk
visit my blog

Key

cold_blood3d 1237930942|%e %b %Y, %H:%M %Z|agohover

I'd like to try this!

Some more sample code to help you play around

Ed Johnson 1237951243|%e %b %Y, %H:%M %Z|agohover

As I try to get my feet wet in Python scripting, I have a test script you can tweak to help you get started too. I just took the samples Gabrys provided and modified them until I got some results back with my sites. I'm really looking forward to seeing some working examples from others, especially once we get write access and can really start breaking things! ;)

Unless we have a better place, I think I'll add a section on my site so we can share some code and discuss the API.

-Ed

- show the script -

# 
# Ed Johnson's Wikidot API Python Test Script
# 
print "========== from xmlrpclib import ServerProxy =========="
from xmlrpclib import ServerProxy
print "========== s = ServerProxy('https://ed-johnson:[e-mail]/xml-rpc-api.php') =========="
s = ServerProxy('https://ed-johnson:fc<snip-snip-snip>[e-mail]/xml-rpc-api.php')
print "========== s.system.listMethods() =========="
# print s.system.listMethods()
print "========== s.site.pages({'site': 'my-wd-local'}) =========="
# print s.site.pages({'site': 'my-wd-local'})
print "========== s.site.pages({'site': 'my-wd-local', 'category': 'guide'}) =========="
# print s.site.pages({'site': 'my-wd-local', 'category': 'guide'})
print "========== s.site.pages({'site': 'my-wd-local', 'category': 'config'}) =========="
# print s.site.pages({'site': 'my-wd-local', 'category': 'config'})
print "========== s.site.pages({'site': 'my-wd-local', 'category': 'otherapp'}) =========="
# print s.site.pages({'site': 'my-wd-local', 'category': 'otherapp'})
print "========== pages = s.site.pages({'site': 'my-wd-local'}) =========="
print "========== for page in pages: =========="
print "==========     print page['title'], page['full_name'] =========="
# pages = s.site.pages({'site': 'my-wd-local'})
# for page in pages:
#     print 'Title: ', page['title'], ' --- Full Name:', page['full_name']
print "========== print s.site.categories({'site': 'my-wd-local'}) =========="
print s.site.categories({'site': 'my-wd-local'})
# print "========== s.page.get({'site': 'my-wd-local', 'page': 'guide:installable-iso-and-a-virtual-machine'}) =========="
# print s.page.get({'site': 'my-wd-local', 'page': 'guide:installable-iso-and-a-virtual-machine'})
# print "===================="
# print "= s.page.files({'site': 'my-wd-local', 'page': 'guide:installable-iso-and-a-virtual-machine'})"
# print "===================="
# print s.page.files({'site': 'my-wd-local', 'page': 'guide:installable-iso-and-a-virtual-machine'})
print "===================="
print "= s.user.sites({'user': 'ed-johnson'})"
print "===================="
print s.user.sites({'user': 'ed-johnson'})
print "===================="
print "= s.user.sites({'user': 'gabrys'})"
print "===================="
print s.user.sites({'user': 'gabrys'})
#   '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}]
# THIS IS A DRAFT
# 
# This page describes Wikidot API methods. Read more about Wikidot API...
# 
# The list will grow as the methods are added.
# site.pages(arguments array)
# 
#     * argument keys:
#           o site: site to get pages from, e.g. "my-site"
#           o category (optional): category to get pages from, e.g. "some-category"
#     * returns: list of page_meta
# 
# site.categories(arguments array)
# 
#     * argument keys:
#           o site: site to get pages from, e.g. "my-site"
#     * returns: list of categories
# 
# page.get(arguments array)
# 
#     * argument keys:
#           o site: site to get a page from, e.g. "my-site"
#           o page: page name to get, e.g. "start" or "blog:first-post"
#     * returns: page
# 
# page.files(arguments array)
# 
#     * argument keys:
#           o site: what site we ask about
#           o page: what page we ask about
#     * returns: list of files
# 
# user.sites(arguments array)
# 
#     * argument keys:
#           o user: whose sites to show it can be only your user name
#     * returns: list of sites
#

---

Free Wikidot Applications · Your Shared Photo Gallery · Your Personal Blog

Gabrys 1237970586|%e %b %Y, %H:%M %Z|agohover

Thank you Ed!

---

Piotr Gabryjeluk
visit my blog

Will the API help with this?

Ed Johnson 1238534283|%e %b %Y, %H:%M %Z|agohover

When we get write access to our sites via the API, will we be able to manipulate some or all of the database fields that we can read? This wish got me thinking that the API could help solve this issue.

I'd like to be able to clone a site and then go back and edit the creation date (especially blog entries so they display correctly with PageCalendar).

-Ed

---

Free Wikidot Applications · Your Shared Photo Gallery · Your Personal Blog

me too please

mcgp 1238584131|%e %b %Y, %H:%M %Z|agohover

Hi Piotr,

Me too please

Paul

Please send me my unique key

AjaykumarM 1239352435|%e %b %Y, %H:%M %Z|agohover

Please send me my unique key. I would like to test this API.

Thanks in advance,
Ajay

API unique key

martin_c 1239508740|%e %b %Y, %H:%M %Z|agohover

Would love one -thanks

martin_c…

API Suggestions

ErichSteinboeck 1239738158|%e %b %Y, %H:%M %Z|agohover

While playing around with the new API, I found the following issues and questions:

Topic:

site.pages() and page.get() return {'user_created': None} if the page was created by an anonymous user

Suggestion:

Return {'user_created': 'Anonymous (ip-address)'} instead

Topic:

site.pages() and page.get() return {'user_edited': None} if the page was not edited (at any time, doesn't have to be the latest edit) by an anonymous user

Suggestion:

Return {'user_edited': 'user-name'} of the latest edit instead

Topic:

site.pages() and page.get() return {'user_created': None} resp. {'user_edited': None} if the page was created resp. edited by a user whose account has been deleted in the meantime

Suggestion:

return {'user_created': '(account deleted)'} resp. {'user_edited': '(account deleted)'} instead

Topic:

Methods may return None values for certain keys (e. g. site.pages() and page.get() may return None values for keys 'title', 'title_shown', 'parent_page', 'user_created', 'user_edited', 'tag_string')

Suggestion:

Always returning '' (zero-length string) instead of None would simplify user scripts

Topic:

system.multicall()

Suggestion:

Please provide a working example for system.multicall(). Even after reading the Python MultiCall Objects doc I cannot figure out the correct calling sequence. Properly used, system.multicall() will slash runtime for repetitive calls by a large factor

Topic:

Method page.save()

Suggestion:

system.listMethods() lists page.save() as an available method. Is it already enabled? Please provide a working example

Topic:

Method user.valid()

Suggestion:

system.listMethods() lists user.valid() as an available method. What does it do? Can you provide an example?

i'd like to get a key

pkeane 1239901946|%e %b %Y, %H:%M %Z|agohover

I'd very much like ot get an API key

—peter keane
ude.saxetu.liam|enaekp#ude.saxetu.liam|enaekp

key

wesaq 1240675036|%e %b %Y, %H:%M %Z|agohover

I would like to get a key.

Key

zoobab 1240736176|%e %b %Y, %H:%M %Z|agohover

I also want an API key.

Wiki xml-api

ErichSteinboeck 1241780089|%e %b %Y, %H:%M %Z|agohover

I've started Wiki xml-api to bring together information about the API, Python, code snippets, and scripts as a platform to share information. You're welcome to join.

Notice the UPDATE - methods now in development !

Helmuti_pdorf 1241780600|%e %b %Y, %H:%M %Z|agohover

http://piotr.gabryjeluk.pl/dev:api-save - have a look on the page.save method Piotr describes in his blog!

---

Service is my success. My webtips:www.blender.org, www.zusi.de (Demo-Video)

Wollen Sie Wikidot helfen im deutschen » Handbuch ?

Re: Wiki xml-api

Gabrys 1241788588|%e %b %Y, %H:%M %Z|agohover

Thanks Ed! I would like to make it clear, the Python is only one of possible languages to write applications using the API. In practice any programming language is good, as long as it has good XML-RPC library.

---

Piotr Gabryjeluk
visit my blog

Love python :-)

Iacopo 1242473193|%e %b %Y, %H:%M %Z|agohover

I'd like a key too :-)

key!

tsangk 1242631630|%e %b %Y, %H:%M %Z|agohover

Can I please have the key?

---

First Wikidot Wiki with a Chinese Domain! -> http://曾勁驊.info.tm/ or http://kenneth.wikidot.com

Out of your site limit? I've got 996 sites left. Ask me and I'll create one for you! Just PM me and let me know.^

^{^If you require an Iron Giant Template cloned site, please tell me that too!}

API key and page creation

temariotic 1243166883|%e %b %Y, %H:%M %Z|agohover

Hi, I would like to test wikidot API. Could you send me an API key?

Only a question: has the API the functionality to create new pages in the wiki?

I have an old wiki in wikimedia format, and Id like to, once translated to wikidot format, to add these pages with a batch process.

Thanks in advance

Re: API key and page creation

Gabrys 1243167610|%e %b %Y, %H:%M %Z|agohover

temariotic: API access is now read-only, but we work on create/edit page functionality as well.

---

Piotr Gabryjeluk
visit my blog

Derick 1243537053|%e %b %Y, %H:%M %Z|agohover

Oooh…page creation would be a huge boon. I am using wikidot for review of ~80 conference abstracts which arrive (right now) via e-mail and need to be transferred to pages manually. Would love to be able to write a script for this.

Page creation

Gabrys 1243537561|%e %b %Y, %H:%M %Z|agohover

@Derick: right this is one of so many use cases, we work on it!

---

Piotr Gabryjeluk
visit my blog

Create/edit page feature: release date?

Iacopo 1243838877|%e %b %Y, %H:%M %Z|agohover

Any idea about the release date of this wonderful functionality?

Thanks for the reply.

last edited on 1248033648|%e %b %Y, %H:%M %Z|agohover by Iacopo + show more

Can I get a key?

graphmastur 1244124051|%e %b %Y, %H:%M %Z|agohover

I would love one of those keys too please.

---

"But sanctify the Lord God in your hearts, and always be ready to give a defense to everyone who asks you a reason for the hope that is in you, with meekness and fear;" ~ 1 Peter 3:16

LaBlueGirl 1246310222|%e %b %Y, %H:%M %Z|agohover

@locapo: We're not able to talk release dates at this time, unfortunately. There are several pressing issues we are trying to get out the door, and once we deal with these we can spend more time on perfecting the Wikidot API. While there is no release date set as of this posting, I do know it is something we are currently discussing. It won't be too long now, thanks for being so patient!!

@everyone else who wants a key: If you have not yet received yours, please contact me!!

Thanks!
Rainey

---

Wikidot Support

development key

zadig 1249517420|%e %b %Y, %H:%M %Z|agohover

Hi, could you please give a developer key?
Thanks a lot!

stani 1250090906|%e %b %Y, %H:%M %Z|agohover

I'd like to have a key too.

Help!!

poilini 1250571965|%e %b %Y, %H:%M %Z|agohover

I have just joined and the whole thing has me confused! I just want to play Trivia and to chat is that possible and how do I go about it?

leiger 1250602571|%e %b %Y, %H:%M %Z|agohover

I have just joined and the whole thing has me confused! I just want to play Trivia and to chat is that possible and how do I go about it?

Wrong forum ???

---

— Shane | CycloDS Revolution & Compatibility | Starting a community project? | Life's Handbook | XBL: leiger40

Please, key

dirbaio 1250618560|%e %b %Y, %H:%M %Z|agohover

This looks cool. Please send me a key so I can try it.
but i suggest you give keys automatically so you don't have to send all.
Thanks.

Key

paczor 1253289369|%e %b %Y, %H:%M %Z|agohover

Send me a key, pls.

API key request

uttaran dutta 1255435602|%e %b %Y, %H:%M %Z|agohover

Could I please have the developer Key !!
Many thanks in advance

Set API

uttaran dutta 1255436083|%e %b %Y, %H:%M %Z|agohover

These are get APIs are there any set APIs or any way to modify the page content through the apis ?

Gabrys 1255471233|%e %b %Y, %H:%M %Z|agohover

@uttaran dutta: No, there's no put/post API. Maybe in some time.

---

Piotr Gabryjeluk
visit my blog

Looks very interresting

Eric Saint-Etienne 1255476332|%e %b %Y, %H:%M %Z|agohover

That was the thing missing to wikidot.

I'm in hurry to try it, if you don't mind providing me with the suitable key ^^
Cheers

last edited on 1255476379|%e %b %Y, %H:%M %Z|agohover by Eric Saint-Etienne + show more

api

andrewburton 1256440117|%e %b %Y, %H:%M %Z|agohover

May I have an API key for the ASH wiki?

please sir, can i have a key

atomoil 1258235777|%e %b %Y, %H:%M %Z|agohover

Hi, please can i have an API key?

request api key please

qtfimik 1259355322|%e %b %Y, %H:%M %Z|agohover

Hello! Can I have a key, please? Thank you.

API Key Request

Polley Wong 1260259144|%e %b %Y, %H:%M %Z|agohover

Hi, may I have an API key please? Thank you.