A quick introduction to the BOSS REST API and how to use it in JavaScript using YUI3. Make sure to also download the code examples: http://icant.co.uk/stuff/bosscodebr.zip

1. Who’s the BOSS?
Christian Heilmann, Sao Paulo, Brazil, 06/11/2008 (brhackday08)

2. I’m Chris.
Hello I am Chris

3. I live in London, England

4. But originally I am German

5. Doesn’t matter though, both
countries keep losing against
you playing football...

6. I like easy access to things.

7. I also like easy Math.

8. >

9. Here’s what I can help you
with during hack day:
JavaScript, Accessibility, YUI,
CSS, APIs, Flickr, Delicious ...

10. Today I am here to tell you
quickly something about
BOSS.

11. So who’s the BOSS then?

12. BOSS is Build Your Own
Search Service:
http://developer.yahoo.com/search/boss/

13. To use it, you need a
Application ID:
https://developer.yahoo.com/wsregapp/

14. And there is full
documentation available:
http://developer.yahoo.com/search/boss/boss_guide/

15. Happy Hacking!

16. ... oh alright then ...

17. You can get the code
examples I will show here:
http://icant.co.uk/stuff/bosscodebr.zip

18. Say you want to search the
web for donkeys.

19. Because
Donkeys alright then ...
... oh
Rock!

20. Using BOSS you can do this
with a REST API and display
the results any way you want!

21. The REST API:
boss.yahooapis.com/ysearch/{type}/v1/{search}

22. The REST API:
boss.yahooapis.com/ysearch/{type}/v1/{search}
type is what you want to
search:
web: the interwebs
news: new stuff
images: pictures

23. The REST API:
boss.yahooapis.com/ysearch/{type}/v1/{search}
search is the term to look for
(url-encoded)
Put “” around terms to ensure the right order, f.e. “donkey
fur” (you don’t want to see cats, do you?)
Filter with a -, f.e. donkey -shrek
Restrict to a site using site:, f.e. donkey site:flickr.com

24. The REST API:
boss.yahooapis.com/ysearch/{type}/v1/{search}
Other parameters:
appid: your app ID (needed)
count: amount of results
start: where to start the counting
region / lang: country and language
format: xml or json
sites: restrict to certain sites (comma separated)

25. Web search REST API:
boss.yahooapis.com/ysearch/web/v1/{search}
Extra parameters:
filter: To filter out nasties, use filter=-porn-hate
type: to search different types. You can use html, text, pdf, xl,
msword, ppt or groups like msoffice and nonhtml. You can
also do a type=msoffice,-xl

26. Image search REST API:
boss.yahooapis.com/ysearch/images/v1/{search}
Extra parameters:
filter: no nudies
dimensions: all, small, medium, large, wallpaper,
widewallpaper
refererurl: all images in that url
url: image at that url

27. News search REST API:
boss.yahooapis.com/ysearch/news/v1/{search}
Extra parameters:
age: how old the news are in days. Last five days would be
“5d”

28. There are restrictions how to
display results and
information as to what data
comes back.

29. For this, read the guide!
http://developer.yahoo.com/search/boss/boss_guide/

30. Everybody Duck!

31. There will be code

32. The easiest way to use BOSS is
using JavaScript.

33. http://boss.yahooapis.com/
ysearch/web/v1/donkeys?
format=json&appid={id}

