API for Firefox Extensions

Our latest Firefox add-on includes an API that other Firefox extensions can use to easily determine the safety of a website, as briefly mentioned in the announcement. This post documents the interface and gives some examples on using it from your extension. Unless you are a programmer working on a Firefox extension, continuing beyond this point presents a severe danger of being bored.

The API uses the same rating data you see on the add-on, but makes it friendlier for the caller by also taking care of interpretation. Basically, extension developers should see this as a huge people-driven whitelist of safe websites, which can be helpful when deciding whether to enable certain features for a site, for example. Your users can easily manage the whitelist by giving their own ratings using the rating window, thus overriding any ratings from WOT. For example, if the community considers a site to be safe, but the user has rated it dangerous, the API tells you the site isn’t safe.

For simplicity, the API is available as a JavaScript object on the browser window. You can look for its presence by checking if the wot_extapi function has been defined. If it is, you can instantiate the API object as follows:

  var api = null;

  if (typeof(wot_extapi) == "function") {
      api = new wot_extapi();
  }

The wot_extapi object defines a single function called getstatus and a number of return codes as described in the following pseudocode:

  wot_extapi.prototype =
  {
      STATUS_EXCELLENT:    ...,
      STATUS_GOOD:         ...,
      STATUS_UNTRUSTED:    ...,
      STATUS_UNAVAILABLE:  ...,
      STATUS_AGAIN:        ...,

      getstatus: function(target, callback) {
          ...
      }
  };

You can pass the getstatus function either a full URL or simply a host name for the site whose trustworthiness you want to determine, and it immediately returns with one of the status values.

One thing that complicates the API is that ratings may not be cached when you request them, or the WOT add-on has already requested them from our servers and is still waiting for the results. The getstatus method handles requests asynchronously instead of blocking, and you can pass it an optional callback function as a parameter, which gets invoked once the ratings are available. The behavior is then:

• If ratings aren’t available for the site or the extension was unable to retrieve them, the method returns STATUS_UNAVAILABLE.
• If ratings are cached, the method returns STATUS_EXCELLENT if the overall rating is excellent, STATUS_GOOD if it’s good, or STATUS_UNTRUSTED if the ratings are worse or not available in any of the three components. If a callback function is provided, it is invoked with the same status value.
• If ratings are not cached, the method returns immediately with STATUS_AGAIN and the WOT add-on starts a request to our servers in the background. If you supply a callback function, it will be invoked with the status value once the ratings are available. If no callback function is given, you will have to poll getstatus again later to see if the ratings are available.

In other words, after you instantiate the API object, the easiest way to use it is like this:

  api.getstatus(url, function(status) {
        if (status == api.STATUS_EXCELLENT) {
            /* do something */
        }
    });

You can download sample source code for a trivial, but truly annoying Firefox extension that uses the API to constantly bother you with dialogs about site safety. Enjoy!