Tutorial: How to get data from external API ? PART 1: Getting API Key, Creating and Loading Configuration File [Ruby, YAML, REST]


I have gotten numerous emails with this question. I have decided to build a small app, that is based on the external API.

Why do you need to get data from external API ?

If you are asking this question, maybe you are reading the wrong post. Just kidding! Keep on reading! You need an external API because it allows you to use data from third party sources. Do you want your website to show the weather from WeatherNetwork ? Or game scores ? Or Twitter/Facebook feed ? This all is done through external APIs.

What is the process of getting data from external API?

Process usually involves several steps:

a. Registering with API vendor to get an API Key
b. Getting API paths
c. Making HTTP request to the API Path
d. Parsing response

Pretty straightforward right ?

Lets put it on practice.

Here is what we are going to do:

We will build part of the Movie Command Line Interface App (movie-cli), that will receive a movie  title through command line, and give us back information about the movie.

See Screenshot Below:
movie-cli

For this example I will be using RottenTomatoes API, however we will build our app in a such a way, that  by making couple of small changes, you will be able to put any other API.

Registering with API vendor to get an API Key

To get an API key from RottenTomatoes you will need to register your “project”. Put as precise information as you can, you can always change it later, so don’t worry too much about this.

After filling in the form you will get an email, and after clicking on the link in the email you will be redirected to the page that will have a random string which is your API Key. Save this key, you will need it!

That’s done. Easy right ?

Getting API Paths

To make HTTP request to the API Path you need to know API path. Best source for that is always documentation. After browsing through documentation you will see this URL:

http://api.rottentomatoes.com/api/public/v1.0/movies.json?apikey=%5Byour_api_key%5D&q=Toy+Story+3&page_limit=1

Lets explore parts of this API call:

1. Protocol:  http://
2. Host/Domain: api.rottentomatoes.com
3. API Path: /api/public/v1.0/movies.json
4. Parameters: apikey=[your_api_key]&q=Toy+Story+3&page_limit=1

All this parts are necessary in order for to get information from third party source. In order to make our app extensible we will create a YAML configuration file where we will keep all this info.

It will look like this (api_paths.yml):


rottentomatoes:
  protocol: http://
  host: api.rottentomatoes.com
  api_key: <YOUR API KEY> # Please Replace this with API KEY from http://developer.rottentomatoes.com/
  api_path: /api/public/v1.0/movies.json
  max_movies_per_output: 5

Note: If you are following along in the GitHub,  please rename api_paths.yml.sample file to api_paths.yml . Please remember to put your API-KEY into api_key section.

So now we have configuration file, where we can store all necessary configurations regarding our third party API`s.

Last thing we will do in this part is we are going to load this configuration file into one of our classes.

How to load YAML file into Ruby class ?

Now we are going to create RottenTomatoes::API ruby class that will load this configuration file. Please refer to Github for the file structure.

In constructor of API class we are going to load YAML configuration file:

 def initialize
   # path can be either from root or for debugging from the curent class
   if File.exists?('../../config/api_paths.yml')
	@config = YAML.load(File.open('../../config/api_paths.yml'))
   elsif File.exists?('./config/api_paths.yml')
	@config = YAML.load(File.open('./config/api_paths.yml'))
   else
     raise StandardError, 'Configuration File cannot be found... please make sure you have api_paths.yml'
   end
end

Note:  When dealing with YAML file do not forget to require ‘yaml’.  

This code is pretty straightforward, since I am dealing with relative paths, and  sometimes I run code inside of the class for debugging, I am checking File.exists? two times, once against  path being relative to the root of my app, other relative to the current directory.

If I cannot read/locate my configuration file I raise an exception.

After RottenTomatoes::API is initialized, you are going to have all your API  configurations loaded into a @config , and available to use.

This is it for the Part 1 of our tutorial. Please stay tuned, as Part 2 will be coming up in the next couple of days, and it will deal with actually sending request to RottenTomatoes using RestClient gem. Of course if you cant wait, just grab the whole app from here .

Once again, if you have any questions concerns or recommendations, please let me know.

Have a great day,

Anatoly

Advertisements

About Anatoly Spektor

My name is Anatoly Spektor (originally Anatolijs Spektors) I am Software and Web Developer. I have worked in Seneca Center for Development of Open Technology on Big Blue Button Add-on - Polling Module, Red Hat and some other places :) I am an author of the book 'Eclipse Debugging How To', Muay Thai fighter and amateur photographer ;)
This entry was posted in open-source, Programming Languages, Ruby and tagged , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s