34. {quot;ysearchresponsequot;:
{quot;responsecodequot;:quot;200quot;,quot;nextpagequot;:quot;/ysearch/web/
v1/donkeys?
format=json&appid=[...]&start=10quot;,quot;totalhitsquot;:quot;492
215quot;,quot;deephitsquot;:quot;15700000quot;,quot;countquot;:quot;10quot;,quot;startquot;:quot;0
quot;,quot;resultset_webquot;:[{quot;abstractquot;:quot;Hyperlinked
description of the domesticated mammal discussing
its appearance, relationship to horses, economic
<b>...</b> horses and <b>donkeys</b> were
brought back <b>...</b>quot;,quot;clickurlquot;:quot;http://
lrd.yahooapis.com/
_ylc=X3oDMTU4b2NoaDR2BF9TAzIwMjMxNTI3MDIEYXBwaWQDV
Fg2YjRYSFYzNEVuUFhXMHNZRXI1MWhQMXBuNU84S0FHcy5MUVN
YZXIxWjdSbW1WclpvdXo1U3Z5WGtXc1ZrLQRwb3MDMARzZXJ2a
WNlA1lTZWFyY2hXZWIEc2xrA3RpdGxlBHNyY3B2aWQDR3lDaEg
wU081cTlmSktUNG1ndTVUUUJNdlNjaS4wa1ZUVndBQVF5Sw--
/SIG=11820sato/**http%3A//en.wikipedia.org

35. To use this across domains,
simply define a callback
parameter:

36. http://boss.yahooapis.com/
ysearch/web/v1/donkeys?
format=json&callback=foundd
onkeys&appid={id}

37. founddonkeys({quot;ysearchresponsequot;:
{quot;responsecodequot;:quot;200quot;,quot;nextpagequot;:quot;/ysearch/web
/v1/donkeys?
format=json&callback=founddonkeys&appid=TX6b4XHV3
4EnPXW0sYEr51hP1pn5O8KAGs.LQSXer1Z7RmmVrZouz5SvyX
kWsVk-
&start=10quot;,quot;totalhitsquot;:quot;492215quot;,quot;deephitsquot;:quot;15700
000quot;,quot;countquot;:quot;10quot;,quot;startquot;:quot;0quot;,quot;resultset_webquot;:
[{quot;abstractquot;:quot;Hyperlinked description of the
domesticated mammal discussing its appearance,
relationship to horses, economic <b>...</b>
horses and <b>donkeys</b> were brought back
<b>...</b>quot;,quot;clickurlquot;:quot;http://
lrd.yahooapis.com/
_ylc=X3oDMTU4cG05cXJwBF9TAzIwMjMxNTI3MDIEYXBwaWQD
VFg2YjRYSFYzNEVuUFhXMHNZRXI1MWhQMXBuNU84S0FHcy5MU
VNYZXIxWjdSbW1WclpvdXo1U3Z5WGtXc1ZrLQRwb3MDMARzZX

38. All you then need to do is put
this url in a script node and
write the founddonkeys
function:

39. <div id=quot;searchresultsquot;></div>
<script type=quot;text/javascriptquot;>
function founddonkeys(o){
var donkeys = o.ysearchresponse.resultset_web;
var results = document.createElement('ul');
for(var i=0,j=donkeys.length;i<j;i++){
var item = document.createElement('li');
var link = document.createElement('a');
var abstract = document.createElement('p');
link.setAttribute('href',donkeys[i].clickurl);
link.innerHTML = donkeys[i].title;
item.appendChild(link);
abstract.innerHTML = donkeys[i].abstract;
item.appendChild(abstract);
results.appendChild(item);
}

40. document.getElementById('searchresults').appendChild(r
esults);
}
</script>
<script type=quot;text/javascriptquot; charset=quot;utf-8quot;
src=quot;http://boss.yahooapis.com/ysearch/web/v1/donkeys?
format=json&callback=founddonkeys&appid=xxxquot;></script>

42. Two problems though:

43. First of all – without JavaScript
there are no donkeys!

44. Secondly – you can only find
donkeys!

45. The solution: Event Handling
and dynamic script
generation.

47. <p>Warning: this is terrible code, USE A LIBRARY INSTEAD!</p>
<ul id=quot;searchesquot;>
<li><a href=quot;http://search.yahoo.com/search?va=donkeysquot;>
Search for Donkeys
</a>
</li>
<li><a href=quot;http://search.yahoo.com/search?va=kittensquot;>
Search for kittens
</a>
</li>
</ul>
<div id=quot;searchresultsquot;></div>

48. <script type=quot;text/javascriptquot; charset=quot;utf-8quot;>
function founddonkeys(o){
var donkeys = o.ysearchresponse.resultset_web;
var results = document.createElement('ul');
for(var i=0,j=donkeys.length;i<j;i++){
var item = document.createElement('li');
var link = document.createElement('a');
var abstract = document.createElement('p');
link.setAttribute('href',donkeys[i].clickurl);
link.innerHTML = donkeys[i].title;
item.appendChild(link);
abstract.innerHTML = donkeys[i].abstract;
item.appendChild(abstract);
results.appendChild(item);
}
var resultsbox = document.getElementById('searchresults');
resultsbox.innerHTML = '';
resultsbox.appendChild(results);
}
var APIkey = 'TX6b4XHV34EnPXW0sYEr51hP1pn5O8KAGs'+
'.LQSXer1Z7RmmVrZouz5SvyXkWsVk-';
var searchlinks =
document.getElementById('searches').getElementsByTagName('a');
for(var i=0;searchlinks[i];i++){

49. var APIkey = 'TX6b4XHV34EnPXW0sYEr51hP1pn5O8KAGs'+
'.LQSXer1Z7RmmVrZouz5SvyXkWsVk-';
var searchlinks = document.getElementById('searches').
getElementsByTagName('a');
for(var i=0;searchlinks[i];i++){
searchlinks[i].onclick = function(){
var searchterm = this.href.split('va=')[1];
var url = 'http://boss.yahooapis.com/ysearch/web/v1/' +
searchterm + '?format=json&' +
'callback=founddonkeys' + '&appid=' + APIkey
var s = document.createElement('script');
s.setAttribute('type','text/javascript');
s.setAttribute('src',url);
document.getElementsByTagName('head')[0].appendChild(s);
return false;
}
}
</script>

50. *click*

51. Using the YUI library (YUI3
JavaScript and CSS grids) you
can easily make this much
cooler:

54. Now, that was JavaScript,
what about the server side
magic and BOSS?

55. Over to my colleague for some
hot Python action...

56. Obrigado!
Christian Heilmann | http://wait-till-i.com | twitter: codepo8