Recently, I was tasked to build a JSON API for a project in the Backend Engineering Program at Turing School of Software & Design. While the visual gratification was somewhat anti-climactic (Look! I spent 7 days and a lot of hours to make a bunch of hashes show up on a page! My non-tech friends were not impressed.), I was personally looking forward to this project to understand exactly what an API was, and what it can give you access to.
In my former life, I was a Digital Marketer. I was responsible for the business’ website, mobile app and email marketing channel. In my time with the business, we talked about APIs a lot (and I mean A LOT), but I never really wrapped my brain around what they were. Basically they were magical things that got called from somewhere and gave us access to our customer data, though sometimes made everything break if we sent too many requests per second. Silent, but deadly.
Here’s what I learned in my exploration: an API, or Application Protocol Interface, allows us to share data between applications.This can be exceptionally helpful when you’d like to plug into features of another application. For example, if you wanted your application to allow users to add an event created to a users Google calendar, you could simply use the Google Calendar API from within your application.
Easy enough? Great. Let’s start building an API. Here’s what you’ll need:
#1: A new rails app with --api.
$ rails new rales_engine -T -d postgresql --api
#2: Fast JSON API gem (gem ‘fast_jsonapi’). This will allow you to Serialize your data to only display the information you’d like to share with the world.
#3: A database, any necessary tables, and data. I used PostgreSQL, and sales data that includes merchants, customers, items, invoices, invoice items and transactions.
Let’s say we want to create an endpoint (a unique URL that represents a collection of objects and attributes) to find a merchant by id. First things first, we’ll want to write a test (I use RSpec).
Now we can TDD our way through the problem, starting with the fact that we need a route.
This project called for a lot of custom endpoints, like most_items, most_revenue, favorite_customer, etc. Rather than making a large junk drawer style controller for merchants with custom actions, my goal in this project was to stick with restful conventions, utilizing only show or index depending on how many records are being returned in the query.
At the end of the day, this meant a lot of controllers, but accomplishes Single Responsibility Principle (SRP) like a champ.
When it comes to displaying merchant info in my API, I only want their id and name displayed. In order to customize my JSON and remove created_at and updated_at from my results, I’ll need to create a Serializer.
Thank you Fast JSON API, now I will only share the data that I want to share.
Next we need to make our controller action. Since we’re looking for 1 record by ID, I routed this to my SearchController in a show action.
Let’s run Rails s and visit our new API endpoint. Success! It’s displaying the information that we intended.
Once I got the hang of creating endpoints to show all merchants, find a merchant by name, display all of a specific merchants items, etc. I was able to dive into some more complex problems in ActiveRecord. My personal favorite was an endpoint to display all revenue for all merchants on a specific day. Was it my favorite because it was fun? Not quite.
I built 3 different queries starting on 3 different tables before I landed somewhere that I was happy with in terms of accuracy and efficiency. But those are the problems that push you to learn, and to think in different ways. The gratification at cracking a problem you’ve been tackling for a while is also pretty top notch.
I’m leaving this project with a better understanding of APIs (they are not, in fact, magic), JSON customization, and an increased confidence in ActiveRecord.
Want to check out the full project? You can see it on my GitHub here: https://github.com/jalena-penaligon/rales_engine