Getting Your API to Play Well With Others


Steven Weiss is a web developer, technology enthusiast, and recent Web Development Immersive graduate.  His former life was spent as a sound engineer for NPR and various voice over studios.  When not coding, he is likely cooking and/or eating. In this blog, Steve takes us through the process of creating his app, On The Side, in our WDI course. This post originally appeared on Steve’s blog here.

My first app is out in the world, flying on its own little wings. It’s called On The Side, your source for restaurant recommendations based around a super cool and esoteric list of the best ingredients right now. But lets take a step back.

On The Side begins its life as the first project assignment for the General Assembly Jan’ 14 WDI class, a collective of 27 pirate like individuals from diverse backgrounds, all restarting their lives as web developers. It’s like a reality show, except that everyone is there to make friends.

In 6 weeks, each of us has gone from little to no web development knowledge to building a fully functioning app. Once you beat yourself up over everything you’d like to improve or need to have a better handle on…it’s pretty exciting.

This was my first foray into the world of API’s (application programming interfaces), a concept so wonderful and exciting it can be hard to wrap your head around. An API is at its base level, a set of instructions to let your software access someone else’s software. In my case I used APIs provided by Foursquare and Instagram.

These services are free to use (unless you are making a very large number of requests per day) and in both of the above cases, the documentation was excellent. You make a standard HTTP request (not unlike a web URL) and are returned a whole bunch of data, but we’ll get to that in a minute.

Working in Ruby On Rails, I would send HTTP requests to Foursquare based around an ingredient and neighborhood, get back 5 restaurant names, and use the location of those restaurants to post Instagram pics taken at those locations. Simple enough, right?

In a perfect world, our computers would know exactly the information we want and deliver it to us in easy to read sentences, maybe with a little encouragement and a few compliments thrown in. But that’s not what happens. My process of working with these API’s was divided into three phases.

Phase 1 : Familiarize Yourself with the API

I initially attempted to work with the Yelp API, but much like the content of their restaurant reviews, the service was not so dependable. Their Github page hasn’t been updated in 3 years, and the results I was getting just didn’t match up. After many highs and lows, I switched over to Foursquare who appeared much more supportive to developers.

After signing up, you are provided 2 authorization keys, a Client ID, and a Client Secret, which both have to be appended to the end of each HTTP request you make. (These should be stored as Environment variables so they don’t end up on Github, here is a lovely post on the subject.) Before diving into Rails, I set up a simple Ruby program to make requests, using a method to change the variables of location and ingredient. Lo and behold, I got results! But, those results were nested deep within a hash of unimaginable riches. Don’t believe me? Take a look.

That’s just for one result (both screenshots). Once you read through the returned hashes of hashes of arrays (etc.), you best get your iteration skills sharpened.

Notice where the restaurant name, address, and URL are? Way down into those results, at the top of the 2nd view, under “venue”. This was where most of my necessary info was returned. You can see in the method photo below how those results can be accessed.

Getting these results was an exhilarating feeling. After a month of working in Ruby, only dealing with data I created myself, this opened up a world of possibilities.

Side note — in order to get those results to a standard Ruby hash, they need to be converted from JSON. I used HTTParty, mainly because it prints an Andrew WK quote after installing.

I’m quickly learning that in programming, this fleeting feeling of joy is common, and shortly after you return to the real world and face your next challenge. This brings us to…

Phase 2: Put that data to work in Rails

At this point, it was time to parse through those results and put them to good use in the program. Here is the method I used:

The arguments are just the neighborhood and food interpolated into the HTTP request. That method was then called within another method, “neighborhood” in order to parse through the results and make them usable as their own hash.

The ingredient (the food searched for) is pre-defined based on a menu, and the [:neighborhood] parameter comes from a form tag, input provided by the user. These are all stored in an instance variable “@restaurant_lil_hash” to be iterated through on the view page, since each search would provide 5 results.

You may notice the “single_picture” method above being called for the :image key. That’s where it got tricky.

Phase 3: API Communication (breakdown)

Let me reiterate (sorry) that I had never used an API before this project except for one classroom demonstration. But it does seem that once you understand one, the others follow similar conventions.

Once this data came back from Foursquare and the initial excitement wore off, it clearly needed something else. Apparently there were no images included in the Foursquare results, just a few profile pics which really would not be useful. So I turned to my favorite App-Based-Addiction, Instagram.

I love Instagram. I’ll spare you several paragraphs on why and just put it in a later post. But that love has only grown since working with their API. The documentation is fantastic, and they even have a Gem to dry up your code.

The API works very similarly to Foursquare’s, making an HTTP request and including authorization keys, but their Gem makes these requests incredibly simple. Have a look.

Instagram requests seem to be broken up into a few categories, depending on what you want to get back. In my case, I wanted media results based on a location. Within their documentation, it states that you can use a Foursquare location ID (which is returned in the Foursquare results above) in order to return the Instagram location ID.

I misread this as “You can use the Foursquare ID to get Instagram results, just go for it” and promptly lost severals hours of time running in the wrong direction. It was a relatively simple fix, but let me tell you, solving that one was a pure thrill of victory.

As seen above, the Instagram Gem includes many useful methods such as “location_search” in order to get the Instagram location ID. So, the “single_picture” method first returns the Instagram location ID (stored as foursquare_hash) and then makes another request to Instagram, this time for recent media taken at that location, using the ID (which is located in a hash, within first array[0], and with the key [“id”]). These results are then randomized with “.sample” to return a different single image each time.

Feeling like a renegade outlaw biker instead of a dude behind a laptop, I decided to take this even further, applying my newly acquired API intercommunication skills to the Google Static Maps API (the regular Google Maps API is based in Javascript, which might as well be hieroglyphics at this point).

All this entailed was extracting the longitude and latitude of the restaurant location and applying to the Google Static Maps http request, in the same fashion as Foursquare. To think, none of this made any sense just days ago. Let’s all give a hand to good documentation.

The idea for this project was more of an experiment than anything else, but it shed light on a much bigger concept.

Once you cross that threshold of intimidation and begin working with API’s, the world of possibilities opens up. The initial hash results from many of these seems like gibberish at first glance, but take a closer look and play around with the data.

This is where the conceptually creative side of programming comes into play. After you have the syntax down (one of my main struggles) it’s only a matter of ideas.

On The Side on Github, if you’d like to check out the code

As a closing side note, I spent my past professional life as a sound engineer, and my favorite microphone pre-amps were made by a company called…API. They sound fantastic and are super stylish. Coincidence? There are no coincidences.