• Lista tutte le 91 pagine (it)

Per iniziare:

• Wikidot per chi inizia
• Editing per chi inizia
• Creazione del sito

Utenti avanzati:

• Applicazioni avanzate
• Editing avanzato
• Gestione del sito

Terzo livello:

• Controllo degli utenti
• Controllo dei contenuti
• Promozione del sito

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!

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):

>>> fromxmlrpclibimportServerProxy

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月12日T23:12:13+00:00',
 'date_edited': '2009年01月12日T23: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月12日T23:12:13+00:00',
 'date_edited': '2009年01月12日T23: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'})
>>> forpageinpages:
>>> printpage['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!