QUESTO E' UN PROGETTO
Siamo lieti di introdurre una nuova funzionalità per gli utenti di Wikidot: Wikidot API.
Concetto base
Le Application Programming Interface API (Interfaccia di Programmazione di un'Applicazione), sono insiemi di procedure disponibili al programmatore, per un determinato compito.
Le API permettono di evitare ai programmatori di scrivere tutte le funzioni partendo da zero.
Ad esempio, se si volesse far comparire a video la scritta "ciao mondo", si dovrebbe programmare il disegno e la gestione delle singole lettere "c" "i" "a" "o" … Utilizzando una API già predisposta allo scopo invece, sarà sofficiente inserirla nel corpo del nostro programma.
Naturalmente, per poter essere utilizzate da tutti, le API debbono seguire uno "standard" e, soprattutto, debbono essere distribuite liberamente dal programmatore.
API in Wikidot
Wikidot API è un modo con cui programmi per computer e un sistema automatizzato possono accedere ed interagire con Wikidot . Gli utenti debbono "autorizzare" le applicazioni fornendo l'unica chiave generata per loro da Wikidot.
Dettagli tecnici
Wikidot API tecnicamente è un servizio XML-RPC , con questo URL all'endpoint:
https://www.wikidot.com/xml-rpc-api.php
XML-RPC è un protocollo utilizzato in informatica che permette di eseguire delle chiamate a procedure remote (RPC) attraverso la rete Internet.
Nonostante la sua semplicità permette di trasmettere strutture dati complesse, chiederne l'esecuzione ed avere indietro il risultato.
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!
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!
