In this blog, I attempt a concise outline of the basic steps to create a Ruby on Rails RESTful API.
- Create New Rails Project
- Plan Models / Relationships
- Generate Resources
- Create / Migrate database
- Set Up Controllers
Assuming Rails is installed, enter the following command into your terminal replacing
<my-project> with the project name.
rails new <my-project> --api --database=postgresql
--apiflag will forgo some of the extra junk a full Rails app has that I do not need. The
--databaseflag lets you specify the type of database you prefer. I chose PostgreSQL. If you do not include this flag, the default database will be SQLite.
For demonstration, I’ll create an Evil Dog Catcher API.
Check out this dog catcher toy I found on Google images:
What maladjusted kid wants to play with dog catcher toys? Yikes.
While Rails installs, now is a great time to plan the models and relationships. Having a clear idea of these ahead of time saves a lot of headaches.
I'm going with two models, Catchers and Dogs.
The relationships will be:
- Catchers have many Dogs.
- Dogs belong to Catchers.
Next, I’ll generate resources. This command quickly sets up migrations, models, controllers, and routes for each model name.
rails generate resource <model> <attribute>:<type> <attribute>:<type>
Tips: You can use
gas shorthand for
generate. Also, you can list another model’s name as an attribute with a type of
referencesto automatically add a foreign key to that model.
These will be my resource commands:
rails g resource catcher name:string city:string rails g resource dog name:string breed:string catcher:references
References gives me a foreign key for the Dog model, but I have to manually go into the Catcher model add
class Dog < ApplicationRecord belongs_to :catcher # set up by catcher:references end class Catcher < ApplicationRecord has_many :dogs # add this line end
With all the files generated, it’s time to get the database going. First, I double check the migration files to make sure everything looks right.
class CreateCatchers < ActiveRecord::Migration[6.0] def change create_table :catchers do |t| t.string :name t.string :city t.timestamps end end end class CreateDogs < ActiveRecord::Migration[6.0] def change create_table :dogs do |t| t.string :name t.string :breed t.references :catcher, null: false, foreign_key: true t.timestamps end end end
Note: Notice the line under
CreateDogsthat starts with
null: false, I will not be able to create a Dog unless it has the foreign key of a Catcher. If you want to be able to create models without this, set
Since everything looks right, I will now create and migrate my database by entering these commands into the terminal:
rails db:create rails db:migrate
I double check my progress in the following steps:
In the terminal,
rails consoleopens the console.
In the console, I create a Catcher instance,
Catcher.create(name: 'test'), and a Dog instance,
Dog.create(name: ‘test’, catcher_id: 1). There should be no errors.
I test the relationships by entering
Catcher.find(1).dogs. This finds the Catcher with an id of 1 and shows me if they have any dogs. I get:
<ActiveRecord::Associations::CollectionProxy [#<Dog id: 1, name: “test”, breed: nil, catcher_id: 1, created_at: “2020–10–04 06:39:15”, updated_at: “2020–10–04 06:39:15”>]>
Since there’s no errors, it’s time for the next step.
For the final step, I set up a basic index controller and test it on the Rails server.
class CatchersController < ApplicationController def index # grab an array of all catchers in db catchers = Catcher.all # render a json object of all catchers # include a sub array of their dogs with each catcher render json: catchers, include: :dogs end end
rails s or
rails server in the terminal. I open
http://localhost:3000/catchers in the browser and make sure everything is working.
Tip: For production purposes, you can open the CORS of this API to any website. Install the CORS gem by opening the Gemfile, uncommenting
gem ‘rack-cors’, and run
# Use Rack CORS for handling Cross-Origin Resource Sharing (CORS), making cross-origin AJAX possible gem 'rack-cors'
Next, access the
config/applicationfile. Find the class
Applicationand — without altering any of the default code — insert the following:
config.middleware.insert_before 0, Rack::Cors do allow do origins '*' resource '*', :headers => :any, :methods => [:get, :post, :delete, :put, :patch, :options, :head], :max_age => 0 end end
Remember to change the
originsbefore deployment or this API will be available to anyone.
At this point the basic API is up. The next steps will be to open up the CORS for whatever other site(s) will pull from it and set up the controllers to perform whatever actions I want the back-end to perform.
Hope this is helpful! Mostly I wanted a quick reference for setting up an API. I know Rails has a million aliases and shortcuts. If you have suggestions / corrections. Please comment or email me at