Start Hacking With APIs
You want to learn how to use APIs to make awesome things. That’s good, because that’s what we're doing in this tutorial.
This tutorial was originally part of Bitcamp 2015's Scout Trail.
I ❤ bitcamp.
Intro
API stands for Application Programming Interface. Any time you are interacting with someone else’s code, you're probably using an API. Communicating with hardware, getting data from a service, or internally in a big codebase.
In the hackathon community and web development communities, API usually means a Web API — a way to interact with data over the internet, usually through RESTful HTTP requests. Basically, you can get data, put new data up, delete data, and update data all using the same tools you use to interact with the web.
If you don’t understand the jargon yet, don’t worry — you’ll figure it out eventually. You should google any words or concepts you don’t understand — I google terms even when I’m writing tutorials.
In this tutorial, we will
- Explore APIs in the browser
- Manipulate API data with simple ruby scripts
You can download the code we use in this tutorial here.
Exploring APIs in the Browser
Sometimes the easiest way to understand is to see, so let’s get started!
While we are getting started, you can make API calls from your browser — it’s tough to do much with the data from there, except look at it and copy/paste it somewhere, but it is good for exploring.
Navigate to http://api.umd.io/v0/courses/cmsc131
What you see is the response from the umd.io API. (The response you see might not be as pretty — I’m using the JSON Formatter Chrome extension)
Implicitly in that url, you asked the API for the course named cmsc131, and it sent back information about that course. The data it sends has a particular structure. In order to figure out what the data means, let’s look at the documentation! The method we are calling on the API is explained here: http://umd.io/courses/#get_courses, and what it returns is a http://umd.io/courses/#course_object.
It’s best to actually read those pages, but tl;dr — you can put any course (or even a list of courses) in the url, and the API will respond with a JSON document with a bunch of fields related to that course (or those courses).
But, how is the API structured? How do I find the names of courses? Let’s look around the docs and at the url, and see if there are ways to find courses.
Pretty quickly, you would find the list courses method and the search courses method. Those will let you see what courses are available, and then you can get courses as you did before.
Generally, you can explore the API in the browser to see what is available to you, and what the objects look like. That’s a great first step in using an API, but after exploring in the browser, you probably want to write programs that get the data and manipulate it.
Manipulating Data with Code
So, how do we get the data into the software we are writing? How do we do real things with it?
We’ve got some sample code! Download from Drive there, or get it from github: open a Terminal window (either on your computer or on Cloud9) and type
git clone https://github.com/rrcobb/bitcamp-scout-apis.gitWe’ll recreate the examples anyway, so don’t worry too much about having those ones. They’re for reference. You’ll actually make a program that manipulates some data right now!
We’ll use ruby, but other languages work great with APIs too. If you have ruby installed on your computer, you can create and edit files in whatever code editor you like (as long as it is not a rich text editor like Word — that would throw things off . We like Sublime.) We’ll run programs from the command line. To check whether you have ruby, open up a Terminal and type
ruby --versionIf ruby is installed, it will tell you which version. If you don’t have ruby, hop on cloud9, create an account and start editing a new custom workspace. ruby is already installed there, so you don’t have to do any setup.
We’re going to use open-uri, which is a nice ruby gem for reading data from urls. With open-uri, we’ll call an API and print the response to the standard output of the command line — where you can see it when you run the program.
Either in your code editor or in cloud9, open a new file.
Zeroth program:
require 'open-uri'puts open('http://api.umd.io/v0/courses').read
Copy/paste that in there, and save it.
What it does:
line 1: ‘require’ lets ruby know that you want to use the open-uri gem.
Gems are ruby’s libraries — they let you use code that others have written and shared, like open-uri.
line 2: print out (‘puts’) the response when you make a call to the url
‘puts’ is ruby’s printline command. Ruby doesn’t need parenthesis for method calls, but you can have them if you like.
‘open’ is the method for getting a page from a url. ‘read’ turns it into a string.
Run the program by typing
ruby zero.rbIt’ll print out a horrible mess of course info, all jumbled together.
Still, the script was pretty simple — two lines of code to do what we could do in the browser. Try getting other urls! Open-uri is versatile, and the urls don’t need to be from an API for it to work. See what you get from other pages!
First program:
require 'open-uri'require 'json'data = open(‘http://api.umd.io/v0/courses').readcourses = JSON.parse(data)puts courses[0]
Just like last time, except this time name it something else!
What it does:
line 1&2: Bring open-uri again, but this time, use the ‘json’ gem too — it has useful methods for parsing JSON. (JSON is a format — you can learn more about it here.)
line 3: assign to variable ‘data’ the result of reading the url — this is like what we did in the previous program, except instead of printing out the result, we are storing it temporarily in a variable.
line 4: parse the data — we need to turn it from a long string of characters, which is what the site sent us, into ruby objects, with useful methods. We’re using the parse method from the JSON library — it looks through the string that we got, recognizes the different pieces as arrays, hashmaps, numbers, and strings, and turns the string into a more useful data structure.
This might be tricky for you to get at first. It’s already formatted in a structured way — why do we need to restructure it? Basically, we are using the structure that it has to draw meaningful relationships between the different parts. We get an array (like a list) of course objects, each with lots of data about that course.
line 5: print out the first course object from the array of courses
Run the program with
ruby first.rband see the output — less crazy than the first program! It almost looks like we could do something useful with this.
Try playing with the different lines, and see what changes. If you break something, no worries! Nothing in the script will do any damage — you might get an error printed out instead of what you wanted, but that’s okay!
Second, Third, and Fourth Programs.
Let’s walk through the code to see what they do as we go. A little faster now, so if you get confused, play with the code more and read here less.
Second:
# first we require the gems we need
require 'open-uri'
require 'json'# read the data from the url
# sorting by course_id and filtering to just the CMSC department
data = open(
'http://api.umd.io/v0/courses?sort=course_id&dept_id=CMSC'
).readcourses = JSON.parse(data)# get a comma-separated list of all the course_ids
ids = ''
courses.each do |course|
ids += course['course_id'] + ','
end# now get information about all those ids
data = open(“http://api.umd.io/v0/courses/#{ids}").read
courses = JSON.parse(data)# finally, sum up all the credits
credits = 0
courses.each do |course|# .to_i converts the text to a number
credits += course[‘credits’].to_iendputs credits
Can you figure out what it does?
It’s a little tricky — we can tell that it is doing the familiar requires, and we know that it is getting a JSON document from the url. At the end, it looks like it is adding all the credits of all the courses together and printing that value out. But in the middle it is doing something tricky!
In order to make a second request to the API, the script builds a list of course ids separated by commas — like “CMSC121,CMSC131,CMSC132,…” Once it has this list, it puts it in the url we use for the second call.
If the programming part of this is confusing, you might need to Try Ruby — we aren’t doing anything super complicated, but you should know how ruby loops work, and the basics of variables and operators.
Again, experimenting with the program will help you understand it better — make a change, save it, run the program again.
Third:
require 'open-uri'
require 'json'my_course_sections = "CMSC131–0101,ENGL393–0101,ARTT100–0101"
data = open("http://api.umd.io/v0/courses/sections/#{my_course_sections}").readsections = JSON.parse(data)sections.each do |section|
course_id = section['course'] section['meetings'].each do |meet|
days = meet['days']
times = meet['start_time']
building = meet['building']
room = meet['room']
type = meet['classtype'] puts "#{course_id} #{type} on #{days} at #{times} in #{building} #{room}." end
end
Copy, paste, save. Run with
ruby third.rbThis one is a little less tricky, but it doesn’t have all those comments to help you decipher what it is doing.
The output is telling:
ARTT100 Lab on TuTh at 12:30pm in ASY 2318.
ENGL393 on MWF at 9:00am in TWS 1106.
CMSC131 on MWF at 2:00pm in CSI 1115.
CMSC131 Discussion on MW at 8:00am in CSI 2118.It’s a class schedule! Mostly, the script is getting useful pieces from the data it gets from the API, and then printing them out cleverly with ruby string interpolation — the “#{}” notation that keeps cropping up.
How would you modify the program so that it let a user input their own courses? (maybe check out ruby’s gets method, or command line arguments!) What else can you do to improve the schedule program?
This one might be the first where we actually got something useful from the API — it hints at the promise of APIs generally. Instead of counting the credits in the Computer Science department, we can get useful data that means something to us!
Fourth:
require 'open-uri'
require 'json'course_data = open("http://api.umd.io/v0/courses/HIST110").readcourse = JSON.parse(course_data)
description = URI.encode(course['description'])sentiment_data = open(
"http://api-sentiment.3scale.net/v1/sentence/#{description}.json"
).readresponse = JSON.parse(sentiment_data)puts response[‘sentiment’]
This time, we are using two different APIs. It is still a very simple program, but again hinting at a great deal of possibility.
Copy, save, run. But what does the output mean? -1.0?
We need to know more about the second API that we are using in order to know whether the script is doing anything interesting. Let’s go to https://sentiment.3scale.net/docs and find out what it does.
So, it looks like we are getting the description of a course, then using the Sentiment API to find out whether the words in the description are more positive or negative — and for HIST110? Slightly negative.
See if you can write a script that finds the courses with the most positive and negative descriptions!
Where to Next?
So, you now have a small sense of what it is like to program with APIs. You might not know how to do big complicated things yet, but you can get there.
The basics are pretty simple — read the docs, figure out how to build the right url, fire it at the API, and use the response in some meaningful way. Posting data to an API is almost as easy — check out examples from the docs, fire a POST request to the API server, and voilá!
Through most of this tutorial, we used the umd.io API — the API I’ve been working on for data from the University of Maryland. Not all the things you want to make are related to UMD courses!
Other APIs to check out:
twilio — send a receive phone calls and text messages
spotify — lots of cool things to do with music
sentiment — There are other sentiment APIs — we use this one in fourth.rb
github — access all the data about github repos!
stripe — payments
chain — the bitcoin blockchain, in an api
There are tons more APIs — some require you to have an account, others don’t. Some are well-documented, others aren’t. Some even have drivers in your language of choice, so you don’t have to manually go and fetch the data over http. The point is to explore all that’s out there, and build cool and crazy shit!
Note: curl and Postman
Sometimes you want to test something quickly in development. While exploring from the browser can work, old-school hip-hop developers will use the GNU command line tool curl.
Open up a terminal — either in cloud9 or on your laptop. curl lets you do requests over http (or other protocols) and prints the output.
From terminal, type this and press enter.
curl http://www.google.comThis should print a big mess of nonsense. That’s google’s homepage! Your browser does something like this, and then understands all that nonsense and shows you the homepage. Cool.
Now, let’s get some data that we can understand — How about the course data we were looking at in the browser earlier?
curl http://api.umd.io/v0/courses/cmsc131That request will give you data about CMSC131 — Still data that’s kind of ugly, but it’s sort of readable.
The curl manual page tells all about the secret power of curl — there are all kinds of options you can pass and tricks you can do, which make it a tremendous all-around tool for experimenting with APIs.
If you want an easy-to-use gooey (graphical user interface), check out Postman — it also lets you build and execute url queries.
Hope you liked your time experimenting with APIs!
Check out my other tutorials — How to Make A Resume Website and Building Your First Backend. If you have questions or thoughts, get in touch with me! @robcobbable on twitter, hi@robcobb.me by email.
If you liked it, recommend it to a friend!
