Lesson Weekend

Building a RESTful API

A REST API uses RESTful routing just like the routing we've already used in our Rails applications. It's also stateless, which means our API application and the applications our API communicates with don't need to know about each other's state. In our case, our Rails API will pass information to (and receive information from) other applications using JSON.

Even though we're making our APIs RESTful, they won't meet all the criteria of a true REST API. A REST API has other constraints that are beyond the scope of what we can cover in a single course section. In fact, many APIs on the web that claim to be RESTful don't fully adhere to RESTful constraints. To learn more about these constraints, see What Restful Actually Means.

Rails API Files and Directories

Let's take a look at the files Rails 5 provides for us when we scaffold an API-only project. We'll start by putting the following command in the console:

$ rails new app_name --api

This will set up a new Rails project in API mode. If you haven't specified that Rails applications should use Postgres on your machine, you'll also need to append -d postgresql -T to the rails new command above.


First, let's check our Gemfile. A Rails API application automatically ships with fewer gems than a standard Rails application. For instance, we no longer need gems related to jQuery because an API-only application has minimal views (if any at all).

Before we bundle, make sure to add the faker gem as we will be using it soon.

Next, we'll move on to our app directory. We still have folders for models, views and controllers. The M in a Rails MVC is untouched because we still use ActiveRecord to query the database.


We also have a views folder, which may seem strange since our application will be API-only. However, it might be useful to have some kind of interface for admins. We could also add documentation to our applications and provide a login for users to get an authentication token.


There's a subtle but significant change in our controllers folder. Our application_controller.rb now has the following code:

class ApplicationController < ActionController::API

Unlike the ApplicationController class in a standard Rails application, which inherits from ActionController::Base, our controllers now inherit from ActiveController::API.

Why do Rails APIs inherit from API instead of Base? Controllers in a vanilla Rails application process data and render views. However, controllers in a Rails API application are primarily focused on processing data, not rendering views. Our controllers have different concerns so the code handling these concerns is different, too.

In a Rails API, the controller processes data which is then exposed in the form of an API endpoint. An endpoint is an object (or objects) that our API provides to users — in other words, it's the interface that allows applications to communicate with each other.

Our endpoints will be URLs that use RESTful routing. We'll define these routes in config/routes.rb just as we do with a vanilla Rails application. For example, the endpoint /books/show/41 will provide information about a book object with an ID of 41. It's the exact same routing you've used to build out other Rails applications in the past.


There’s one other key difference between a vanilla Rails application and a Rails API. A vanilla application comes with additional middleware that isn’t needed in a Rails API application. What exactly is middleware?

We don't cover middleware in depth in this course, but in the context of Rails, middleware acts as a bridge between our application and the server running our application. In fact, both Sinatra and Rails are built entirely on Rack middleware. It’s worth exploring middleware further when you have free time to do so.

Now that we've covered some of the major similarities — and differences — between a vanilla Rails application and an API-only application, let's get coding and build our first API endpoint.

Lesson 2 of 19
Last updated August 7, 2022