Are you an absolute (or relative) beginner at Ruby on Rails? Do you want to dip your toe into the vast sea of APIs in order to make your Rails app more dynamic? This is the place for you—welcome, friend!
A note: below is a chronicle of what worked for my app, which used the YelpFusion API. I am, like you, a beginner at Rails, and as we both know, there are hundreds of ways to solve the same problem in programming.
What is an API?
A quick google will tell you that API stands for Application Programming Interface and that, at their core, APIs are built so that programs can talk to each other.
APIs give you access to the data that multinational conglomerates, small businesses, and more experienced devs have spent time and money gathering.
For the fledgling programmer, what that really means is an API can give your app ✨ super powers ✨
The Yelp Fusion API
For our project, a Rails app that allows a user to search for, rate, and save pizzerias in NYC, my partner and I wanted to move beyond hardcoding seed data about pizzerias and make something that felt truly representative of how a user might interact with an app. We needed real-world data.
Enter the Yelp Fusion API, which allows developers to harness the immense power of Yelp, with access to data and content from over 50 million businesses!
And the best part about using Yelp’s API for a small app or student project? It’s FREE. Yelp allows your app to make up to 5,000 calls per day to their API, which is incredibly generous and allows you the freedom to run tests—again and again and . . . you get the point—without the fear of hitting your cap.
For example: my partner and I have been working with the API for a week now, and we’ve made about 200 total calls.
Getting Started
The first step to any app journey, as you’ve no doubt quickly learned, is signing up for an account. Yelp requires fairly basic info about both you and your app.
Once signed up and logged in, you’re kicked into the Yelp Fusion portal, where you immediately have access to documentation on using the API along with your personalized API Key at the top of the page.
API Keys are an essential part of accessing the data that a company as gathered. Any time your app is making a call request to the API, you’ll need to pass along your key in order to authenticate the call.
Now it’s time to add your key into your app!
Hiding Your Key
An essential next step toward using the API is to make sure your key is well hidden in your file structure.
Why are we ‘hiding’ our key? It’s not so that we—the developer—can’t find it again. Like Gandalf said, we want to make sure to keep our key safe from other people using it.
As I mentioned above, your individual key is a way to authenticate your access to the API. It’s a way for companies to keep track of who is accessing their data and how they’re using it. And this becomes crucial when it comes to APIs where you’re paying fees based on the specific endpoints you’re accessing and the number of calls you’re making.
We, like most devs, store our repo on GitHub, which is a collaborative space. Making your repo public means that anyone has the ability to peruse your files or clone your project to their local machine—that’s what open source is all about.
If we don’t hide our key effectively, then it’s fair game for others to use it to make calls to the API.
So let’s hide our key!
There are a number of ways to do this. We used a gem called Figaro, which allows for a fairly straightforward configuration using an ENV variable and a single YAML file.
ENV variables are a way to pass local configuration settings to an application. Ruby has an ability to both set environment variables and read them—Figaro takes advantage of this by allowing you to place a single YAML file in the ‘config’ folder.
We started by adding the Figaro gem to our Gemfile:
gem 'figaro'And then run
$ bundle installGreat! The Figaro gem is now installed in your app. The next step is to add both a YAML file to your ‘config/’ folder and to add a line to your .gitignore file that ensures that file isn’t included in any git actions. The easiest way to accomplish both these tasks is by running
$ bundle exec figaro installNow you’ll need to add your API key to the ‘config/application.yml’ file. Environment variables take key/value pairs.
'config/application.yml'1 YELP_API_KEY: eNtErYoUrKeYhErE
This variable is now available throughout your application, and is called by
File Structure in Ruby
For my partner and I, the real stumbling block to using APIs came with trying to figure out how exactly to set up the API call in a way that our app files—our Controllers and Views—would have access to that information.
We did a lot of googling around and read a lot of blog and StackOverflow posts about how to set-up the files. There was lots of information on the code, but nothing on where to put the code.
We were finally able to jigsaw a solution together by creating a new class in the services folder in our app directory.
This creates a service object, which allows us to keep the concern of calling the API and returning the results in its own class that we can then call in our controllers or, as we later ended up doing, in our seeds.rb file.
There’s absolutely a cleaner way of doing this, and, frankly, if we had more time, I’d want to refactor some of our API interaction methods into that YelpService class. But for the time being, we were able to get by by keeping the following code there.
Making Your First Call
Wow! We’ve gotten through the most difficult bit (we can save cleaning up JSON data for another post, mayhaps). So, it’s time to make our first call!
Since we created the self.search class method in our YelpService class, we can now call that method anywhere in our program to create an API call.
These calls save the data to a variable corresponding to the name of the borough argument that we passed into our method.
The results are a beautiful hot mess of data, but they’re also the results of a successful call on the Yelp Fusion API, so we love and cherish them. Even if they make our head spin. ✨
