Parsing JSON APIs with Ruby gems
API, or Application Programming Interface, provides your application with an immense tool of real time data, made possible by an interactive communication between systems and users of such programs. Among the likes of XML or YAML, JSON, which stands for JavaScript Object Notation, is the most often used format to store and transfer nested data over the internet.
There are a few ways to take in an API endpoint and parse it down to workable format of data, such a hash or an array, in Ruby and specifically Ruby on Rails. Let’s look at the most widely used gems and see what purpose each one of them would best serve.
RESTful APIs follow set of rules such as:
Client-Server Architecture: clear boundaries between the client and the server. This is the Separation of Concerns, where the client is in charge of displaying data, and the server is in charge of storing it.
Statelessness: the server does not store any information about the client, and every request must contain all the necessary details to complete.
Net::HTTP
net/http is a built-in Ruby class which is designed to work closely with URI, or Universal Resource Identifier. URI encompasses URL, which stands for Universal Resource Locator. They are both standard ways to locate something. Data stored in remote servers can be located with an URL, which then needs to be converted into an URI object, then parsed into workable format using net/http or other libraries.
net/http allows us to get back an object closer to the structure of the actual HTTP response. Since it is a standard Ruby library, there is no need to install any gem and there is no dependencies to worry about down the road. If you value stability over speed of development, this is the good choice.
The drawback of this is, of course, there is more work to do than using the gems built on top of it. For example, to use net::http, you need to create an URI object first from the API endpoints before making the actual HTTP request. Often times, if you are just making a few simple GET requests, it is better to use ‘open-uri’.
HTTParty
Makes http fun again! Ain’t no party like a httparty, because a httparty don’t stop.
If using the standard net/http feels clunky and cumbersome, gives this wrapper library a try. A wrapper library is a thin layer of code wrapped around a library, which in a nutshell is a concrete implementation of some functionality. This layer of code, or abstraction, has a purpose of making the existing functionality cleaner and easier to use.
The HTTParty gem is built on top of net::http, with a sole purpose is to “Make HTTP fun again”. It encapsulates HTTP by providing support for all of the normal HTTP request methods, and automatically parses JSON and XML responses, based on the Content-Type of the response, to Ruby hashes. To put the cherry on the top, HTTParty also includes a CLI interface, to make experimenting with endpoints and configurations easy.
As seen in the code snippet above, HTTParty can convert data from an endpoint URL and then called the method parsed_response on the JSON data without explicitly using the JSON library. Compared the all the code needed to parse the same endpoint with net/http, this party gem simplifies the process and make it such a Ruby way to conduct business!
Excon
Another long-lived and well-supported project, Excon was designed to be simple, fast and it works great as HTTP clients and is particularly well-suited to usage in API clients. Like HTTParty, Excon is a wrapper library built on the net/http. Unlike other projects, Excon is not depended on by other gems as much (comparing to HTTParty, which happens to have the most gems depending on it, at just shy of 4000). It includes the standard list of helper methods and the ability to create named connections through Excon.new. These connections then can be reused across multiple requests to share options and improve performance.
Faraday
Faraday is an HTTP client library that aims to be a wrapper around common clients (such as the old faithful Net::HTTP). It embraces the concept of Rack middleware when processing the request/response cycle, hence caters to developers who need control. While HTTParty lock you into Net::HTTP, Faraday lets you choose from seven HTTP clients.
With a comprehensive documentation and easily the best looking site, Faraday’s goal is to provide a shared interface while enabling developers to use different implementations. It is truly an adapter gem in that sense.
Here is an example of how Faraday’s support of middleware to help you modify the request or response in a specific way.
Typhoeus
The last gem we will talk about in this post, Typhoeus is like a modern code version of the mythical beast with 100 serpent heads. It runs HTTP request in parallel while cleanly encapsulating handling logic, and supports concurrent requests without having to write any concurrent code. This makes Typhoeus the best choice if you are looking to maximize your requests per second.
Here is how multithreading looks with this nifty multitasking gem. (Threading is a process of making your Ruby programs do numerous things at the same time such as handling various web requests or many API connections)
Typhoeus is built on top of libcurl, a multiprotocol file transfer library for C language, which makes it very reliable and fast. Additionally, there are features like helpers for commonly used actions, caching and memorization, as well as their custom adapter for Faraday, to mix the best of both! In fact, Faraday is one of the gems that rely on Typhoeus to run.
There are many more HTTP clients in the Ruby ecosystem to choose from when interacting with JSON APIs. As your requests grow more complex, there are ones to favor over to best fit your needs. Another thing that would be helpful to keep in mind is, how well maintained these gems are, since the most updated one might provide you with the best support for your application.
Remember, always:
Sources:
