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?
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!
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.
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.
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.
The API mode in Rails 5 generates applications that are stripped of everything that’s not necessary for APIs; for example, HTML rendering.
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.
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
We will be using many other tools along the way, but we’ll learn more about them as we actually use them.
Here’s a rundown of the different sections in this module.
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.