Utility Mill

The Utility Mill API!

It's experimental, be warned

This is the first instance of the API and I really don't know much about what I'm doing so I can't guarantee that nothing will change. Eventually the API will get finalized and you can code against it with abandon, but for now, be prepared to have to have the ground shift under your feet a bit.

I don't have a huge amount of server resources right now, so please drop me an email if you're planning to use the API for anything with huge potential volume and we'll figure out the best plan for you.

There are two different ways to use the API. There's a simple RESTful XML API, and a RESTful JSON API:

• XML API
• JSON API

How Can I Help You?

I'm open to adding more functions. Perhaps you'd like a function to get a list of all utilities a user has improved? Perhaps you'd like to get an actual HTML form for a utility returned? Just let me know.

Other Options for Connecting

I'll be adding RSS feeds soon and utility widgets you can put onto your own website will be coming down the road eventually.

XML API

This API works pretty simply. You just load a URI and get XML returned to you.

Functions Available

Here are the functions available and how to call them.

Run Utility

Use this function to actually run a utility. Inputs shoud be provided via a query string. Use the URI: http://utilitymill.com/api/xml/utility/[utility name]/[revision number]/run?[query parameters]. An example for the Text_Diff utility is http://utilitymill.com/api/xml/utility/Text_Diff/7/run?LABEL1=Old&TEXT1=some+text&LABEL2=New&TEXT2=some+more+text&OUTTYPE=HTML (click previous link for sample output.)

List Utilities

Use this function to get a listing of all utilities with the following information provided for each utility: utility names, short desc., founding user, last updated date, and number of runs. Use the URI: http://utilitymill.com/api/xml/utilities/list. Click here to see the output: http://utilitymill.com/api/xml/utilities/list

Get Utility Code

Use this function to get the source code for any utility. Use the URI: http://utilitymill.com/api/xml/utility/[utility name]/[revision number]/code. An example for the Miller_Rabin_Primality_Test utility is http://utilitymill.com/api/xml/utility/Miller_Rabin_Primality_Test/6/code (click previous link for sample output.)

Get Utility Info.

Use this function to get information about the latest revision, and the inputs for any utility. Specifically you get the latest revision's number, user, and date. For each input you get its variable name, input type, default value, and the drop down values if any. Use the URI: http://utilitymill.com/api/xml/utility/[utility name]/info. An example for the Text_Diff utility is http://utilitymill.com/api/xml/utility/Text_Diff/info (click previous link for sample output.)

XML API Sample Client Program

Here is a simple Python program to find out the latest revision of the Text_Diff utility and print the source code to the screen. (Sorry I couldn't think of a more exciting example!)

import urllib2
from xml.dom.minidom import parseString
UTILITYNAME='Text_Diff'
#Get latest revision
raw_xml=urllib2.urlopen(
    r'http://utilitymill.com/api/xml/utility/%s/info' % UTILITYNAME
    ).read()
xmldoc=parseString(raw_xml)
revision==xmldoc.getElementsByTagName('number')[0].firstChild.nodeValue
#Get Code
raw_xml=urllib2.urlopen(
    r'http://utilitymill.com/api/xml/utility/%s/%s/code' % (UTILITYNAME,revision)
    ).read()
xmldoc=parseString(raw_xml)
code=xmldoc.getElementsByTagName('code')[0].firstChild.nodeValue
print code

JSON API

The JSON API has the same functions as the XML API and nearly the same URI's. Again you just load a URI and get JSON returned to you.

Functions Available

Here are the functions available and how to call them.

Run Utility

Use this function to actually run a utility. Inputs shoud be provided via a query string. Use the URI: http://utilitymill.com/api/json/utility/[utility name]/[revision number]/run?[query parameters]. An example for the Text_Diff utility is http://utilitymill.com/api/json/utility/Text_Diff/7/run?LABEL1=Old&TEXT1=some+text&LABEL2=New&TEXT2=some+more+text&OUTTYPE=HTML (click previous link for sample output.)

List Utilities

Use this function to get a listing of all utilities with the following information provided for each utility: utility names, short desc., founding user, last updated date, and number of runs. Use the URI: http://utilitymill.com/api/json/utilities/list. Click here to see the output: http://utilitymill.com/api/json/utilities/list

Get Utility Code

Use this function to get the source code for any utility. Use the URI: http://utilitymill.com/api/json/utility/[utility name]/[revision number]/code. An example for the Miller_Rabin_Primality_Test utility is http://utilitymill.com/api/json/utility/Miller_Rabin_Primality_Test/6/code (click previous link for sample output.)

Get Utility Info.

Use this function to get information about the latest revision, and the inputs for any utility. Specifically you get the latest revision's number, user, and date. For each input you get its variable name, input type, default value, and the drop down values if any. Use the URI: http://utilitymill.com/api/json/utility/[utility name]/info. An example for the Text_Diff utility is http://utilitymill.com/api/json/utility/Text_Diff/info (click previous link for sample output.)

JSON API Sample Client Program

Here is a simple JavaScript example to put up an alert box showing the names and number of runs of the top three most popular utilities. Run it Now!

<html>
<head></head>
<body>
<script>
function loadstuff() {
    //First load the desired Utility Mill URI as a script
    var script = document.createElement('script');
    script.setAttribute('src','http://utilitymill.com/api/json/utilities/list');
    script.setAttribute('id', 'jsonScript');
    script.setAttribute('type', 'text/javascript');
    document.documentElement.firstChild.appendChild(script);
}

function show_top_three() {
    //write a function to compare utilities by num runs to use for sorting
    function compare(a,b) {return parseInt(b.numruns)-parseInt(a.numruns);}
    UtilityMill.sort(compare);
    //Tell us the names of the top three:
    for (var i=0; i<3; i++) {
        alert(UtilityMill[i].name + " with " + UtilityMill[i].numruns + " runs");
    }
}
loadstuff();
//We now have a new global variable UtilityMill holding all the JSON
</script>
<p onclick="show_top_three();">Show top 3</p>
</body>
</html>