mini_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b21a5cc35f98d6a21450a738d876b0c7fee94d36113e0c3999f15df17c59f643
+  data.tar.gz: d60bf59a2ca1d64d4157fa46e9d770ed6b748e7895aa77bb2410936e09de91a6
+SHA512:
+  metadata.gz: dcb3b028b14506c7c15dd2df893c25af5dabdfd7f47ca8781c32ebaeb7cf2a3b6c5d17be9a2befeeb2c0c7cc996c774230ba1f9fe11b07464f1a50cd7a6e4a9a
+  data.tar.gz: 2af62824d289dd78d9bb9e7a813a319179c56229ed6443e64746e65cf687e796e519a59d00c20c2f9745a3950d455111e0291eb6c7f05e5cd2cd6b635b9de7ab

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2023 Leon Cruz
+
+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.

data/README.md

@@ -0,0 +1,182 @@
+![](https://github.com/leoncruz/api-responder/actions/workflows/tests.yml/badge.svg)
+[![Maintainability](https://api.codeclimate.com/v1/badges/ec2939be693459b7ce4d/maintainability)](https://codeclimate.com/github/leoncruz/api-responder/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/ec2939be693459b7ce4d/test_coverage)](https://codeclimate.com/github/leoncruz/api-responder/test_coverage)
+
+# Mini Api
+A gem to standardize json responses in Rails applications, highly inspired on [Responders](https:github.com/heartcombo/responders)
+
+## Table of Contents
+- [Usage](#usage)
+  - [Respondering json](#respondering-json)
+  - [Success and failure actions](#success-and-failure-actions)
+- [Overriding response](#overriding-response)
+- [Pagination](#pagination)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "mini_api"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Your must install [Kaminari](https://github.com/kaminari/kaminari) to handle pagination
+and [Active Model Serializers](http://github.com/rails-api/active_model_serializers) to handle data serialization
+
+## Usage
+
+After install the gem, include the `MiniApi` module into your `ApplicationController` or other parent controller
+```ruby
+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:
+```ruby
+class UsersController < ApplicationController
+  def show
+    user = User.find(params[:id])
+
+    render_json user
+  end
+end
+```
+
+The generated json will be like:
+```json
+{
+  "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
+```ruby
+class UsersController < ApplicationController
+  def index
+    users = User.all
+
+    render_json users
+  end
+end
+```
+The response will be like:
+```json
+{
+  "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:
+```ruby
+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:
+```ruby
+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:
+```json
+{
+  "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:
+```json
+{
+  "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
+
+## Overriding response
+
+You can override the `status`, `message` and `sucess` keys simply informing values to `render_json`. Example:
+
+```ruby
+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
+
+1. Fork it
+2. Create your feature branch (git checkout -b my-new-feature)
+3. Commit your changes (git commit -am 'Add some feature')
+4. Push to the branch (git push origin my-new-feature)
+5. Create new Pull Request
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+require 'bundler/gem_tasks'

data/lib/mini_api/default_responder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module MiniApi
+  class DefaultResponder
+    def initialize(controller, resource, options = {})
+      @controller = controller
+      @resource = resource
+      @options = options
+    end
+
+    def respond
+      success = @options[:success] != false
+
+      @controller.render(
+        json: {
+          success: success,
+          data: @resource,
+          message: @options[:message] || nil
+        },
+        status: @options[:status] || :ok
+      )
+    end
+  end
+end

data/lib/mini_api/exceptions/kaminari_not_installed.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MiniApi
+  class KaminariNotInstalled < StandardError; end
+end

data/lib/mini_api/locales/en.yml

@@ -0,0 +1,13 @@
+en:
+  mini_api:
+    messages:
+      actions:
+        create:
+          notice: '%{resource_name} was successfully created.'
+          alert: '%{resource_name} could not be created.'
+        update:
+          notice: '%{resource_name} was successfully updated.'
+          alert: '%{resource_name} could not be updated.'
+        destroy:
+          notice: '%{resource_name} was successfully destroyed.'
+          alert: '%{resource_name} could not be destroyed.'

data/lib/mini_api/model_responder.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'mini_api/serialization'
+
+module MiniApi
+  # class to handle json render of ActiveRecord::Base instances and ActiveModel::Model's
+  class ModelResponder
+    include Serialization
+
+    def initialize(controller, resource, options = {})
+      @controller = controller
+      @resource = resource
+      @options = options
+    end
+
+    def respond
+      body = {
+        success: resource_has_errors? == false,
+        message: @options[:message] || default_message
+      }
+
+      body =
+        if resource_has_errors?
+          { errors: @resource.errors.messages }.merge(body)
+        else
+          { data: serialiable_body(@resource) }.merge(body)
+        end
+
+      @controller.render json: body, status: status_code
+    end
+
+    private
+
+    def resource_has_errors?
+      !@resource.errors.empty?
+    end
+
+    def status_code
+      return @options[:status] if @options[:status].present?
+
+      return :unprocessable_entity if resource_has_errors?
+
+      return :created if @resource.previously_new_record?
+
+      return :no_content unless @resource.persisted?
+
+      :ok
+    end
+
+    def default_message
+      kind = resource_has_errors? ? 'alert' : 'notice'
+
+      I18n.t(
+        kind,
+        scope: [:mini_api, :messages, :actions, @controller.action_name],
+        resource_name: @resource.class.model_name.human,
+        default: ''
+      )
+    end
+  end
+end

data/lib/mini_api/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'active_support/i18n'
+
+module MiniApi
+  class Railtie < ::Rails::Railtie
+    # load translations
+    I18n.load_path << File.expand_path('../mini_api/locales/en.yml', __dir__)
+  end
+end

data/lib/mini_api/relation_responder.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'mini_api/exceptions/kaminari_not_installed'
+require 'mini_api/serialization'
+
+module MiniApi
+  class RelationResponder
+    include Serialization
+
+    def initialize(controller, resource, options = {})
+      @controller = controller
+      @resource = resource
+      @options = options
+    end
+
+    def respond
+      meta, collection = extract_meta_and_collection
+
+      @controller.render json: {
+        success: @options[:success] || true,
+        data: collection,
+        meta: meta
+      }, status: @options[:status]
+    end
+
+    private
+
+    def extract_meta_and_collection
+      collection = transform_resource_to_collection
+
+      [
+        {
+          current_page: collection.current_page,
+          next_page: collection.next_page,
+          prev_page: collection.prev_page,
+          total_pages: collection.total_pages,
+          total_records: collection.total_count
+        },
+        serialiable_body(collection)
+      ]
+    end
+
+    def transform_resource_to_collection
+      unless defined?(Kaminari)
+        raise KaminariNotInstalled, 'The Kaminari gem is not installed. Install to perform pagination operations'
+      end
+
+      @resource.page(@controller.page).per(@controller.per_page)
+    end
+  end
+end

data/lib/mini_api/responder.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'mini_api/default_responder'
+require 'mini_api/model_responder'
+require 'mini_api/relation_responder'
+
+module MiniApi
+  class Responder
+    def initialize(controller, resource, options = {})
+      @controller = controller
+      @resource = resource
+      @options = options
+    end
+
+    def respond
+      case @resource
+      when ActiveRecord::Relation
+        relation_responder.respond
+      when ActiveRecord::Base, ActiveModel::Model
+        model_responder.respond
+      else
+        default_responder.respond
+      end
+    end
+
+    def relation_responder
+      RelationResponder.new(@controller, @resource, @options)
+    end
+
+    def model_responder
+      ModelResponder.new(@controller, @resource, @options)
+    end
+
+    def default_responder
+      DefaultResponder.new(@controller, @resource, @options)
+    end
+  end
+end

data/lib/mini_api/serialization.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module MiniApi
+  #
+  # This module is responsible to handler integration with Active Model Serialier gem
+  # call the +get_serializer+ method of controller implemented by gem
+  # to find the serializer of informed object.
+
+  module Serialization
+    def serialiable_body(resource)
+      return resource unless defined?(ActiveModel::Serializer)
+
+      @controller.get_serializer(resource)
+    end
+  end
+end

data/lib/mini_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MiniApi
+  VERSION = '0.1.0'
+end

data/lib/mini_api.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'mini_api/railtie'
+require 'mini_api/responder'
+
+# Entrypoint module
+module MiniApi
+  def render_json(resource, options = {})
+    responder = Responder.new(self, resource, options)
+
+    responder.respond
+  end
+
+  def page
+    params[:page].to_i || 1
+  end
+
+  def per_page
+    if params[:per_page].to_i.in?([10, 25, 50, 100])
+      params[:per_page]
+    else
+      25
+    end
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: mini_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Leon Cruz
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-06-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.5
+description: A collection of resources to create restful apis
+email:
+- leon.cruz.teixeira@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/mini_api.rb
+- lib/mini_api/default_responder.rb
+- lib/mini_api/exceptions/kaminari_not_installed.rb
+- lib/mini_api/locales/en.yml
+- lib/mini_api/model_responder.rb
+- lib/mini_api/railtie.rb
+- lib/mini_api/relation_responder.rb
+- lib/mini_api/responder.rb
+- lib/mini_api/serialization.rb
+- lib/mini_api/version.rb
+homepage:
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key:
+specification_version: 4
+summary: A collection of resources to create restful apis
+test_files: []