November 13, 2009

Introducing the API Explorer Mutant

Overview

Do you enjoy peering into the abyss of structured data? Do floating swirls of abstraction wrapped in the churlish embrace of XML get your goat? Yeah, you got issues, but read on anyway. Please?

Meet my baby-blue-eyed monstrosity, a humble yet raffish creature: the Yahoo! Social API Explorer.

If you're one of those people who read case studies of criminal minds and learns assembly for kicks, you can find the code for the API Explorer on github. Or, to approach this beast in 11 easy steps, see the tutorial Exploring the Yahoo! Social APIs.

Getting Started with the Mutant

Wait, I have a little tale to tell.

A few weeks ago, I was soul-searching, desperate for XML responses, JSON responses--even a lowly response header. After futilely poring over spools of internal wikis, I sought the office oracle on how to best document the Y! Social API Reference. "How do I quickly get response bodies from the APIs to put in the documentation?" I asked. The oracle looked askance at me, made a crack about my shirtsleeves being too short, took a swig of diet Pepsi, and belched the opening melody of Nessun Dorma in my face.

Okay, as a Tech Writer, I am quite accustomed to being turned away, not getting responses from engineers, being ignored by project managers, being dissed by grocery baggers, etc. (I still can't figure out how the grocery baggers know that I'm a tech writer?) Oh yes, I know you're different, dear reader. You take your tech writer to lunch, patronizing this half-writer, half-engineer, half-wit, 3-halved fool with drivel about cloud computing.

So, you can understand how I've always taken a liking to Web services. These tireless, mute machines are relatively friendly, approachable, sanitary, and extremely egalitarian. You spit a GET at them and they unhesitatingly kindly reply with an OK and some prim and proper data.

I guess we never really got started. Oh well, put on your green hunting cap and quietly lumber to the next paragraph.

Starting Again

As it turned out, while I was plucking my eyebrows in frustration, my co-worker inadvertently stepped into my cubesicle and showed me a code scrap that used the Y! Social SDK For PHP to make GET requests to the Y! Social APIs. I scraped the scrap and transformed it into a towering fetid heap of spaghetti code that somehow rendered into a serviceable API explorer: The fiend was born.

Yes, I now had an XML-JSON-spitting machine at my disposal, but all I saw was this frivolous, link-riddled page so GeoCities-personal-page ugly that it was certain to be quickly abandoned by mother Internet, condemned forever to the nightmarish purgatory of pasting XML schema types into tiny element tables for a living. Uh, sorry, got off track there.

Like any good parent, I wanted the little monster to become something, to lead a respectful existence, rescued from the horror of being common, forever banished to some forsaken archive. I shuddered and gave my creation an undisguised look of repugnance.

Brain Transplant and Face Lift

I like data and information, lots of both. Getting the response bodies was not going to be enough. Wouldn't someone want to see the request and response header? What if they wanted to know about the APIs and not just see an avalanche of data?

So, I pulled out some tabs and tooltips from the YUI grab bag, slapped in some stylesheets taken from the YQL Console, and added a text field for manually entering URIs. Sure, it was Abby Normal's brain lodged sideways into the misshapen skull of Shrek, but now the data-spitting contraption at least had monkey intelligence. Users might learn a few things, stay a little longer, understand what they were doing...

A Pragmatic Monster

Most monsters are rather indolent and would rather file their hideous nails by the pool than work. My despicable creation, on the other hand, although clumsy and simple-minded, will actually assist you.

Holding its gnarled hand, you can learn about the types of data available, examine the URI syntax for making calls to the APIs, compare the differences between the XML and JSON responses for collections, learn how to paginate collections, distinguish collection and singleton resources, refer to the reference docs for information about query and matrix parameters, what HTTP methods are supported, distinguish the European Mouflon from the Leicester Longwool....

Excuse me, my inner tech writer wants to put that in a nice bulleted list.

With the API Explorer Half-Breed, you can do the following:

• Learn about the types of data available.
• Examine the URI syntax for making calls to the APIs.
• Compare the differences between the XML and JSON responses for
  collections.
• Learn how to paginate collections.
• Distinguish collection and singleton resources.
• See what HTTP methods are supported for each API.

Okay, if you've read this far, you'd be remiss not to see the tutorial Exploring the Yahoo! Social APIs. I hope you use the Yahoo! Social APIs to make your own creations.

Thanks for reading and tell me if I need to go back to the lab and do more exploratory surgery.

Joe Catera
Tech Writer

Posted at November 13, 2009 8:56 AM | Permalink

Bookmark this on Delicious

Comments