• If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • You already know Dokkio is an AI-powered assistant to organize & manage your digital files & messages. Very soon, Dokkio will support Outlook as well as One Drive. Check it out today!

View
 

Blog200612310331

Page history last edited by PBworks 17 years, 2 months ago

 

 

Blog List All Entries Archives by Month Photos My Notes

 

 

Introduction to the PBwiki API
3:31am December 31, 2006

 

 

NOTE: The entirety of this blog post is in the foreign language of Hackerese. If you don't speak Hackerese, I suggest you run far far away and wait for my next post.

 

Introduction

 

So I've spent the last week or so honing my AJAX skills on the PBwiki API. It has its share of ups and downs, which I'm going to discuss momentarily along with some of the successes I've had along the way.

 

The PBwiki API itself is documented here. It's incomplete, and as far as I can tell, hasn't been updated for a few months, but that's quite alright. I'm mostly understanding and sympathetic to the idea that a wiki farm run by three guys, of whom only two are programmers, is going to be a little slow in updating certain things. Between trying to minimize the network load, unveiling and debugging the new wysiwyg interface, and undoubtedly working on the next iteration of our favorite wiki, developer tools are going to be low on the totem pole.

 

What is there is interesting, though, and more than sufficient to begin to realize some possibilities. Furthermore, David Weekly has done a good job of keeping the documentation ahead of production a little, allowing us to see what functions will eventually show up. With all this in hand, I decided to push the limits of my Javascript ability and envision the client-side possibilities.

 

A General Idea of API's

 

What's an API, you ask? An API is an Application Programming Interface, or a way for two programs or scripts to talk to one another. Most web-based API's, such as PBwiki's or Yahoo's UI tools, exist as a number of functions that can be called through an HTTP request (how your browser retrieves web pages). The PBwiki API, for example, currently has functions to read/write pages and files, get listings of pages and files, verify a user's access to the API, etc.

 

The API is run like most others, with either XML and JSON formatting and all that fun stuff. I'm dealing exclusively with the JSON formatting for now (click the link if you need to learn more), as it's simpler to handle and all you have to do is eval() it. JSON formatting also has another useful trick, which I will also discuss probably in the next post about this.

 

The basic gist is this: the API provides a number of calls which can be used to request specific data from a wiki or to perform specific actions, and then, in my case, some client-side script handles the data. Everything from reading a wiki page to writing a text file is possible (as long as the API function has been written). Here are a few possibilities (but by no means all of them):

 

  1. Read a page into a text window, edit it, and save again.
  2. Create dynamically generated data custom-made for users/readers.
  3. Obtain the file/page list as an array and create a page that displays it nicely
  4. Append some data to a page (useful for a blog)
  5. Get the recent changes and tailor a page around the information, to your specification

 

To use the API, your wiki must first be API-enabled, which is as simple as asking one of the PBwiki guys to enable it for you. Access to the API is currently restricted to either those who are logged in to their wiki (PBwiki is contemplating opening read only functions up to anyone who can view a wiki) OR those who use that wiki's apikey. The apikey is a special number that allows anyone access to the API. As such, it's not particularly useful in a client-side/JS setting, as anyone viewing the source could get the apikey and hack away. The exception to this is a wiki that is completely accessible to the public anyway, such as a public test wiki like this one.

 

An Example

 

The best way to explain this is with an example. Imagine going to the following URL:

 

http://somewiki.pbwiki.com/api/json/GetAllFiles?&apikey_v1=123456

 

You'd see on your screen a text output looking something like this:

 

{"v1":{"files":["words.txt","music.mp3"]}}

 

However, accessing it like this is rather useless. Instead, we need to somehow retain it in a variable that we can manipulate. We do that with XMLHttpRequest, a JS object that fetches the data at the given url, and through some code that you can easily steal after a few Google searches (or by looking at the source of this demo page, returns your request as either straight text or XML.

 

So, let's say you get it as text. Since this is json, you can eval() it and get an object:

 

//some code that returns a response in xmlHttpObj

var myObject = eval('(' + xmlHtppObj.ResponseText() + ')');

//use myObject
alert( myOBject.v1.files[0] );  //alert output: "words.txt"

 

And then you're free to use the data as you see fit.

 

A large advantage ofusing XMLHttpRequest is that you can tailor the url (and thus the parameters of the call) dynamically. For example, I could do this:

 

var filename = 'words.txt';
var url="/api/json/GetFile?name=" + filename;
doXMLHttpRequest(url)

 

where doXMLHttpRequest() is a function handling all the sordid details of the object. It's really a simple and powerful technique.

 

 

Closing for now

 

So thats the absolute basic version of Javascript access to the API. Making one call like that is pretty easy, but if you don't get it yet, you should study the code here for a while. In a later entry, I'll discuss some of the things I'm doing to make the API easier to work with without reinventing the wheel every time, but it's always nice to know the basics.

 

 

 

 

 


 

Umino pic from the Sailor Moon manga.

 

 

Permalink | | Top

 

 

 

 

Content (c) Jason Nguyen 2006

 

Comments (0)

You don't have permission to comment on this page.