api_responser 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 81300d06901f90334a8a2f47154ca0773836b4b0a640923059b62d1e86e48eac
+  data.tar.gz: d189a7133d7679a0e788d75d21eeb7bf041166dfd0677326cdc4227c0be97cac
+SHA512:
+  metadata.gz: 332bc07fd3079cb4c7bb8743609a146dac88e225bf5c71ecb5f94456b3b34794cb66bc0a7c82468fa2b4b8f46e3a9fd58313a5dc8f733a8fa88d139f63d1af7d
+  data.tar.gz: da4e7d004677798c5ac679c31af48c5fa413ade46f12bdc69cceefa0b3abb56a804b305c44a951673a257bafa69b9a1e8cb8276c54a8f49d738b48df58668672

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nazim T.M.
+
+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/app/helpers/api_responser_helper.rb

@@ -0,0 +1,5 @@
+module ApiResponserHelper
+  def self.error_handling(code:nil,debug_message:nil,message:nil)
+    Logger.new(STDOUT).fatal("Error with code #{code}. Debug message: #{debug_message}. Message: #{message}")
+  end
+end

data/app/views/api_responser/error.json.erb

@@ -0,0 +1 @@
+{"status":"error","code":<%= @code %>,"message":"<%= @message %>"}

data/app/views/api_responser/success.json.erb

@@ -0,0 +1 @@
+{"status":"success","code":<%= @code %>,"message":"<%= @message %>","records":<%= @records.to_json %>,"records_count":<%= @records_count %>}

data/config/locales/en.yml

@@ -0,0 +1,27 @@
+en:
+  api_responser:
+    error:
+      access_denied: "Access denied"
+      page_not_found: "Page not found"
+      record_not_found: "Record not found"
+      record_not_created: "Record not created: %{message}"
+      record_not_updated: "Record not saved: %{message}"
+      record_not_deleted: "Record not deleted: %{message}"
+      bad_request: "Bad request"
+      unauthorized: "Unauthorized"
+      forbidden: "Forbidden"
+      method_not_allowed: "Method not allowed"
+      not_acceptable: "Not acceptable"
+      conflict: "Conflict"
+      gone: "Gone"
+      unsupported_media_type: "Unsupported media type"
+      too_many_requests: "Too many requests"
+      internal_server_error: "Internal Server Error"
+      not_implemented: "Not implemented"
+      service_unavailable: "Service unavailable"
+    success:
+      record_index: "List"
+      record_created: "Created"
+      record_updated: "Updated"
+      record_deleted: "Deleted"
+      record_show: "Show"

data/lib/api_responser/railtie.rb

@@ -0,0 +1,19 @@
+require 'rails'
+
+module ApiResponser
+  class Railtie < Rails::Railtie
+    I18n.load_path += Dir[File.join(File.dirname(__FILE__), '../../config/locales/*.yml')]
+
+    initializer 'api_responser.add_view_paths' do |app|
+      # Adding the gem's views directory to the view paths
+      app.config.paths['app/views'].unshift File.expand_path('../../../app/views', __FILE__)
+    end
+
+    initializer 'api_responser.include_helpers' do
+      ActiveSupport.on_load(:action_controller_base) do
+        require File.expand_path('../../../app/helpers/api_responser_helper', __FILE__)
+        include ApiResponserHelper
+      end
+    end
+  end
+end

data/lib/api_responser.rb

