I just looked through the API of Microsoft’s new Bing search (which is really a re-branding of the live search – also, switch to “low bandwidth view” to be able to use the docs much more smoothly) and I found an interesting step in protecting code from throwing errors.
When you provide a JSON output for developers it does make sense to also allow for a callback parameter. That way your code can be used in script nodes without having to use any backend at all. If you for example provide an API to return the names of the Beatles you could have a data endpoint like getBeatles and a parameter for output format:
http://example.com/API/getBeatles?output=json
The return data then will be:
{
“members”:
[
‘Paul’:{ ... more info … },
‘Ringo’:{ ... more info … },
‘John’:{ ... more info … },
‘George’:{ ... more info … }
]
}
This I cannot use in JavaScript without hacks. I’d need to eval (or to be safe JSON parse) the results and with conventional Ajax I cannot reach data outside my domain. To make JSON work as easy as possible you can provide a callback parameter.
http://example.com/API/getBeatles?output=json&callback=eleanorRigby
This should wrap the code in a function call which means the output is already evaluated and the user has to define a callback method to read that information. The output would be:
eleanorRigby({
“members”:
[
‘Paul’:{ ... more info … },
‘Ringo’:{ ... more info … },
‘John’:{ ... more info … },
‘George’:{ ... more info … }
]
});
If I define a function like eleanorRigby(o){} o will be the object returned from the data and I can use it immediately:
Now the issue there is if eleanorRigby is not defined it throws an error.
The Bing API is the first instance where I have seen that they worked around that as the output is this:
if(typeof eleanorRigby 'function') eleanorRigby(
{
"SearchResponse":
{
Version",
"Query":
{
SearchTerms hard day's night"
},
"Translation":
{
"Results":
[
{TranslatedTerm harten Tag-Nacht "}
]
}
}
} /* pageview_candidate */);
I have no clue what the /* pageview_candidate */ is about and frown upon omitting the {} of the if statement, but I must say I do like this.
The issue is now that errors are silent, which might make debugging a pain. Maybe a better option would be to have an error case where the API writes out an error to the console when the callback is not defined:
if(typeof callback = ‘function’) {
callback(... data … );
} else {
if (typeof console!==’undefined’ &&
typeof console.log !== ‘undefined’){
console.log(‘Error: Callback method not defined’);
}
}
All in all an interesting approach though!