mediawiki-api
v0.1.8
Published
MediaWiki API Wrapper
Downloads
2
Readme
This is a wrapper library for the Mediawiki API.
This library is woefully incomplete. The only parts implemented were those necessary to collect all the pages in a category and append text to it.
If you need more functionality, file an issue, and it'll get fixed, fix it yourself and send a push request, or use the internal _request method that is explained later in this article.
It is likely that in the future the callback that every function requires will become optional.
Installation
npm install mediawiki-api
Usage
var MediaWikiApi = require('mediawiki-api');
wiki = new MediaWikiApi('your-wiki.org');
All actions happen over HTTP.
Configuration
The only configurable property is ''isBot'', which is true by default.
wiki.isBot = (true || false);
Events
Every function returns an event emitter that will emit three events:
- complete — Called when the request is complete. Gives err and res as parameters.
- error — Called when the request is complete and there is an error.
- result — Called when the request is complete, and there is no error.
An optional parameter after each method is a callback to be called when the complete event is fired.
Functionality
Logging In/Out
Logging in is important for making sure your edits are done under a bot account.
wiki.login(username, password, callback)
Logging out is less important, but it is a good idea not to leave sessions open longer than necessary. You also cannot use the session after the wrapper is closed, so there's little reason not to logout after you are done.
wiki.logout(callback)
Example
Here's an example of logging in and then logging out.
wiki.login('user', 'mysecret', function (err, res) {
if (err) {
console.log(err);
return;
}
// We are currently logged in.
// Do stuff logged in.
wiki.logout(function (err, res) {
if (err) {
console.log(err);
return;
}
// We are now logged out.
});
});
Getting Article Contents
wiki.getArticleContents(article, callback)
article is the title of the article or the article id.
Only one article should be sent. A request for multiple articles will return only one article in an arbitrary fashion.
The contents of the article is a plain old string.
Editing Pages
wiki.edit(article, body, callback)
The article can be either a string for the page name or a number for its id.
The body can contain all of the parameters found at https://www.mediawiki.org/wiki/API:Edit. Even so, it requires one of the following properties: text, appendtext, prependtext
If appendtext or prependtext are set, then the text parameter is ignored.
The edit token and md5 verification are automatically handled for you.
Edits done by this method will not create new pages, or restore deleted pages.
Getting Category Members
wiki.categorymembers(category, query, callback)
You can pass any parameter that starts with 'cm' into the query, but don't include the 'cm' in it. This query is limited to 50 by default. The results are not cleaned up, and you'll get the raw response.
Example
This script will get the first 500 articles in the Author category in the main namespace, put their titles into an array, and then print the array to the console.
wiki.getCategoryMembers("Author", {
limit: 500,
prop: 'title',
namespace: 0,
}, function (err, res) {
if (err) {
console.log(err);
return;
}
for (page in res.query.categorymembers) {
var article = res.query.categorymembers[page];
output.push(article.title);
}
console.log(output);
});
Searching for Pages
- http://www.mediawiki.org/wiki/API:Search
wiki.search(searchString, query)
You can pass any of the search parameters to query. The query defaults to 5 results. You get an array of results, each result having the following fields:
- ns - Namespace id of the article.
- title
- snippet - Some text on the page.
- size - Number of bytes of the page.
- wordcount - Number of words on the page.
- timestamp - When this information was generated.
Example
This example prints the first ten titles of the search 'Wizard' on the DnD Wiki.
dndwiki = new MediaWikiApi("dnd-wiki.org/");
dndwiki.search("Wizard", {
limit: 10,
what: "text"
}).on("result", function (articles) {
for (var ix = 0; ix < articles.length; ix++) {
console.log(articles[ix].title);
}
});
Unimplemented Functionality
If you use any of the methods described here, file an issue explaining what you used them for.
Tokens
Other than edit tokens being handled by the edit method, you'll need to get and inject the other tokens. The _getToken private method will do that.
wiki._getToken(tokenType, callback)
Generic POST, GET, and Requests
wiki._post(query, body, callback)
wiki._get(query, callback)
wiki._query(query, callback)
wiki._request(query, callback, method, body)
As of right now, there's no function other than the private _request method that can handle things you usually have to be logged in to do.
query is an object representation of the URL parameters. For example, { action: 'query', list: 'categorymembers' cmtitle: 'Category:Author' cmlimit: 50 }
By default, format: 'json' will be added to all queries.
If you use, _query, then the method is get, and action: 'query' is set by default.
callback is explained eariler.
method is the HTTP method. I.E. GET or POST.
body is the body of the message as a JS object. Only use for HTTP methods that have a body.
Final Words
Again, the features that exist here exist because they were needed for a very specific itch. If you need any additional features, they can be added.
If you do queries that are passed the results limit, you'll have to configure the continuations yourself. This might be handled by the library automatically in the future.