adding a small API to a web application

Question

I have a rails application with some standard routes, and I would like to add some API endpoints into it.

I figure I just have to add some routes (probably under a scope '/api'), create some new controllers that extend ActionController::API, and then perhaps do something so rails magically knows how to render the JSON data.

Are there any guides on how to do this? Everything I can find talks about creating 'API only' applications, but doesn't discuss adding a few API endpoints to an existing web application.

edit: I am specifically looking for rails 5 solutions

Answer 1

The difference between a "classical" or API only application are pretty small. The API only app scales away some of the middleware and components that are not needed in an API.

Otherwise the steps of building the actual API components are pretty much identical.

You will want to start by choosing a different superclass for your API controllers. Your API controllers don't need all the junk on ApplicationController and you will be treating quite a few aspects such as authentication differently.

Rails 5 has ActionController::API, In previous versions you would use ActionController::Metal and include the modules needed.

# app/controllers/api_controller.rb
class ApiController < ActionController::API
  # Do whatever you would do in ApplicationController
end

You then setup your routes:

namespace :api, defaults: { format: :json } do
  resources :things
end

And controllers:

module API
  class ThingsController < ApiController

    before_action :set_thing, except: [:create, :index]

    def show
      render json: @thing
    end

    def index
      render json: @things = Thing.all
    end

    def create
      @thing = Thing.create(thing_params)

      if @thing.save
        head :created, location: [:api, @thing]
      else
        render json: @thing.errors, status: :bad_entity
      end
    end
    # ...
  end
end

There are quite a few aspects to building an API such as versioning and JSON serialization strategies and you'll find plenty of tutorials on the subject - just don't get hung up on the API only part.

Answer 2

1. Decide on an API data format (in this case we'll use JSON)
2. Figure out what your endpoints will be (for example let's say you're creating a products#create endpoint)
3. Decide on an API scoping and versioning scheme (in this case v1)
4. In your config/routes.rb add the routes seen below
5. Create a directory in your controller directory named v1

6. Create a controller in that v1 directory like the one below

   #goes in routes
   namespace 'v1', defaults: {format: 'json'} do
     resources :products, only: [:create] 
   end
   
   #controller
   module V1
     class ProductsController < ActionController::API
   
       def create
         #some code
       end
     end
   end
   

Random Wisdoms

• Try to think about your end point as thoroughly as possible. I don't know if you're planning for someone to consume this API or if you will be the only person using it but think about each end point from the perspective of what will be consuming it; this will save you lots of refactoring and redesign time.
• You should also look into the pattern of using serializers to help with you object decoration before serving them to your endpoints.
• Make sure that you think about how you want handle errors, do you want them to fail silently, do you want to give feed back to the consumer etc. Whatever you choose to do just make sure you're consistent.

Look here for some advice:

https://www.codementor.io/franzejr/creating-simple-api-with-rails-du108148l

https://www.airpair.com/ruby-on-rails/posts/building-a-restful-api-in-a-rails-application