Using a Web API in Rails

In this blog post you’ll learn what is an API and how it can be applied in a Ruby on Rails application.

What is an API?

You’ve probably heard the term API thrown around by developers and novices alike, maybe with descriptors like private API, public API, or partner API. How about local API, program API, or web API? It’s difficult to define APIs as a whole because there are many types that serve many purposes. At its core, an API (Application Programming Interface) is code that allows two entities to exchange information. It is an interface (the I!), or a middleman, that controls the passage of data.

When using a web API, the requested data is being passed from the server, via the API, to the client (you and your web browser). It is usually returned in JSON (JavaScript Object Notation), a language-agnostic format that likely includes nested data structures.

It’s useful to understand the request-response life cycle as you begin working with APIs:

• The user makes an HTTP request, like you would input into your browser’s address bar
• The request gets sent to the website’s server
• It is then intercepted by the API
• The API accesses and returns the specific data-set that you have requested from the broader body of data that developers have decided should be included for API access

There is an amazing wealth of information available to us via APIs on the web. Some APIs are monetized and require a subscription, which you might use if you run a ski area and want accurate current weather reports. Your customers will know whether to bring those big, wide powder skis or the 20-year-old sticks that can handle a rock or two. These APIs often have a free version that comes with limitations on call frequency or available data, but is perfectly good for practicing as a beginner developer.

One thing to keep in mind is that each API will have a slightly different format for making requests to its server, so check out the documentation. This should be readily available on its website, and will include code examples, so you can copy/paste and insert your own parameters.

In my example, I use Climacell’s weather API . Its clear documentation shows the code necessary for a request, and even allows you to build your own code snippet. Notice how the code on the right includes “Seattle” because I typed it in the box on the left?

API in Rails

Now the fun part, using an API!

1. Choose an API

• There are very simple APIs that return a chunk of data when you send a URL request. Look ma, no parameters! Try entering this into your address bar: https://api.publicapis.org/entries . It’s an API of APIs, but it’s really just a big array of hashes.
• More complex APIs return data based on parameters you include in the HTTP request, often separated by “&”. Try entering this: https://datausa.io/api/data?drilldowns=Nation&measures=Population . Now instead of “Nation” type “State”. You can test what other parameters are allowed.
• Even more complexity is added with increasingly strict authentication. For practice purposes you should be able to find APIs that are accessible with a free API key or OAuth token that is assigned immediately.

2. Get an API key if needed

To use the Climacell API I signed up for a free account and selected the desired service. Climacell has many great APIs that offer different data-sets: current conditions, future forecasts, historical weather, etc. On the dashboard page, I have access to my API key, which needs to be included in every API call. An example HTTP request looks like this:

Wow, that’s a mouthful, but you can see each parameter and its value after the “?”: latitude, longitude, units, time, data fields, and the API key.

3. Set up the API call in Rails

You’ll need a way to send this request to the server from inside your Rails application, and fortunately there are some helpful Ruby gems. There are multiple ways to achieve this connection, but I use Rest Client to send the HTTP request, and JSON to parse the data into a format I can use.

You’ll first have to install the gems and require them in your application, either in the environment file or the file where the gems will be used (probably the former). Here is an example of a method that retrieves the JSON data:

4. Identify the data structure

You’ll need to take a look at what the json variable actually returns. Probably something like this, woah!

If you go through the above JSON carefully, you can identify the data structure and how to pick out a certain piece, such as low temperature (highlighted). Adding that logic in another method looks like this:

The user will see “The low temperature today is 24F” and have an interactive experience with your application. Cool!

Thanks for reading and please drop a comment if you think this could use additional information or clarification. Happy coding!