mini_api

Mini Api

A gem to standardize json responses in Rails applications, highly inspired on Responders

Table of Contents

• Usage
  • Respondering json
  • Success and failure actions
  • Transform keys
• Overriding response
• Pagination
• Contributing
• License

Installation

Add this line to your application's Gemfile:

gem "mini_api"

And then execute:

$ bundle

You must install Kaminari to handle pagination and Active Model Serializers to handle data serialization

Usage

After install the gem, include the MiniApi module into your ApplicationController or other parent controller

class ApplicationController < ActionController::Base
  include MiniApi
end

This include three methods in your controllers: render_json, page and per_page

The methods page and per_page will handle the params: page and per_page respectively

Respondering json

In your controller you only need to call the render_json method informing what you want to send. Example:

class UsersController < ApplicationController
  def show
    user = User.find(params[:id])

    render_json user
  end
end

The generated json will be like:

{
  "success": true,
  "data": { }, // user data here
  "message": ""
}

If your data is a ActiveRecord::Relation, the behavior is the same, with pagination data added to meta key

class UsersController < ApplicationController
  def index
    users = User.all

    render_json users
  end
end

The response will be like:

{
  "success": true,
  "data": { }, // users here
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "total_pages": 10,
    "total_records": 100
  }
}

Success and failure actions

Many times, our controller actions need to persist or validate some data coming from request, the default approach to do that is like:

class UsersController < ApplicationController
  def new
    user = User.new(user_params)

    if user.save
      render json: user, status: :created
    else
      render json: user.errors.messages, status: :unprocessable_entity
    end
  end
end

But, with mini_api, you could simplify the action doing like:

class UsersController < ApplicationController
  def new
    user = User.new(user_params)

    user.save

    render_json user
  end
end

If the user was created successfully, then the response will be like:

{
  "success": true,
  "data": {  }, // user data here
  "message": "User was successfully created."
}

with status_code 201

But, if user is not valid, then the response will be like:

{
  "success": false,
  "errors": {  }, // user errors here
  "message": "User could not be created."
}

witht status_code 422

The message key is different based on actions on informed model: create, update, and destroy

You can respond any type of data, but ActiveRecord/ActiveModel::Model and ActiveRecord::Relation has a special treatment as shown above

Transform keys

It is possible to transform the keys of request and response. By default, will transform to snake_case, but the possible values are snake_case, camel_lower and camel_case

To change the transform operation, simply adds a initializer on initilizations folder with content:

MiniApi::Config.configure do |config|
  config.transform_params_keys_to = :snake_case
  config.transform_response_keys_to = :camel_lower
end

The option transform_params_keys_to will transform request params. The option transform_response_keys_to will transform responses.

Overriding response

You can override the status, message and sucess keys simply informing values to render_json. Example:

class UsersController < ApplicationController
  def new
    user = User.new(user_params)

    if user.save
      render_json user, message: 'custom message'
    else
      render_json user.errors.messages, status: :bad_request, success: true
    end
  end
end

This way, the response will contain the informed values

Pagination

This plugin handle pagination using kaminari gem. The params to evaluate pagination are page and per_page

if no page is informed, by default will use page 1

Default value of per_page is 25. Only specific values are permitted to per_page, they are: 10, 25, 50, 100

If the value it is none of those, so the default value is used

Contributing

• Fork it
• Create your feature branch (git checkout -b my-new-feature)
• Commit your changes (git commit -am 'Add some feature')
• Push to the branch (git push origin my-new-feature)
• Create new Pull Request

License

The gem is available as open source under the terms of the MIT License.