I recently sat down to create a Rails API and found myself googling like mad. At the end of the day, I had tabs galore and knew there had to be a better way.

This guide is intended for developers comfortable with Ruby on Rails. You will be able to set up a Rails API with CRUD functionality and (hopefully) not open a million tabs in the process.

Preview

• Create the API with a PostgresSQL Database
• Add the Project to Github
• Create the Schema, Models, and Routes
• Create Relationships Between Models
• Set Up Cors
• Create and Reorganize Controllers
• Create an AuthController to Handle JWT
• Change the Gem File
• Hide JWT Tokens
• Set Up Other Controllers
• Change Routes
• Get Everything Up and Running

Let's get started!

Creating the API and Hooking it up to PostgresSQL

You’ll want to start out cding into a folder to store your project.

In your terminal type:

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

This creates a new Rails project specifically for API use. This command populates specific gems in your gem folder and forgoes view files. It also hooks your database up to postgresSQL. You do not necessarily need to hook up your database to Postgres, but platforms such as Heroku require it.

Adding the New Project to Github

You can connect your project to your Github at any time. It's recommended to start early so you can save as you go.

In your Github account, create a new repository. Go back to your terminal, and while in your project directory, type the following:

git init git add . git commit -m “first commit” git remote add origin <http url> git remote -v git push origin git checkout -b new_branch 

These commands link your project up to Github and ensure you have a new branch to work on.

Create Your Models, Routes, and Database

This section will be largely determined by the needs of your project. Rails documents a list of generators that you may find useful.

Since we are using bcrypt to encrypt passwords, write a password_digest column on the user table. The resource generator will create a user table, a model, and restful routes for a user.

rails generate resource User username:string password_digest:string

Create another resource generator for a post model. Notice the shorthand for generator and title--the word string can be omitted, but not any other data type.

rails g resource Post title content user_id:integer

Create Relations Between Models

In the users model, just below the class declaration, type the following:

has_many :posts has_secure_password 

Type the following in the post model:

belongs_to :user

A few things to take note of in these models is that has_many relationships take in a plural and the belongs_to does not. The has_secure_password validation gives us access to bycrypt methods in controller (more on that later) which relies on the password_digest from the previously created user table.

Setting up Cors

Cors is middleware that allows your app to make API calls from the front-end.

There’s three steps you need to do to hook this up.

Step 1.

In your project directory, navigate to your gem file and uncomment:

gem ‘rack-cors’

Step 2.

Navigate to config/application.rb and find this class declaration:

class Application < Rails::Application

Beneath the class declaration, paste this code. Do not modify anything else.

config.middleware.insert_before 0, Rack::Cors do allow do origins '*' resource '*', headers: :any, methods: [:get, :post] end end 

Step 3.

In config/initializers/cors.rb uncomment and change

origins ‘examples’

to

origins ‘*’

Rails.application.config.middleware.insert_before 0, Rack::Cors do allow do origins '*' resource '*', headers: :any, methods: [:get, :post, :put, :patch, :delete, :options, :head] end end 

Cors errors can be incredibly frustrating to debug, so I recommend taking the time to carefully comb through the files to uncomment and add the code laid out in these steps.

Create and Reorganize Your Controllers

When we created our models using the generator command, we also created our controllers. However, these controllers are currently in the wrong directory. What’s up with API/V1? API convention states that you include the version in your url.

You will also need to add an AuthController which will manage user security.

From your terminal, navigate to the controllers directly and type the following:

mkdir api cd api mkdir v1 touch auth_controller.rb 

Move all your controllers into the V1 directory except for ApplicationController.

Precede all your controllers with Api::V1:: like this example:

class Api::V1::UsersController < ApplicationController

This will ensure your routes are consistent.

Create an AuthController to Handle JWT Tokens and User Authentication

We are about half-way into creating our Rails API.

In the newly created AuthController, add the following code:

 class Api::V1::AuthController < ApplicationController skip_before_action :authorized, only: [:create] def create user = User.find_by(username: user_login_params[:username]) if user && user.authenticate(user_login_params[:password]) token = issue_token(user) render json: {user: UserSerializer.new(user), jwt: token} else render json: {error: 'That user could not be found'}, status: 401 end end def show user = User.find_by(id: user_id) if logged_in? render json: user else render json: { error: 'No user could be found'}, status: 401 end end private def user_login_params params.require(:user).permit(:username, :password) end end 