@@ -0,0 +1,143 @@
+require 'rails'
+
+require_relative 'api_responser/railtie' if defined?(Rails)
+module ApiResponser
+  # Success responses
+  def record_index(records, records_count = nil)
+    success_render(code: 200, message: i18n_message(__method__, status:"success"), records: records, records_count: records_count)
+  end
+
+  def record_show(records)
+    success_render(code: 200, message: i18n_message(__method__, status:"success"), records: records)
+  end
+
+  def record_created
+    api_success(code: 201)
+  end
+
+  def record_updated
+    api_success(code: 204)
+  end
+
+  def record_deleted
+    api_success(code: 204)
+  end
+
+  # Error responses
+  def page_not_found
+    error_render(code: 404, message: i18n_message(__method__, status:"error"))
+  end
+
+  def record_not_found
+    error_render(code: 404, message: i18n_message(__method__, status:"error"))
+  end
+
+  def record_not_created(message, debug_message = "", report:false)
+    error_render(code: 422, message: i18n_message(__method__, status:"error", message: message), debug_message: debug_message, report:report)
+  end
+
+  def record_not_updated(message, debug_message = "", report:false)
+    error_render(code: 422, message: i18n_message(__method__, status:"error", message: message), debug_message: debug_message, report:report)
+  end
+
+  def record_not_deleted(message, debug_message = "", report:false)
+    error_render(code: 500, message: i18n_message(__method__, status:"error", message: message), debug_message: debug_message, report:report)
+  end
+
+  def bad_request(debug_message = "", report:false)
+    error_render(code: 400, message: i18n_message(__method__, status:"error"), debug_message: debug_message, report:report)
+  end
+
+  def unauthorized(debug_message = "", report:false)
+    error_render(code: 401, message: i18n_message(__method__, status:"error"), debug_message: debug_message, report:report)
+  end
+
+  def forbidden(debug_message = "", report:false)
+    error_render(code: 403, message: i18n_message(__method__, status:"error"), debug_message: debug_message, report:report)
+  end
+
+  def internal_server_error(debug_message = "", report:false)
+    error_render(code: 500, message: i18n_message(__method__, status:"error"), debug_message: debug_message, report:report)
+  end
+
+  def method_not_allowed
+    error_render(code: 405, message: i18n_message(__method__, status:"error"))
+  end
+
+  def not_acceptable
+    error_render(code: 406, message: i18n_message(__method__, status:"error"))
+  end
+
+  def conflict
+    error_render(code: 409, message: i18n_message(__method__, status:"error"))
+  end
+
+  def gone
+    error_render(code: 410, message: i18n_message(__method__, status:"error"))
+  end
+
+  def unsupported_media_type
+    error_render(code: 415, message: i18n_message(__method__, status:"error"))
+  end
+
+  def too_many_requests
+    error_render(code: 429, message: i18n_message(__method__, status:"error"))
+  end
+
+
+  def not_implemented
+    error_render(code: 501, message: i18n_message(__method__, status:"error"))
+  end
+
+  def service_unavailable
+    error_render(code: 503, message: i18n_message(__method__, status:"error"))
+  end
+
+  private
+
+  def api_success(code: 200)
+    {status: code}
+  end
+
+
+  def success_render(code: 200, message: "", records: nil, records_count: nil)
+    @code = code
+    @message = message
+    @records = records
+    @records_count = determine_records_count(records, records_count)
+    {json:ERB.new(file_read("success")).result(binding), status: code}
+  end
+
+  def error_render(code: 500, message: "", debug_message: "", report: false)
+    @code = code
+    @message = message
+    error_handling(code: code, message: message, debug_message: debug_message) if report == true
+    {json: ERB.new(file_read("error")).result(binding), status: code}
+  end
+
+  def file_read(type = "error")
+    if defined?(Rails) && Rails.root
+      app_view_path = Rails.root.join('app', 'views', 'api_responser', "#{type}.json.erb")
+    else
+      app_view_path = File.join(Dir.pwd, 'app', 'views', 'api_responser', "#{type}.json.erb")
+    end
+
+    gem_view_path = File.expand_path("../../app/views/api_responser/#{type}.json.erb", __FILE__)
+
+    File.exist?(app_view_path) ? File.read(app_view_path) : File.read(gem_view_path)
+  end
+
+  def i18n_message(method_name, status:"error", message: nil)
+    message = message.full_messages.join(', ') if message.is_a?(ActiveModel::Errors)
+    message = message.join(', ') if message.is_a?(Array)
+    I18n.t("api_responser.#{status}.#{method_name}", message: message)
+  end
+
+  def error_handling(code:, message:, debug_message:)
+    ApiResponserHelper.error_handling(:code => code, :message => message, :debug_message => debug_message)
+  end
+
+  def determine_records_count(records, records_count)
+    records_count || ((records.is_a?(ActiveRecord::Relation) || (records.is_a?(Array))) ? records.count : (records.nil? || records.blank? ? 0 : 1))
+  end
+end

