Simple, beginner steps: API with Rails!

Let's talk through some basics to building out an API in Rails.

Make sure you have rails installed first by running gem install rails! This assumes you already have a rails directory started. If not, run rails new [name] --api to start new.

1. Build out your resources

For the sake of this example, we're going to work with the following:

• Owner --< Pets >-- Pet Sitters
• An owner has many pets
• A pet sitter has many pets they take care of
• Through relationships apply

Let's build out our resources. We're going to use rails g resource because it will generate model, controller, migration and serializers for us.

rails g resource owner name phone:integer
rails g resource sitter name phone:integer active:boolean
rails g resource pet name age:integer sitter:references owner:references

This will build out our resources, and include the foreign keys in the pet migration. References will ensure the foreign keys cannot have a null value when we migrate and update the schema.

2. Add/confirm relationships

Once we've created our resources with the generator, let's make sure our relationships are correct. The resource generator automatically generated the belongs_to when we used references, but we need to go into the Owner and Sitter models and include:

In Owner:

has_many :pets, dependent: :destroy
has_many :sitters, through: :pets

In Sitter:

has_many :pets
has_many :owners, through: :pets

Now our relationships are confirmed. In the Pets model you should see:

belongs_to :owner
belongs_to :sitter

This is also a good time to think about whether any relationships will need dependent: :destroy . Obviously if an owner deletes their profile, the pets they own should be deleted as well. We included this in the Owner model.

3. Validations

Now that our models are linked, let's look at validations in our models. Let's assume an owner must be 16 or older to use our service, and a pet sitter must be 18 to be a pet sitter. Also, a pet cannot be created without a name.

In Owner model:

validates :age, numericality: {greater_than_or_equal_to: 16}

In Sitter model:

validates :age, numericality: {greater_than_or_equal_to: 18}

In Pet model:

validates :name, presence: true

These are the validations we've added in each of the models.

4. Routes

Let's take a look at our routes in Config >> Routes. Since we used the resource generator, we'll already see:

resources :owners
resources :sitters
resources :pets

This means that all default routes are currently open. Let's clean up what's accessible:

resources :owners, only: [:index, :show, :create, :destroy]
resources :sitters, only: [:index, :show, :create, :destroy]
resources :pets, only: [:index, :show]

We can define the routes any way we want to, but this is what we'll arbitrarily use for now.

5. Controllers

Now that we've got the routes, let's head for the Controllers and get some of the routes defined. Let's just look at an example of OwnersController:

def index
        render json: Owner.all, status: :ok
end

def show
        render json: Owner.find(params[:id]), status: :found
end

def create
        render json: Owner.create!(owner_params), status: :created
end

def destroy
        Owner.find(params[:id].destroy
        head :no_content
end

private

def owner_params
        params.permit(:name, :phone, :age)
end

Make sure each Controller has routes defined for each route we've specified in our Config >> Routes. Technically, we didn't really need strong params for this, but I wanted to show an example. In the private methods of the controller, I've defined the strong params, which are the only params that will allowed to be passed.

!!! I've used find because it throws an error. I've also added the bang operator in the create method. In our ApplicationController, you would find something like this:

class ApplicationController < ActionController::API
  include ActionController::Cookies

  rescue_from ActiveRecord::RecordNotFound, with: :not_found
  rescue_from ActiveRecord::RecordInvalid, with: :render_unprocessable_entity

  private

  def not_found(error)
    render json: {error: "#{error.model} not found"}, status: :not_found
  end

  def render_unprocessable_entity(invalid)
    render json: {errors: invalid.record.errors.full_messages}, status: :unprocessable_entity
  end

end

All of our controllers inherit from ApplicationController, so we can write these rescues only once and they will be applicable for any of our Controllers that need them.

6. Serializers

First, you need to ensure that the serializer gem is in the Gemfile. If it's not, add gem "active_model_serializers", "~> 0.10.12"

Our resource generator already generated serializers for each model when we used the resource generator. We can use those serializers to limit what we receive in our responses. Anything in the related Controller will default to the serializer with the matching name, unless you specify otherwise. In our OwnerController, that would look like:

render json: <something>, serializer: <CustomSerializerName>, status: :ok

If you'll be using the default serializer with the corresponding name, you can omit the serializer specification in the Controller. However, let's say we have two serializers for Owners.

1. One default for index, so we see all owners with their :id, :name, :age, :phone like so:

class OwnerSerializer < ActiveModel::Serializer
     attributes :id, :name, :age, :phone

1. One custom serializer for show, so when we access individual owner info their pets are also returned:

class OwnerIdSerializer < ActiveModel::Serializer
     attributes :id, :name, :age, :phone
     has_many :pets

If we call that custom serializer in our show method:

def show
     render json: Owner.find(params[:id]), serializer: OwnerIdSerializer, status: :ok

end