api_responser 1.0.0.9 → 1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3f5a73a1b52366c43c394e2d5e24125f81f020a7341ec422701250462ddc6dc
-  data.tar.gz: 8b9d6fc699ce3182c2671f2e39d4d93ba4319fc91e6e1471060fc6cf1c999928
+  metadata.gz: e28a527016ea61d6d5050e1bc049556e1803be3b99d63327e525fc244bc68064
+  data.tar.gz: 1b7399981de0a77cdcc935f828c098d2654a5a9ee72af1acb866563358a30ae2
 SHA512:
-  metadata.gz: 28f1cbb554ebd6d2e799880358affbf333a68074fb5ff39646e650770e226c33123cc98339a4f1b127f904cc725a1690295f0e74132cf702a5e73b1fd32ff700
-  data.tar.gz: 6fb2d8c87e418c1cd3c0d2b03302b3402efe525f1f45c1f290927d761bf719912c3334f62f346922155a4e0b8da266129f92eb99a2dcb85fbf0f2b137f573aaf
+  metadata.gz: 31b9f21ee19f8c88757000df8608f6917ea83e869ac5b26c481d7467ec283f5e7fc0eafdd4291ffe5de35edfeb3784917af29ce150fcf48c081529ea40025f68
+  data.tar.gz: a1ffa33b876ba7047f6c75ac8732f1c13479bef7f1a45480c6499bee89fff85b5ffcd5d36fe2375fc9fdc6e9cb2d44b9709d3eec838c07c61ed517b5ff9eab76

data/lib/api_responser.rb

@@ -1,3 +1,5 @@
+require 'erb'
+require 'json'
 require 'rails'
 
 require_relative 'api_responser/railtie' if defined?(Rails)
@@ -19,11 +21,12 @@ module ApiResponser
     end
   end
 
+  # 204 No Content must not carry a body, so a response with records is sent as 200.
   def record_updated(records = nil)
     if records.nil?
       api_success(code: 204)
     else
-      success_render(code: 204, message: i18n_message(__method__, status:"success"), records: records)
+      success_render(code: 200, message: i18n_message(__method__, status:"success"), records: records)
     end
   end
 
@@ -31,7 +34,7 @@ module ApiResponser
     if records.nil?
       api_success(code: 204)
     else
-      success_render(code: 204, message: i18n_message(__method__, status:"success"), records: records)
+      success_render(code: 200, message: i18n_message(__method__, status:"success"), records: records)
     end
   end
 
@@ -114,7 +117,7 @@ module ApiResponser
 
   def success_render(code: 200, message: "", records: nil, records_count: nil)
     @code = code
-    @message = message
+    @message = json_escape(message)
     @records = records
     @records_count = determine_records_count(records, records_count)
     {json: ERB.new(file_read("success")).result(binding), status: code}
@@ -122,11 +125,18 @@ module ApiResponser
 
   def error_render(code: 500, message: "", debug_message: "", report: false)
     @code = code
-    @message = message
+    @message = json_escape(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
 
+  # The JSON templates interpolate @message inside a quoted string literal, so
+  # any quote or backslash in it would otherwise produce unparseable JSON.
+  # to_json gives us the escaped form; the surrounding quotes come from the template.
+  def json_escape(value)
+    value.to_s.to_json[1..-2]
+  end
+
   def file_read(type = "error")
     if defined?(Rails) && Rails.root
       app_view_path = Rails.root.join('app', 'views', 'api_responser', "#{type}.json.erb")
@@ -140,7 +150,7 @@ module ApiResponser
   end
 
   def i18n_message(method_name, status:"error", message: nil)
-    message = message.full_messages.join(', ') if message.is_a?(ActiveModel::Errors)
+    message = message.full_messages.join(', ') if message.respond_to?(:full_messages)
     message = message.join(', ') if message.is_a?(Array)
     I18n.t("api_responser.#{status}.#{method_name}", message: message)
   end
@@ -150,6 +160,17 @@ module ApiResponser
   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))
