Many good web applications, and many bad ones, have an API, and my hobby project, RhymeBrain.com, is no exception. The trouble is: the target users of both the web site and the API don't know the difference between Javascript and Java. They don't even know what "A.P.I." stands for. The most they can do is edit some HTML and paste in some code, so that's what my API has to be.

I managed to get it down to that using a technique called JSONP. This technique avoids any problems with cross domain requests, and allows non-coders to use the API using a short, customizable HTML snippet.

Demonstration

Paste this in your web site:

<form action="javascript:RhymeBrainSubmit()"> <input type=text id="RhymeBrainInput"> <input type=submit value="Rhyme"> </form> <script type="text/javascript"> var RhymeBrainMaxResults = 50; </script> <script type="text/javascript" src="http://rhymebrain.com/external.js"></script> Rhyme results are provided by <a href="http://rhymebrain.com">RhymeBrain.com</a>

... and you get this:

How it works

1. The API user pastes a form and reference to a script into their web page.

2. The script inserts some more DIV elements to contain the search results. The DIVs could have been included in the pasted code, but this way is more flexible in case I want to change it later on.

var resultDiv;
document.write("<div id='RhymeBrainResultDiv'></div><div style='clear:both'></div>");
resultDiv = document.getElementById("RhymeBrainResultDiv");

When the user clicks the Rhyme button, this function is called. It creates a special URL that points back to a program on my server. For example, this one: http://rhymebrain.com/talk?function=getRhymes&maxResults=10&word=javascript&jsonp=RhymeBrainResponse. It adds a brand new script element to the end of the document, and sets it source to point back to a program on the rhymebrain server.

function RhymeBrainSubmit()
{
    var input = document.getElementById("RhymeBrainInput");
    var word = input.value;

    $(resultDiv).empty();
    resultDiv.appendChild( img );

    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src = "http://rhymebrain.com/talk?function=getRhymes" +
        "&word=" + encodeURIComponent(word) +
        "&maxResults=" + MaxResults + 
        "&jsonp=RhymeBrainResponse";

    document.body.appendChild(script);
}

3. The server does some super intensive processing involving C, mmap() and 100 MB files, and sends back a response. The response happens to be executable javascript.

RhymeBrainResponse([ {"word":"equipped", "freq":22,"score":"300","flags":"c","syllables":"2"},
 {"word":"manuscript", "freq":22,"score":"300","flags":"bc","syllables":"3"},
 {"word":"script", "freq":21,"score":"300","flags":"bc","syllables":"1"},
 {"word":"shipped", "freq":21,"score":"300","flags":"c","syllables":"1"},
 {"word":"slipped", "freq":21,"score":"300","flags":"c","syllables":"1"},
 {"word":"stripped", "freq":21,"score":"300","flags":"c","syllables":"1"},
 {"word":"dipped", "freq":20,"score":"300","flags":"c","syllables":"1"},
 {"word":"tipped", "freq":20,"score":"300","flags":"c","syllables":"1"},
 {"word":"whipped", "freq":20,"score":"300","flags":"c","syllables":"1"},
 {"word":"gripped", "freq":19,"score":"300","flags":"c","syllables":"1"}]);

4. The browser executes the javascript, which calls the function name that was passed as the jsonp parameter to the script URL. It calls a function which displays the results on the web page.

That's all there is to it. JSONP neatly sidesteps the problem cross domain requests, since script tags can be included from any domain, and it provides a way for non-coders to create mashups.