🚨🚨🚨 Cerulean is no longer maintained. Check out Fern, which is mostly API-compatible.

Cerulean is a reasonably unopinionated DSL for writing APIs in Rails.

Add a reference to Cerulean in your Gemfile:

gem 'cerulean'

Include Cerulean in your base controller class:

class ApplicationController < ActionController::API
  include Cerulean
end

Or include it in individual controllers as-needed:

class PostsController < ApplicationController
  include Cerulean
end

Cerulean provides methods for get, post, put, and delete.

The basic structure of a request looks like this:

get :index do
  request do
    # ...
  end
end

Cerulen provides basic parameter validation for a variety of common data types.

Request parameters are defined in a params block:

get :show do
  params do
    param :id, Integer, required: true
  end
  request do
    # ...
  end
end

While the raw params can still be accessed inside of your request block via the params variable, when declaring a params block for an endpoint, you should use declared instead.

For example, for the above endpoint, you could access the id via declared[:id].

The following param types are supported:

• String
• Integer
• Float
• Boolean
• Date
• DateTime

Arrays are also supported using Array[Foo] where Foo is one of the primitive types listed above.

• min
• max
• required
• values
• default
• null

When parameter validation fails, a Cerulean::InvalidParams exception will be raised. Validation error messages can be accessed via the errors property of the exception. For example:

{
  username: ['is required'],
  length: ['is not a float'],
  age: ['must be less than or equal to 100']
}

Presenters are classes which satisfy two criteria:

• They accept a model instance as an argument to their constructor.
• They implement an as_json method.

Cerulean provides the presenter method to declare a presenter for an endpoint, and a present method to instantiate that presenter, call as_json, and automatically return the result.

class FooPresenter
  def initialize(foo)
    @foo = foo
  end

  def as_json()
    @foo.as_json
  end
end

get :show do
  params do
    param :id, Integer, required: true
  end
  presenter FooPresenter
  request do
    present Foo.find(declared[:id])
  end
end

Forms are classes which accept a params hash as an argument to their constructor.

Cerulean provides the form method for declaring the form for an endpoint. The form will be instantiated automatically using the params hash from the action and can be accessed via @form.

{
  "name": "Hello World"
}

class FooForm
  def initialize(params)
    @foo = params.has_key?(:id) && Foo.find_by(id: params[:id]) || Foo.new
  end

  attribute :name, String

  def errors
    @foo.errors
  end

  def valid?
    build
    @foo.valid?
  end

  def save!
    build
    @foo.save!
    @foo
  end

  private

  def build
    @foo.name = self.name
  end
end

post :create do
  form FooForm
  presenter FooPresenter
  request do
    present @form.save!
  end
end

The form method supports targeting a specific key in the request JSON for form binding.

{
  "foo": {
    "name": "Hello World"
  }
}

post :create do
  form :foo, FooForm
  # ...
end

Copyright (c) 2017 Kyle Kestell

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.