+    return records_count if records_count
+    return records.count if collection?(records)
+
+    records.blank? ? 0 : 1
+  end
+
+  # ActiveRecord is not necessarily loaded (e.g. an API app with no database),
+  # so the constant is resolved lazily rather than referenced directly.
+  def collection?(records)
+    return true if records.is_a?(Array)
+
+    defined?(ActiveRecord::Relation) && records.is_a?(ActiveRecord::Relation)
   end
 end

data/readme.md

@@ -13,6 +13,11 @@ A gem to standardize API responses in Rails applications.
 
 All methods return JSON and status.
 
+## Requirements
+
+- Ruby >= 3.0
+- Rails >= 7.0 (tested against 7.1 and 8.1)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -43,8 +48,8 @@ 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
+The *records* argument is required and should be an **Array** or an **ActiveRecord::Relation**. 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 *records*. This is useful for pagination, where the rendered page is smaller than the total count
 ```ruby
 def record_index(records, records_count = nil)
 ```
@@ -54,15 +59,23 @@ The *records* argument should be a **Hash**. It should contain only one model
 def record_show(records)
 ```
 #### Item Create / Item Update / Item Delete
-*No arguments* are required
+The *records* argument is optional.
+
+When called *without arguments*, the response has no body and only a status code is returned
+(**201** for create, **204 No Content** for update and delete).
+
+When *records* are passed, the created/updated/deleted record is rendered in the response body
+(**201** for create, **200** for update and delete). Update and delete use **200** rather than **204**
+in this case, because a 204 No Content response is not allowed to carry a body.
+
 ```ruby
-def record_created
+def record_created(records = nil)
 ```
 ```ruby
-def record_updated
+def record_updated(records = nil)
 ```
 ```ruby
-def record_deleted
+def record_deleted(records = nil)
 ```
 
 
@@ -108,6 +121,11 @@ The *message* argument is required, while the *debug_message* argument is option
 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**). 
 
+The *message* argument accepts a **String**, an **Array** of strings, or a model's
+**errors** object (e.g. `item.errors`), which is joined into a single sentence.
+Messages are escaped before being rendered, so text containing quotes, backslashes
+or newlines is safe to pass through.
+
 ```ruby
 def record_not_created(message, debug_message = "", report:false)
 ```
@@ -145,23 +163,29 @@ Templates should be located in **app/views/api_responser/**
 The default templates are:
 #### success.json.erb
 ``` ruby
-"data":{
+{"data": {
   "status": "success",
   "code": <%= @code %>,
   "message": "<%= @message %>",
   "records": <%= @records.to_json %>,
   "records_count": <%= @records_count %>
-}
+}}
 ```
 ####  error.json.erb
 ``` ruby
-"data":{
+{"data": {
   "status": "error",
   "code": <%= @code %>,
   "message": "<%= @message %>"
-}
+}}
 ```
 
+**Note on `@message` in custom templates:** `@message` arrives already escaped for
+JSON, so quotes, backslashes and newlines in a message are safe. It is escaped as
+*string contents only* — the surrounding quotes come from the template, so keep
+`@message` wrapped in `"` as shown above. Values you add yourself should be passed
+through `to_json` (as `@records` is) so the rendered body stays valid JSON.
+
 ## Customizing Error Handling
 The gem provides a default error handler in **ApiResponserHelper**:
 ``` ruby
@@ -172,7 +196,7 @@ module ApiResponserHelper
 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**
+Helper should be located in **app/helpers/api_responser_helper.rb**
 
 
 ## Localization

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_responser
 version: !ruby/object:Gem::Version
-  version: 1.0.0.9
+  version: '1.1'
 platform: ruby
 authors:
 - Nazim Mehdiyev
@@ -82,14 +82,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 3.7.2
 specification_version: 4
 summary: A gem to standardize API responses in Rails applications
 test_files: []