Chapter 11


We are finally done reviewing the basics of building web APIs. Now, we are ready to create a complete web API using Rails 5. Through this module, we will learn more about the topics we’ve already studied, while also getting more into testing, architecture and best practices.

So, what are we going to build?

11.1. Module Introduction

This module is all about building a real-world web API using Rails 5. The API we are going to build is called Alexandria, a complete e-commerce platform that sells… books!

The context for this API is as follows: we are a small startup beginning a new project, namely building an e-commerce website that exclusively sells digital books. We’ve decided to build a web API with Rails 5 that will be used by a front-end JavaScript SPA (Single-Page Application) and an iOS mobile application. Since we will have two front-end applications, it makes sense to create a shared backend application.

At first, this API won’t be following all REST constraints, therefore it cannot be considered “RESTful”. That’s something we will change in module 3 when we learn more about what creating RESTful APIs really means.

11.2. Picking The Right Tool For The Job

With a name like Alexandria, our API has to be epic. Hopefully, it won’t get burned down…

Let’s go through the different technologies we will be using.

11.2.1. Rails 5 API Mode

We will be using the new version of Rails (version 5) and the API mode it comes with to build our application. You might be wondering, “Why use Rails to build an API instead of Sinatra?” From my personal experience, any big application built with Sinatra will turn into something similar to Rails.

When building a large application, Rails comes with everything you need, from managing the database to controllers and models. It’s easier than making everything from scratch using ActiveRecord (or Sequel), Sinatra, or a bunch of other gems, and creating something that will probably end up looking like Rails anyway.

What you will learn in this module can easily be applied to any Ruby API, especially when using Rails and mounting Sinatra or Grape to handle the controller layer.

If you’re not convinced about using Rails for web APIs, here is a list of things Rails will do for you - for free.

  • Auto-Reloading
  • Development/Test/Production Mode
  • Logging
  • Protection against IP spoofing attacks and timing attacks
  • Conditional GETs with ETag and Last-Modified
  • HEAD requests are automatically converted to GET requests, but will only return the headers
  • Resourceful Routing
  • URL Generation
  • Header and Redirection Responses
  • Page/Action/Fragment Caching
  • Basic, Digest, and Token Authentication
  • Generators
  • Plugins & Rails Engines
  • Migrations

The API mode in Rails 5 generates applications that are stripped of everything that’s not necessary for APIs; for example, HTML rendering.

11.2.2. SQLite & PostgreSQL

We will start by using SQLite since it’s already configured and easy to use. Later on, we will switch to PostgreSQL to implement full-text search.

11.2.3. Testing

We will follow a TDD (Test-Driven Development) approach to create this application. This means we will be writing tests first, making them fail (RED), implementing the appropriate code to make them pass (GREEN), and then refactoring.

This is known as the red-green-refactor flow. It allows developers to write better code, but requires some time to get used to.

The first tests we write will follow this cycle strictly. The following tests and implementations will be more liberal. This is to avoid boring you by showing too many testing cycles, which can become quite tedious to go through in a book. In the following chapters, we might write the tests before or after the actual implementation. Sometimes, we will write one test at a time, and other times you will be given an entire test file. For real projects, I recommend using the red-green-refactor cycle when coding.

If you don’t like TDD or if you’re just getting started with automated testing, I honestly think writing tests after the implementation is easier. It will ease you in the process without making you change the way you work too much. Once you feel ready, you can give TDD a try.

The code and tests in this module are organized in a way to teach you as much as possible about different subjects.

To write tests, we will be using rspec, factory_bot, database_cleaner and webmock.

11.2.4. Others

We will be using many other tools along the way, but we’ll learn more about them as we actually use them.

11.3. Module Structure

Here’s a rundown of the different sections in this module.

  • Chapter 11 - Module Introduction (in other words, what you’re reading now)
  • Chapter 12 - Alexandria: Setup Time
  • Chapter 13 - Adding Books and Authors
  • Chapter 14 - Exposing The Books Resource
  • Chapter 15 - Building Representations
  • Chapter 16 - The First Query Builder: Paginator
  • Chapter 17 - Query Builders
  • Chapter 18 - Representation Builders
  • Chapter 19 - Finishing up our controllers
  • Chapter 20 - Full-Text search
  • Chapter 21 - Client Authentication
  • Chapter 22 - Users
  • Chapter 23 - User Authentication and Authorization
  • Chapter 24 - Selling Books
  • Chapter 25 - Compression, Caching, CORS, Versioning
  • Chapter 26 - Writing documentation
  • Chapter 27 - Deployment
  • Chapter 28 - Module Conclusion

11.4. RESTful?

The Alexandria API won’t be RESTful… for now.

We’ll learn more about that in the third module, but for now I can tell you that we won’t be respecting some of the REST constraints.