Given that Google has closed its Translate API it is a good time to take a hard look at the Bing Translate API. It also turns out to be interesting as a use of a JSONP Ajax API.

The Bing Translate API is fairly easy to use once you have pinned down exactly the form of API you want to use. It is part of the wider Bing API and this comes in three flavors:

• SOAP
• REST
• JSONP

Yes the same API is packaged in three different ways and you can even select between XML or JSON data.

So which to use?

Unless you have a pressing need to use SOAP my advice is to ignore it. SOAP is over complex, slow and basically a dead technology. It really is a case of only use it if you have a legacy application or implementation policy to respect.

REST is a good second choice because it is easy to use and fits in with the way the web works but it has a number of serious problems. You can't invoke a REST interface cross site. That is you can't build a client that uses REST unless you build a server side redirect or whatever. REST is really a server-to-server API in the sense that it lets your server offer the facilities of another server on another domain.

The only truly client side API on offer is JSONP which not only overcomes the cross site restrictions it also passes back the data in JSON format ready to process in a JavaScript program.

In short JSONP is the idea client side "Ajax" style API and it is the one you should choose unless you really want to build a server side and client side system of programs.

That is you can use the JSONP form of the API from JavaScript with the clients browser without writing any other code.

So how does this work?

JSON

If you already know how JSON/JSONP work feel free to skip to the next section or treat this as a quick refresher.

First JSON.

This is a natural way of packing data as a JavaScript object. It is so natural that it hardly needs inventing or explaining once it has been pointed out to you.

A JavaScript literal object is just a set of names and values. For example:

MyObject={Age:23,Name:"Bill",Sex:"Male"}

You can see that this can be treated at a record of field names and values. This can be transmitted as the result of a query as a string: .

'{Age:23,Name:"Bill",Sex:"Male"}'

and when it is received it can either be parsed as a string or simply interpreted as JavaScript and used to create the object literal.

Once you get the idea you can see that you can also just pass a JavaScript string or an Array object as special cases.

Things get a little more difficult if you throw in security considerations. For example, if you instantiate the JSON object literal using eval, for example:

var JSONresult='{Age:23,
               Name:"Bill",Sex:"Male"}';
var resultObject=eval('('+JSONresult+')');

then you have to worry about what might be in JSONresult - it could be a complete script that does something you wouldn't want it to do.

The solution to the security problem is to restrict the JSON to a simple subset of JavaScript and use special parsing methods to ensure that the string is in this form.

In this application we don't need to worry about implementing a proper JSON framework.

Ok now we understand JSON where does the "P" come into it?

JSONP

For security reasons you can't download XML or JavaScript from other sites using simple Ajax techniques. This is a rule that was created to stop cross-site scripting attacks. However as with all security rules that limit what you can do in a program we simply have to work around it and this is what JSONP is all about.

While you can't download and run JavaScript from another site dynamically you can include it as a script tag in a web page. That is while you can't download JavaScript from OtherDomain you can write:

<Script src="/OtherDomain/OtherScript">
</script>

and the script will be downloaded and run or used by other JavaScript in the page. This is, of course the standard way you get JavaScript libraries and frameworks into your client application.

But this is no good for a dynamic Ajax like request.

How can you use a <Script> tag to get the results of a query made by JavaScript running in the client?

The answer is surprisingly easy - use the DOM.

You can dynamically create a script tag in a page using the DOM to create the corresponding script object. This script object behaves just like the static script tag and can load a script from another site. This is how it has to be because the DOM is supposed to mimic the way tags work in objects.

What this means is that you can get a result back from an external site/domain by just writing some DOM oriented code as long as the external site knows how to make use of it - and this is what JSONP is all about.

For example, to get a simple string back from a site that uses JSONP all you have to do is create a script object that loads JavaScript from the site:

var s=document.createElement("script);
s.src="http://OtherDomain/OtherScript"
document.getElementByTagName(
             "head")[0].appendChild(s);

The first line creates a script object, the second sets the src property to the URL of the script that is going to be loaded and the final line adds the script object to the DOM and hence activates the download.

That is after the appendChild(s) method is obeyed  the script referenced by s is downloaded and executed.

You could arrange for the downloaded script to simply create some global variables but how would your script know that the dynamic script has completed? Much better to specify a callback function. So by convention say we could insist that the dynamically loaded script called MyCallback with the JSON data as the parameter. That is the dynamic script would read:

MyCallback(JSONdata);

That's it - JSONP -  the P stands for "padded" - and that's the function that wraps the JSON data proper.

Of course it would be limiting if the name of the callback function was hardwired into the API but you can code anything you want to in to the URL of the script to be loaded.

So for example you could use:

s.src="http://OtherDomain/
      OtherScript?callback="MyCallback";

To tell the JSONP server the name of the function to pad the JSON with.

You can use the same mechanism to pass any parameters to  the API function and all of the return values are packaged into the JSON and processed by the callback.

Enough theory - how does this work for the Translate API?