The PBwiki Developer API

NOTE: The basic API is live on our servers, but you will need to email api@pbwiki.com to ask us to enable your wiki for the API. While the documentation on this page closely resembles what is available on production, it may actually be slightly ahead of our production service in some cases.

Mailing List

Subscribe to PBwiki API Hackers

Email:

Visit this group

Notes

The below are the first sketches of the API. There are two separate ways of calling the API. One is done with a special shared secret key as is appropriate for a server-hosted script and the other uses a user's existing login session as is more appropriate for a wiki extension or browser plugin.

API Key Access

If using the API Key authentication mechanism, you will need to generate an API key in the "API" section of your wiki's administrative interface. Only the administrator of a wiki can enable API access, and even then only if their wiki is authorized to use the API and the administrator has agreed to the API's Terms of Service. Once you have an API key, you must provide the GET parameter "apikey_v1" set to the API key assigned to you to every call. If this parameter is not set or does not match the API key for the wiki or the wiki does not have API access enabled, the request will be denied with HTTP code 401 (Unauthorized). Additionally, if you fail to provide a function name, you'll get an HTTP 400 ("Bad Request").

If the PBwiki system is down, you may not receive any response at all, or an HTTP 503 ("Service Unavailable"). You may (rarely) get an HTTP 500 ("Internal Server Error") if our script screws up. If you call a function that we haven't yet implemented, you will get a HTTP 501 ("Not Implemented"). You should be sure to check the HTTP return code on your calls to PBwiki's API.

Parameters are given in simple REST key=value form. All keys and values should be fully escaped. Parameters may be in Unicode, but they must be URI-escaped. Boolean parameters should be set to numeric 0 for false and numeric 1 for true, so "foo=0" means that foo is false. All API calls will be of the form: http://yourwiki.pbwiki.com/api/STYLE/FunctionName?param1=value1

STYLE specifies the object format you'd like the result in; this can be "json", "xml", or "php". Our XML output is a little less elegantly styled than JSON or PHP; variables are given escaped, not in CDATA style. We very strongly recommend you use JSON style output at least for debugging, as it is very easy to examine visually for correctness. All of the examples given in this documentation will first focus on the JSON output. JSON & PHP outputs are returned in an object called "v1". If the "error" or "errorCode" fields of v1 is ever set or the return HTTP code is not 200, the call did not succeed. A possibly-helpful English description will be the string in the "error" field. If you get any 4xx style error back from the API, you should not not continue retry with the same parameters.

Below is an example of a what our JSON return data might look like for a function:

{ "v1": {
  "someString": "foo",
  "someNumber": 5,
  "someList": [ 1, 2, 3, "banana" ],
  "someObject": {
    "objectString": "yadda",
    "objectNumber": 5
  }
}}

The XML equivalent (admittedly horky) is:

<?xml version="1.0" encoding="UTF-8"?>
<pbwapi version="1.0">
<someString>foo</someString>
<someNumber>5</someNumber>
<someList>1</someList>
<someList>2</someList>
<someList>3</someList>
<someList>banana</someList>
<someObject>
 <objectString>yadda</objectString>
 <objectNumber>5</objectNumber>
</someObject>
</pbwapi>

The PHP equivalent is not given here, but the format is documented in the PHP manual.

Wiki Access

The following functions will be used to retrieve information from the wiki.

GetPage - retrieves a given page on the wiki
GetPageHistory - retrieves a page's revision history
GetAllPages - retrieves a list of all pages on the wiki
GetRecentChanges - retrieves a list of recent changes made to the wiki
GetSiteInfo - retrieves site-wide information, such as the title, skin, language, and description for the wiki
GetSiteStats - retrieves statistics associated with the wiki
GetComments - fetches comments attached to the wiki
DiffPage - returns the difference between two page revisions

Wiki Modification

These functions will be used to update information on the wiki. Note that there is no RenamePage function, because in our current system, page renames are a destructive operation, equivalent to copying the current revision of a page to a new page and deleting the old page and revision history. This may be changed in the future.

AddPage - adds a new page to the wiki.
AppendPage - appends information to an existing wiki page. If the page does not exist, it is created
PrependPage - prepends information to an existing wiki page. If the page does not exist, it is created
ChangePage - changes an existing page to the page content posted. It fails if the page is locked for editing by a human
SetPageInfo - updates meta-information about a page, such as whether or not it is adminlocked (requires admin access)
SetSiteInfo - updates site-wide information, such as the title, skin, language, and description for the wiki (requires admin access)
DeletePage - deletes a page and all its revisions (requires admin access)
RevertPage - reverts a page to a prior revision

File Manipulation

These functions manipulate files attached to the wiki.

GetFile - retrieves a file attached to the wiki
GetAllFiles - retrieves the list of all files uploaded
AddFile - creates a file attached to the wiki
DeleteFile - deletes a file (requires admin access)
RenameFile - renames a file (requires admin access)

The Authentication API

The Authentication API lets you run a script which determines who a user is and whether or not they have permission to access the wiki.

It is not an API call itself, but is documented at AuthApi.

Wiki Alerting

These functions will let you be alerted on updates to your wiki.

RegisterCallback - this function registers a URL to be called on all wiki updates

API-ish Other Things

There are a number of facilities we support that are not under the scope of the formal API above. As such, these features are much more likely to change or go away without notice.

ZIP Backups

Every wiki permits the download of ZIP file with the contents of the wiki in raw PBwiki format as a crude way for you to back up your data. We may drop this facility in the future.

Wikilets

You can embed a wiki page in a web page pretty easily, using either an IFRAME or inline-Javascript technique:

You can see more on this technique and
the initial forums post on Wikilets.

Bitty

You can embed PBwiki content in a Bitty Browser as well, using both IFRAME and inline-Javascript techniques:

Server-Side Inlining Public Wiki Content

If SEO matters to you, the HTML that your website generates will need to include the wiki content inline (versus fetched by a client web browser). It's easy to do this with PBwiki, particularly if your wiki is public; here's how to do that in PHP in one line:

Server-Side Inlining Private Wiki Content

For this, you'll need to set up an API key for the wiki you'd like to selectively republish. Once you have your API key, it's two lines of PHP. (One if you wanted to be clever.)

 Create your own business wiki!Support CommunityPublic, Platinum wiki Privacy Policy RSS