data/readme.md

@@ -0,0 +1,264 @@
+# ApiResponser
+
+#### Overview
+The **api_responser** gem is designed to streamline the process of handling API responses in your Rails application. It provides a simple and consistent way to render success and error messages, ensuring your API responses are always well-structured and easy to manage.
+
+#### Key Features
+- Standardized Responses: Simplify the way you handle API responses by using a set of predefined methods for success and error messages.
+- Localization Support: Leverage the power of I18n to dynamically translate response messages, making your API more versatile and user-friendly for a global audience.
+- Ease of Use: With intuitive method names and straightforward implementation, integrating api_responser into your Rails application is quick and hassle-free.
+- Maintenance: Reduce the effort required to maintain consistent response structures across your application, making your codebase cleaner and more maintainable.
+
+A gem to standardize API responses in Rails applications.
+
+All methods return JSON and status.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'api_responser'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install api_responser
+```
+
+## Usage
+### Initialization
+```ruby
+class ApplicationController < ActionController::Base
+  include ApiResponser
+end
+```
+
+## Success Response list
+#### List of Items
+The *records* argument is required and should be an **Array**. The *records_count* argument is an **Integer** and is optional.\
+If *records_count* is not provided, the count will be calculated from the size of the *records* array
+```ruby
+def record_index(records, records_count = nil)
+```
+#### Show Item
+The *records* argument should be a **Hash**. It should contain only one model 
+```ruby
+def record_show(records)
+```
+#### Item Create / Item Update / Item Delete
+*No arguments* are required
+```ruby
+def record_created
+```
+```ruby
+def record_updated
+```
+```ruby
+def record_deleted
+```
+
+
+
+
+## Error Response list
+#### Page Not Found / Record Not Found / Method Not Allowed / Not Acceptable / Conflict / Gone / Unsupported Media Type / Too Many Requests / Not Implemented / Service Unavailable
+*No arguments* are required
+
+```ruby
+def page_not_found
+```
+```ruby
+def record_not_found
+```
+```ruby
+def method_not_allowed
+```
+```ruby
+def not_acceptable
+```
+```ruby
+def conflict
+```
+```ruby
+def gone
+```
+```ruby
+def unsupported_media_type
+```
+```ruby
+def too_many_requests
+```
+```ruby
+def not_implemented
+```
+```ruby
+def service_unavailable
+```
+
+#### Record Not Created / Record Not Updated / Record Not Deleted
+The *message* argument is required, while the *debug_message* argument is optional.\
+The *report* argument is optional and is useful if you would like to handle *debug_message*.\
+The *message* argument is used to output a message in the JSON response, whereas *debug_message* is useful for providing the real reason for the error (if *report* is **true**). 
+
+```ruby
+def record_not_created(message, debug_message = "", report:false)
+```
+```ruby
+def record_not_updated(message, debug_message = "", report:false)
+```
+```ruby
+def record_not_deleted(message, debug_message = "", report:false)
+```
+
+#### Bad request / Unauthorized / Forbidden / Internal Server Error
+The *debug_message* argument is optional.\
+The *report* argument is optional and is useful if you would like to handle *debug_message*.\
+The *debug_message* is useful for providing the real reason for the error (if *report* is **true**). 
+
+```ruby
+def bad_request(debug_message = "", report:false)
+```
+```ruby
+def unauthorized(debug_message = "", report:false)
+```
+```ruby
+def forbidden(debug_message = "", report:false)
+```
+```ruby
+def internal_server_error(debug_message = "", report:false)
+```
+
+
+## Customizing Response Templates
+You can modify the success and error response templates.
+Templates should be located in **app/views/api_responser/**
+
+The default templates are:
+#### success.json.erb
+``` ruby
+{
+  "status": "success",
+  "code": <%= @code %>,
+  "message": "<%= @message %>",
+  "records": <%= @records.to_json %>,
+  "records_count": <%= @records_count %>
+}
+```
+####  error.json.erb
+``` ruby
+{
+  "status": "error",
+  "code": <%= @code %>,
+  "message": "<%= @message %>"
+}
+```
+
+## Customizing Error Handling
+The gem provides a default error handler in **ApiResponserHelper**:
+``` ruby
+module ApiResponserHelper
+  def error_handling(code: nil, debug_message: nil, message: nil)
+    Logger.new(STDOUT).fatal("Error with code #{code}. Debug message: #{debug_message}. Message: #{message}")
+  end
+end
+```
+You can customize this method to handle errors in a way that suits your application's requirements. For example, you might want to log errors to a file or send notifications to an external service.
+Helper should be located in **app/helpers/app_responser_helper.rb**
+
+
+## Localization
+**ApiResponser** uses I18n for localization.
+
+Default localization located in config/locale/en.yml
+
+
+
+## Example
+```ruby
+class ApplicationController < ActionController::Base
+  include ApiResponser
+  before_action do
+    set_model_variable("ModelName")
+  end  
+  before_action :find, only: [:show, :update, :destroy]
+
+  def index
+    itemList = @modelName.all
+    render record_index(itemList)
+
+    # could be using with counter for pagination
+    itemList = @modelName.where(:name => "value")
+    render record_index(itemList.limit(5), itemList.count)
+  end
+
+  def show
+    render record_show(@obj)
+  end
+
+  def create
+    item = @modelName.new(model_params)
+    if item.save
+      render record_created
+    else
+      render record_not_created(item.errors, report:true)
+    end
+  end
+
+  def update
+    if @obj.update(model_params)
+      render record_updated
+    else
+      render record_not_updated(@obj.errors, report:true)
+    end
+  end
+
+  def destroy
+    if @obj.destroy
+      render record_deleted
+    else
+      render record_not_deleted(@obj.errors, report:true)
+    end
+  end
+
+
+  private
+  def find
+    @obj = @modelName.find_by(:id => params[:id])
+    unless @obj
+      render record_not_found
+    end
+  end
+
+  def model_params
+    params.require(:model).permit(:name)
+  end  
+
+  def set_model_variable modelName
+    @modelName = modelName.constantize
+  end
+end
+
+```
+
+[![Buy me a coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=&slug=nmehdiyev&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://www.buymeacoffee.com/nmehdiyev)
+
+
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first
+to discuss what you would like to change.
+
+Please make sure to update tests as appropriate.
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/)

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: api_responser
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Nazim Mehdiyev
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-07-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: "\n    The api_responser gem provides a standardized way to handle API
+  responses in a Rails application. \n    It includes methods for rendering success
+  and error responses, making it easier to manage and maintain \n    consistent response
+  structures across your application. The gem leverages I18n for localization, allowing
+  \n    dynamic translation of response messages based on method names.\n  "
+email:
+- nazim@mehdiyev.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- app/helpers/api_responser_helper.rb
+- app/views/api_responser/error.json.erb
+- app/views/api_responser/success.json.erb
+- config/locales/en.yml
+- lib/api_responser.rb
+- lib/api_responser/railtie.rb
+- readme.md
+homepage: https://github.com/nmehdiyev/ApiResponser
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/nmehdiyev/ApiResponser
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: A gem to standardize API responses in Rails applications
+test_files: []