Libraries have been developed by community members in the following languages. Click on the member's name for each library's home-page.
Java
— by leiger
Javascript
— by tsangk
— by Gabrys
PHP
— by Jerad Whitaker
Python
— by rurwin
Watchers
... and more
We want to make some cleanups in API methods. New methods (that'll override old ones) are published here:
http://www.wikidot.com/doc:api-methods-v2
The methods are not implemented, this is just a draft.
Piotr Gabryjeluk
visit my blog
I prefer the old style where dog.bones lists all bones for a specified dog, and bone.bury buries a specified bone. The v2-API seems to be missing that orthogonality. For example page.select operates on all pages, and to list categories it is site.categories but to list pages it is page.list.
| Methode | Result | |
|---|---|---|
| get.site(my_site) | ALL Site information | |
| SUBMethode | Result | |
| get.site | .categories(my_site) | List of all categories for site |
| get.site | .title(my_site) | Title of site |
| get.site | .tags(my_site) | Sitetags not to confuse with pagetags |
| get.site | .policy(my_site) | Returns Open-closed-private |
| get.site | ….(my_site) | Returns any possible thing that can be set by the MA of a site and wich can be found in the admin:manager |
| set.site.xxx(my_site,value) | SET SOME Site information as described as submethodes from the GET-methode | |
| SUBMethode | Result | |
| set.site | .policy(my_site) | can change the policy of a site |
| set.site | .title(my_site) | can change the title of site |
| get.category() | a dictinionary of information of all the metadata of the pages in a category | |
| SUBMethode | Result | |
| get.category | .total() | wich would return the amount of pages for a certain category |
| get.category | .titles() | wich would return the titles of pages for a certain category |
I am thinking of more things but before I document all this… I would like some reactions
get.page
write.page
A - S I M P L E - P L A N by ARTiZEN a startingpoint for simple wikidot solutions.
How about a page delete methode?
A - S I M P L E - P L A N by ARTiZEN a startingpoint for simple wikidot solutions.
If there's a page delete method, I'd want a way to disable that on a per-site basis.
Site manager changes & deleting pages is irreversible, and therefore if it's to be usable in the API it should be possible to disable it as well.
Also want a way to enable notifications. It's frustrating not getting notifications when the API is used to modify a site. Would rather get several thousand emails than none :(
~ Leiger - Wikidot Community Admin - Volunteer
Wikidot: Official Documentation | Wikidot Discord server | NEW: Wikiroo, backup tool (in development)
Methode "source.get". I think it would be usefull to be able to only get the page-source from a page. If changes need to be made to a page that firstly needst to be checked of the current content. This methode will make checking unnessecary content like side-bar and top-bar and other stuff superfluous.
A - S I M P L E - P L A N by ARTiZEN a startingpoint for simple wikidot solutions.
I agree, it is absolutely vital to be able to fetch the Wikidot source. I hadn't realised that was missing.
It's definitely possible to get the source code of a page - so it isn't missing. However, what is missing is the ability to fetch only the source code and ignore the other data about a page.
At the current point in time you can fetch a whole page and get all meta data, source code, etc at once. If all you want is the source code, then this is slightly inefficient as you are transferring data that you have no intention of using.
~ Leiger - Wikidot Community Admin - Volunteer
Wikidot: Official Documentation | Wikidot Discord server | NEW: Wikiroo, backup tool (in development)
After reading this thread, we decided to make API methods more consistent.
The convention used now is:
The updated documentation is at the previous place: http://www.wikidot.com/doc:api-methods-v2
Piotr Gabryjeluk
visit my blog
And thank you for listening.
The new draft is a lot more orthogonal, thanks for that.
The use of "-" for a blank parent seems odd, since on the site a blank parent would be "", but it will be easy enough to get used to and easy enough to special-case in code. However I notice that the output parameters from page.get_meta and page.get_one do not use the same convention. I am glad to see that the output parameters of page.get_meta match the input parameters of page.save_one; that is an improvement over v1.
One thing that is missing (so far) is a method to fetch all the meta-data for all pages on the site. Perhaps you will forgive me if I pontificate on the subject for far too long.
Since all XML-RPC calls take at least a second, it is very useful to be able to cache all the page names, tags and parents with a single call. One important real-world use-case for the API is in making batch changes to very large sets of pages. For example Steven and I recently re-parented 1,323 pages using the API. In such a large list there are sure to be mistakes, and we need to put checks in place to protect against creating pages by accident, re-parenting pages that already have parents, tagging pages with contradictory tags, and so forth. Fetching the meta-data every time we change a page will halve the speed of the program. I can see you have added parameters and methods to reduce the need for fetching all the meta-data, but is it so much quicker to do an intelligent, ordered selection and return just the page names, as opposed to just dumping out all the meta-data for all the pages? I can do the intelligent selection, including the ordering, in Python. I can even calculate an inverse relation on the parent names and a union of the tags. All of that will be quicker than fetching the data via XML-RPC, and quicker by some orders of magnitude. It is nice to have pages.select, but I estimate that any program that calls it twice will be slower than a program that uses the v1 site.pages intelligently. I'm not qualified to judge the implications for server load, but I would expect the ordering and selection process to negate any advantage in producing a smaller output data-set.
I understand your point, but we need to have a control on total maximum time spent in every method call.
As I understand, the prefered sulotion to fetch all metadata, would be like this:
def get_all_pages_meta(s, site): """s: XML-RPC proxy, site: name of the site""" meta = {} pagenames = s.pages.select({"site": site}) for i in range(0, (len(pagenames) - 1)/10 + 1): tmp_meta = s.pages.get_meta({"site": "your-site", "pages": pagenames[i*10 : i*10+9]}) for page in tmp_meta: meta[page] = tmp_meta[page] return meta
Getting metadata in chunks (in 10s in this example) is equivalent of running ListPages (perPage=10). It also scales better with concurrency than it would with pages.get_meta with no limit in number of pages to fetch meta data from.
Piotr Gabryjeluk
visit my blog
I hope you realize getting all meta data of all pages in a site IS a huge operation, so don't expect it'll take anything less than quite long.
Imagine 100 people ask for all metadata for their sites and then ignore the response (because it takes too much time). Server would need to generate the response anyway (for all of them) so everything would slow down. This is why we aim at API methods being from design limited in time, so that even if it's not used by client, servers only do a constant amount of unneeded work.
Also with separate select and get_meta we avoid pagination on the server-side, which can be very tricky when pages are added/deleted during the server-client conversation.
So to sum things up, the API will be very simple at the server part, so that it's perfectly manageable and very reliable. Client software will be only a bit more complicated (but hiding these complications is a task for wikidot-rpc libraries in our opinion).
Hope this is acceptable for you (and everyone else).
One more thing, could you elaborate on how get_one is inconsistent with get_meta in terms of returned value?
Piotr Gabryjeluk
visit my blog
They are consistent, but not with pages.select etc. get_one returns a blank parent as None, according to your example, whereas pages.select and pages.save_one use "-".
pagename = ... thepage = api.pages.get_one({"site":"mysite", "page":pagename}) ... # modify thepage ... # Annoying extra code to change the blank parent form if thepage.parent_fullname == None: thepage.parent_fullname = "-" api.pages.save_one({"site":"mysite", "page":pagename, "title": thepage.title, "tags":thepage.tags, "source":thepage.source, "parent_fullname":thepage.parent_fullname})
Ah, I see, the problem is that you have two meanings of "empty" parent, that you need to distinguish from when passing to the API:
When getting data from API, there's no such thing, so nil is used as universal value for "nothing".
Piotr Gabryjeluk
visit my blog
To be more consistent, I changed "category" selector in pages.select to "categories" (so far in documentation only).
Also, I introduced basic methods for fetching page comments.
As a loose rule — if a method has a line between its name and argument keys saying what it does (in the documentation), it means it's implemented. This comes from the fact I'm documenting the methods in the code (the same description is available via system.methodHelp("name.of.method")) and I also copy the description to the documentation.
Piotr Gabryjeluk
visit my blog
