Api::ResponseBuilder

Example

#app/controllers/api/v1/application_controller.rb
module Api
 module V1
 class ApplicationController < ActionController::API
 def serializer_responder(resource, config = {})
 response = ::Api::ResponseBuilder::Main.new(resource, config, params).response
 render json: response, status: response[:status_code]
 end
 end
 end
end
# app/serializers/v1/user_serializer.rb
module V1
 # Serializer for User model
 class UserSerializer < ::ActiveModel::Serializer
 attributes :id,
 :firstname,
 :lastname,
 :phone_number,
 :email
 end
end
# app/controllers/api/v1/users_controller.rb
module Api
 module V1
 # Defines endpoints for CRUD operations on user model
 class UsersController < ::Api::V1::ApplicationController
 def index
 users = User.all
 serializer_responder(users, serializer: ::V1::UserSerializer)
 end
 end
 end
end

{
 "status": "success", 
 "body" : 
 [
 {
 "id": 1,
 "firstname": "Kalidas",
 "lastname": "M",
 "phone_number": "+919876543210",
 "email": "kalidasm610@gmail.com"
 },
 {
 "id": 2,
 "firstname": "Dass",
 "lastname": "Mk",
 "phone_number": "+919876543211",
 "email": ""
 }
 ],
 "status_code": "ok"
}

Installation

gem 'api-response_builder'

$ bundle

$ gem install api-response_builder

Usage

ApplicationController - Setup

 module Api
 module V1
 class ApplicationController < ActionController::API
 # action callbacks
 # Global Exception Handler for Api Exceptions and StandardError
 rescue_from ::Api::Exception, StandardError do |e|
 handle_api_exception(e)
 end
 # Global exception handlers for ActiveRecord Exceptions
 rescue_from ::ActiveRecord::RecordNotFound, with: :render_record_not_found
 rescue_from ::ActiveRecord::RecordInvalid, with: :render_record_invalid
 rescue_from ::ActiveRecord::RecordNotDestroyed, with: :render_forbidden
 # Public methods
 def handle_api_exception(e)
 response = ::Api::ResponseBuilder::Main.new(e, {}, params).response
 render json: response, status: response[:status_code]
 end
 def render_record_not_found
 handle_api_exception ::Api::Exception.new(
 ::Api::Exception.record_not_found
 )
 end
 def render_internal_server_error
 handle_api_exception ::Api::Exception.new(
 ::Api::Exception.internal_server_error
 )
 end
 def render_record_invalid(e)
 # If exception message is not included in arguments, locale message
 # (if present) for record invalid exception will be returned in resp
 exception_message = e.record.errors.full_messages
 exception = ::Api::Exception.new(
 ::Api::Exception.record_invalid, exception_message
 )
 handle_api_exception(exception)
 end
 def render_forbidden
 handle_api_exception ::Api::Exception.new(
 ::Api::Exception.forbidden_resource
 )
 end
 def serializer_responder(resource, config = {})
 response = ::Api::ResponseBuilder::Main.new(resource, config, params).response
 # response object also contains corresponding http status code under the key :status_code
 # Including `Http Status Code` as part of API response is generally considered as good practice
 # If all your api responses should have `200 OK` as status code, omit status key in render method
 # Rails, by default, set status code as `200 OK`
 render json: response, status: response[:status_code]
 end
 end
 end
 end

Passing Additional Information to Response

 # app/controllers/api/v1/users_controller.rb
 def index
 users = User.all
 config = {}
 config[:serializer] = UserSerializer
 config[:meta] = { total_count: users.count }
 serializer_responder(users, config)
 end
 # simple way
 serializer_responder(users, { serializer: UserSerializer, meta: { total_count: users.count } })

Response

 {
 "status": "success", 
 "body" : 
 [
 {
 "id": 1,
 "firstname": "Kalidas",
 "lastname": "M",
 "phone_number": "+919876543210",
 "email": "kalidasm610@gmail.com"
 },
 {
 "id": 2,
 "firstname": "Dass",
 "lastname": "Mk",
 "phone_number": "+919876543211",
 "email": ""
 }
 ],
 "status_code": "ok",
 "meta": {
 "total_count": 2
 }
}

API Exceptions

Error Messages for API Exceptions

 en:
 api_response:
 messages:
 internal_server_error: "Internal server error."
 record_not_found: "The resource you are looking for does not exist."
 record_invalid: "Validation Failed"
 record_not_destroyed: "Failed to delete the resource"
 forbidden_resource: "You don't have sufficient privileges to perform this operation"
 unauthorized_access: "You are not authorized to perform this operation"

Raising API Exception inside controller actions

 class CreditsController < ApplicationController
 before_action :authorize_user, only: :update
 def update
 @credit.update(credit_params)
 end
 private
 def authorize_user
 return if user_authorized?
 # Will be handled by rescue_from methods in application controller
 raise ::Api::Exception.new(
 ::Api::Exception.unauthorized_access
 )
 end
 end

 {
 "status": "failure",
 "messages": {
 "errors": ["You are not authorized to perform this operation"]
 },
 "status_code": "unprocessable_entity",
 "meta": {}
 }

 private
 def authorize_user
 return if user_authorized?
 raise ::Api::Exception.new(
 ::Api::Exception.unauthorized_access, "Looks like you are not authorized to update credit score"
 )
 end

 {
 "status": "failure",
 "messages": {
 "errors": ["Looks like you are not authorized to update credit score"]
 },
 "status_code": "unprocessable_entity",
 "meta": {}
 }

Response Status - Failure / Success

Development

Contributing

License