Whipping Up a Rails API Real Quick

In this blog, I concisely outline the basic steps of creating a Rails RESTful API.

jump to the code on GitHub

Tutorial

Steps

1. Create New Rails Project
2. Plan Models / Relationships
3. Generate Resources
4. Create / Migrate database
5. Set Up Controllers

1. Create New Rails Project

First things first. Assuming Rails is installed, enter the following command into your terminal replacing <my-project> with the current project name.

rails new <my-project> --api --database=postgresql

Flags: The --api flag will forgo including some of the extra junk a full Rails application has that we do not need. The --database flag 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. I type out my command and hit enter.

2. Plan Models / Relationships

While Rails is installing, it’s a great time to plan the models and relationships. Having a clear idea of these ahead of time can save a lot of headaches.

For my Evil Dog Catcher API, I am going to have two models: Catchers and Dogs. The relationships will be:

1. Catchers have many Dogs.
2. Dogs belong to Catchers.

3. Generate Resources

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: g is shorthand for generate. Also, you can list another model’s name as an attribute with a type of references to automatically create that model with a foreign key.

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 on the Dog model, but I have to manually go into the Catcher model set up a has_many :dogs.

4. Create / Migrate database

With all our files generated, it’s time to get the database going. First, I double check the migration files to make sure everything looks right.

Note line 6 of CreateDogs. Because 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 null: true.

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

Next, I test my progress in the following steps:

1. rails c or rails console opens the console.
2. In the console, I create a Catcher instance, Catcher.create(name: 'test'), and a Dog instance, Dog.create(name: ‘test’, catcher_id: 1)
3. I test the relationship by entering Catcher.find(1).dogs and 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”>]>

If there’s no errors, it’s time for the next step.

5. Set Up Controllers

For the final step, I will set up a basic controller and test it on the Rails server.

Then, I run rails s or rails server in the terminal. I open http://localhost:3000/catchers and I see that everything is working.

For production purposes, you can open the CORS of this API to any website. First, install the CORS gem. Open the Gemfile, uncomment ‘rack-cors’, and run bundle install.

Next, access the config/application file. Find the class Application and — 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 origins before deployment or this API will be available to anyone.

Conclusion

At this point the basic API has been created. The next steps will be to open up the CORS for whatever other sites will pull from it, and I set up the controllers to perform whatever actions you want to perform.

Hope this is helpful! Mostly I wanted to create a quick reference for setting up an API. If you have suggestions / corrections. Please comment or email me at jason.melton2@gmail.com.