Building great APIs in Ruby w/o Rails

von tobonaut

In this article I want to show a nice and clean way to create restful JSON-APIs in Ruby without Rails.

Rails is a very nice framework for creating web-applications in ruby and has a ton of great stuff in it. Of course it’s also possible to create APIs in rails, but if the application should be API-only the full rails stack is a bit overhead (we don’t need stuff loaded that is used for HTML rendering and so on).

Just for the reference: even for this usecase there is a really cool gem that strips down the rails stack to only the API related stuff: rails-api.

It’s simply added to a existing rails app or better the rails app is created using this gem:

rails-api new codebuddies-api

A sample controller that handles API requests could look like the following example:

class Api::PostsController < ActionController::Base
  before_filter :check_api_key
  before_filter :check_params, only: [:create]

  def create
    Post.create(post_params) if @errors.empty?    
    render json: { success: @errors.empty?, errors: @errors }


  def post_params
    params.require(:post).permit(:title, :body)

  def check_params
    @errors << "title can't be blank" unless post_params[:title]
    @errors << "body can't be blank" unless post_params[:body]

But in this article I want to show how easy the same stuff could be build without using rails.

A very handy library to build APIs without a lot of cluttered code is grape. It provides a own DSL to create beautiful and easy to maintian code.

The following snippet does the same as the controller above:

module Codebuddies
  class API < Grape::API
    version "v1", using: :header

    resource :posts do
      desc "Create a new blogpost"
      params do
        requires :title, type: String, desc: "The title of the blogpost"
        requires :body,  type: String, desc: "The body of the blogpost"
      post do
        Post.create(params) if @errors.empty?

and can be used in a plain ruby/rack application.

Ok, to be honest it’s not much less lines of code but in my oppinion it’s much better to read. The other benefits are the possibility to add inline documentation that can be exported or used for graphical test tools like swagger-ui. Validations are auto-generated from the parameter definition before each method.

Another very cool feature of grape is that you can version your API. That means you can create a new version of the API using the existend implementation and add or even override single methods.

Of course grape can be also used insinde of a rails or rails-api application and benefit of the goodies provided there but you see it’s not necessary to always take a sledgehammer to crack a nut ;-)