“They were careless people, Tom and Daisy- they smashed up things and creatures and then retreated back into their money or their vast carelessness or whatever it was that kept them together, and let other people clean up the mess they had made.” –F. Scott Fitgerald

If there was a metaphorical representation of a third party API, Leo would be it.

Undoubtedly.

The Great Gatsby. Eternally eloquent, dazzling, sparkling, but somehow you can’t help but feel that you were handed a big broken, mess, you need to JSON your way out of!

APIs aren’t exactly “messy” so to speak, in fact, they are quite the opposite, a careful, calculated way to access an Application Programming Interface’s data–yet to someone interacting with an API for the first time, you can’t help but be a bit messy, “careless” so to speak–in fact, it’s completely necessary to understand how your API is working.

This blog will attempt to give you the tools to wrecklessly and glamorously parse APIs. Before you know it, you’ll be flying over the Queensboro bridge, all of New York City in your view as you glide slowly but stylishly (cause you’re in a hot car with a 12 cylinder engine 😎) headfirst into the city that never sleeps.

First, it sounds obvious, but at times, we all need the obvious pointed out to us with exclamation marks!!!!!!! and –>arrows<–. LOUD AND CLEAR. Making an API call is simply accessing the correct URL for your desired data (well… you are also scraping the JSON located at a SPECIFIC website, but this is a good starting understanding.)

Now, look up at the top of the screen. RIGHT NOW! The url you are currently at is “http://beccaades.github.io/what-we-talk-about-when-we-talk-about-third-party-apis”. This is where you come on the internet to read my blog about API’s!

Now for THE RULES:

1st RULE OF API’s: READ THE DOCUMENTATION.

The latest API I used, instagram, includes a developer page. It tells you all the different endpoints you will need to access their data, and you can get to playing immediately, by placing the different queries in your browser.

This is what they give you:

1

https://api.instagram.com/v1/locations/search?lat=48.858844&lng=2.294351&access_token=ACCESS-TOKEN

This is what you do:

1

https://api.instagram.com/v1/locations/search?lat=40.7577&lng=-73.9857&access_token=ACCESS-TOKEN

And this is what you get:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
meta: {
code: 200
},
data: [
{
latitude: 40.757696,
id: "5106788",
longitude: -73.985716,
name: "Swatch"
},
{
latitude: 40.75770595,
id: "877266653",
longitude: -73.985676,
name: "Espn - Abc Studio Times Square"
},
{
latitude: 40.7576833,
id: "5012142",
longitude: -73.9857171,
name: "Times Square"
},
{
latitude: 40.757692657,
id: "242689896",
longitude: -73.985731602,
name: "Black Bar & Loungue"
},

(SIDENOTE: Please don’t be a dummy and know that you will have to actually replace the access token with your own.)

To access this information you can treat the JSON like a hash. Let’s say we set this equal to the variable data_hash. If I wanted to access “Swatch,” I could enter data_hash[:data][0][:name]and it would return “Swatch” back to me.

2nd RULE OF API’s: PLAY!!

Now. Listen close. I have a little gem to share with you. The httpary gem to be exact.

This gem lets you get down to business quickly by simply requiring it and then gaining direct access to JSON in the API to your app, to gain both familiarity and explore potential methods for your classes.

To use the httparty gem you simply require it in your gem file. Then in your model, your require the gem like so:

1
2
3
4
5
6
7

class InstagramWrapper

  require 'httparty'

  response = HTTPARTY.get("https://api.instagram.com/v1/media/search?lat=40.7577&lng=73.9857&distance=1000&access_token=access_token")

end

You can then begin by binding into the respond and deciding what information you need and begin to structure your methods.

3rd RULE OF API’s: ASK THE API’s WHAT METHODS THEY HAVE

Once you are able to access the JSON, don’t be afraid to ask the API exactly what methods they have! They may just tickle your fancy with some extra methods that they don’t discuss in the documentation. For example, the only way, I was able to learn about instagram’s nifty tag_count feature was through directly asking instagram what methods they have (rails console, baby!) and I got this quite lovely response (amongy MANY many others).

1
2
3

=> [:client,
 :get_count_for_tag,
 :get_tourist_instagrams

I simply did this by entering the following into my console:

1
2

tell_me_the_methods_baby = InstagramWrapper.new
tell_me_the_methods_baby.methods?

How wonderfully convenient.

4th RULE OF API’s: WRAP THE API’S METHODS IN YOUR OWN INSTANCE METHODS

Once you have found the desired method, it is time to wrap it in an instance method. For example the instagram tag count method could be wrapped as such:

1
2
3
4

  def get_count_for_tag(tag)
    results = client.tag_search(tag)
    results.collect {|result| result["media_count"]}.first
  end

Results for the tag “HTTparty” gives you back :

1

=> 8.0

Sad toast.

The people of instagram are definitely missing out.

And there you have it. A step by step guide to deconstruct the many faces third party API’s may bring us. Cheers to that!