A note on the methods in this class:
The AuthController’s job is to create a session for our user each time they log into the site.

User.authenticate comes from the bcrypt gem.

The skip_before_action validation ensures the user will be able to make an account via the create method. Issue token enables us to use JWT tokens, and is a method we’ll go over later in the application controller. We are using serializers here to better format our JSON.

The logged_in? action in the show method is also inherited from application controller.

Change the Gem File

To get access to some of these actions, go to your gem file and uncomment the following:

gem bcrypt gem 'jbuilder', '~> 2.7' 

In order to use JWT and serializers, add:

gem "jwt", "~> 2.2" gem "active_model_serializers", "~> 0.10.10" 

Please note that your gem versions may vary. Refer to the documentation for the most up-to-date versions.

Set Up and Hide Your JWT Token

Refrain from committing to github until after your secret key and the corresponding file is created.

JWT tokens are industry standard security credentials. These protocols are most commonly used for logging in users by storing a token in their localstorage. You can create your own jwt token by going to the website and changing your-256-bit-secret.

To create your JWT token (and hide it, too) go to your Application controller, add the following:

 class ApplicationController < ActionController::API before_action :authorized def jwt_key Rails.application.credentials.jwt_key end def issue_token(user) JWT.encode({user_id: user.id}, jwt_key, 'HS256') end def decoded_token begin JWT.decode(token, jwt_key, true, { :algorithm => 'HS256' }) rescue JWT::DecodeError [{error: "Invalid Token"}] end end def authorized render json: { message: 'Please log in' }, status: :unauthorized unless logged_in? end def token request.headers['Authorization'] end def user_id decoded_token.first['user_id'] end def current_user @user ||= User.find_by(id: user_id) end def logged_in? !!current_user end end 

Notice the jwt_key variable? We will be hiding this code with the following command.

Hide the secret key by typing in your terminal:

EDITOR="code --wait" rails credentials:edit

Add the hash:

jwt_key: your-256-bit-secret

You can also hide other information in the same way. Once you are done adding your secret keys, save and close the file. For a more in-depth look at how Rails credentials work, check out Derya Tanriverdi ‘s tutorial The Secret to Rails.

You are now free to resume committing to Github.

Having trouble accessing this secret key when migrating to Heroku? Try this command out in your heroku terminal:

heroku config:set RAILS_MASTER_KEY=<your master key>

Your master key is NOT the JWT token key we created, but the Rails master key found in the masterkey file.

Set Up Your Other Controllers

Code the RESTful actions that seem appropriate to your controllers: index, create, show, update, destroy. Your UsersController should also use the jwt_token and current_user methods we created in the application controller.

class Api::V1::UsersController < ApplicationController skip_before_action :authorized, only: [:create] def profile @user = User.find(params[:id]) render json: {user: current_user} end def create @user = User.new(user_params) if @user.valid? @user.save @token = encode_token(@user) render json: { user: @user, jwt: @token } else render json: { error: 'failed to create user' }, status: :not_acceptable end end 

Add Serializers (optional)

Serializers are a good idea for projects with a number of associations. You can generate a serializer from the terminal using the rails g command.

rails g serializer user

This will create a serializer folder and file.

In your newly created serializer, write the following:

class UserSerializer < ActiveModel::Serializer attributes :id, :username end 

Depending on your project's needs, you may need to add additional methods and attributes.

Change Routes

Rails created routes for you through the resources generator. However, these routes are in the wrong places. Reorganize the file and create custom routes for the auth and user controllers.

Rails.application.routes.draw do # For details on the DSL available within this file, see https://guides.rubyonrails.org/routing.html namespace :api do namespace :v1 do resources :posts resources :users post '/login', to: 'auth#create' get '/current_user', to: 'auth#show' post '/sign_up', to: 'users#create' end end end 

Getting Rails Up and Running

Finally your Rails app is ready to function as an API. Run these last commands from the terminal.

Bundle install Rails db:create Rails db:migrate Rails s 

Summary

And there you have it! We set up a Rails API by connecting it to a postgresSQL database, added JWT tokens for user security, and added serializers. In addition, we connected our project to github, hid our secret key, changed routes, and enabled cors and bcrypt. As a final exercise, use Postman to test out your routes, or use the Rails console to create a few users.