Merge pull request #2 from vladfaust/development

Version 1.0.0

Author: vladfaust

README.md

@@ -8,7 +8,7 @@ Official JSON API [implementations page](http://jsonapi.org/implementations/#ser
 
 I'd like to notice that there already is one gem called [jbuilder-jsonapi](https://github.com/csexton/jbuilder-jsonapi) by [csexton](https://github.com/csexton), but it adds a links helper only. It's not enough for me! :facepunch:
 
-As a result, I've created a **very** lightweight & flexible solution - all you need is Jbuilder and this gem. Then you should delete everything within your `*.json.jbuilder` files and replace it with below recommendations (just one line! :flushed:). After you are free to customize parsed attributes and relationships with two tiny methods.
+As a result, I've created a **very** lightweight & flexible solution - all you need is Jbuilder and this gem. Then you should delete everything within your `*.json.jbuilder` files and replace it with below recommendations (just one line! :flushed:). After you are free to customize parsed attributes and relationships with three tiny methods.
 
 ## Installation
 
@@ -31,10 +31,13 @@ Or install it yourself as:
 Replace any content within any `*.json.jbuilder` file with the code below:
 ```ruby
 # Common example
-json.api_format! @resources, @errors, meta: @meta, access_level: @user_access_level
+json.api_format! @resources, @errors, meta, options
 
-# Articles w/o meta or access levels example
-json.api_format! @articles, @errors
+# Items example
+json.api_format! @items, @errors, nil, access_level: :admin
+
+# A simple items example
+json.api_format! @items
 ```
 You can also render formatted JSON straight from controller actions:
 ```ruby
@@ -43,24 +46,24 @@ respond_to do |f|
  f.html { render nothing: true, status: :bad_request }
 end
 ```
-Each resource instance, as well as the included one, will be invoked with `json_api_attrs` & `json_api_relations` methods. These methods **MAY** be implemented within each model. `api_format!` method will try to get an object's permitted (**you are free do define authentication logic yourself!**) attributes and relations via those two methods.
+Each resource instance, as well as the included one, will be invoked with `json_api_attrs (options)`, `json_api_relations (options)` & `json_api_meta (options)` methods. These methods **MAY** be implemented within each model. `api_format!` method will try to get an object's permitted attributes (**remember, you are free do define authentication logic yourself!**) and relations and meta information via those three methods.
 
 Here is an example of implementation:
 ```ruby
-# Item model
+# Inside Item model
 
-def json_api_attrs (access_level = nil)
+def json_api_attrs (options = {})
  attrs = []
- attrs += %w(name description price buyoutable item_type category) if %i(user admin).include?access_level
- attrs += %w(real_price in_stock) if access_level == :admin
+ attrs += %w(name description price buyoutable item_type category) if %i(user admin).include?options[:access_level]
+ attrs += %w(real_price in_stock) if options[:access_level] == :admin
  attrs
 end
 
-def json_api_relations (access_level = nil)
+def json_api_relations (options = {})
  %w(category orders)
 end
 ```
-**Note** that the gem will call methods pulled with `json_api_relations and _attrs`. As for the above example, methods like `:name`, `:description`, `:orders` will be invoked for an Item instance. And yes, relations are fetched properly if an object responds to `orders`.
+**Note** that the gem will call methods pulled via `json_api_relations and _attrs`. As for the above example, methods like `:name`, `:description`, `:real_price`, `:orders` will be invoked for an Item instance. And yes, relations are fetched properly and recursively if the object responds to `orders`.
 
 ## Development
 
@@ -75,5 +78,17 @@ Bug reports and pull requests are welcome on GitHub at [https://github.com/vladf
 ## ToDo
 
 - [ ] Maybe add `Content-Type: application/vnd.api+json`. This spec is ignored right now :smirk:
-- [ ] Add links tests
+- [ ] Add links tests and improve them. Links now work only within views (where `@context` is present).
 - [ ] Somehow implement `[fields]` parameter
+
+## Versions
+
+#### 0.0.1 -> 1.0.0
+
+**Breaking:**
+- [x] Now any value can be forwarded to resources' methods via last `options` argument.
+- [x] Added third argument `meta`, which is used to show meta information in the context of request
+
+**Not breaking:**
+- [x] Added support for `json_api_meta (options)` method.
+- [x] Any internal error is now properly handled.

lib/jbuilder/json_api.rb

@@ -5,92 +5,99 @@ module JsonAPI
  # Returns a valid-formatted JSON which follows JSON-API specifications:
  # http://jsonapi.org/
  #
- # Arguments:
- #  :resources: - list of resources to render (may be even one or nil)
- #  :errors: - array of errors in below format:
+ # ==== Arguments
+ # * +resources+ - list of resources to render (may be even one or nil);
+ # * +errors+ - array of hashes in the below format:
  # [{ status: 422, detail: 'This error occurs because...' }, {...}]
+ # * +meta+ - a hash representing any meta (additional) information.
  #
- # Options:
- # :access_level: - access level, e.g. nil, :user, :admin
- # :meta: - a hash representing meta (additional) information
+ # ==== Options
+ # Any information can be passed as +options+ argument; resources' class methods
+ # +json_api_attrs+, +json_api_relations+ and +json_api_meta+
+ # will be invoked with this argument.
  #
- def api_format! (resources = nil, errors = nil, options = {})
- options.merge access_level: nil
- options.merge meta: nil
-
- # Firstly, print meta
- # http://jsonapi.org/format/#document-meta
- #
- if options[:meta] && !options[:meta].empty?
- meta options[:meta]
- end
+ def api_format! (resources = nil, errors = nil, meta = nil, options = {})
+ begin
+ # Firstly, print meta
+ # http://jsonapi.org/format/#document-meta
+ #
+ if meta && !meta.empty?
+ meta meta
+ end
+
+ # Secondly, take care of errors. If there are any,
+ # no 'data' section should be represented.
+ # http://jsonapi.org/format/#document-top-level
+ #
+ # Read more at
+ # http://jsonapi.org/format/#errors
+ #
+ if errors && !errors.empty?
+ ignore_nil! true
+ errors errors do |error|
+ id error[:id]
+ status error[:status]
+ detail error[:detail]
+ code error[:code]
+ title error[:title]
+
+ if error[:source]
+ source do
+ pointer error[:source][:pointer]
+ paramater error[:source][:parameter]
+ end
+ end
 
- # Secondly, take care of errors. If there are any,
- # no 'data' section should be represented.
- # http://jsonapi.org/format/#document-top-level
- #
- # Read more at
- # http://jsonapi.org/format/#errors
- #
- if errors && !errors.empty?
- ignore_nil! (@ignore_nil.nil? ? true : @ignore_nil)
- errors errors do |error|
- id error[:id]
- status error[:status]
- detail error[:detail]
- code error[:code]
- title error[:title]
-
- source do
- pointer error[:pointer]
- paramater error[:parameter]
+ if error[:links]
+ links do
+ about error[:links][:about]
+ end
+ end
  end
+ return self
+ end
+
+ resources = [*resources]
 
+ # http://jsonapi.org/format/#document-links
+ #
+ if @context
  links do
- about error[:about]
+ set! 'self', @context.request.path
  end
  end
- return self
- end
-
- resources = ::Kernel::Array resources
 
- # http://jsonapi.org/format/#document-links
- #
- links do
- begin
- set! 'self', @context.request.path
- rescue
- # No @context given, cannot find path
+ data do
+ resources.blank? ? array! : _api_resource_objects(resources, options)
  end
- end
 
- data do
- resources.blank? ? array! : _api_resource_objects(resources, options[:access_level])
- end
+ included = []
+ resources.each do |resource|
+ next unless resource.respond_to?'json_api_relations'
+ resource.json_api_relations(options).each do |relationship|
+ included += [*(resource.send(relationship))]
+ end
+ end
+ included.uniq!
 
- included = []
- resources.each do |resource|
- next unless resource.respond_to?'json_api_relations'
- resource.json_api_relations(options[:access_level]).each do |relationship|
- included += ::Kernel::Array(resource.send(relationship))
+ included do
+ _api_resource_objects(included, options, resources) unless included.blank?
  end
- end
- included.uniq!
 
- included do
- _api_resource_objects(included, options[:access_level], resources) unless included.blank?
+ self
+ rescue Exception => e
+ @attributes = {}
+ message = Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.3.0') ? e.original_message : e.message
+ return api_format! nil, [{ status: 500, title: e.class.to_s, detail: message }]
  end
-
- self
  end
 
  private
 
  # Formats a resources array properly
  # http://jsonapi.org/format/#document-resource-objects
  #
- def _api_resource_objects (resources, access_level, parent_resources = nil)
+ def _api_resource_objects (resources, options, parent_resources = nil)
  resources.each do |resource|
  child! do
  type resource.class.name.demodulize.to_s.downcase
@@ -100,7 +107,7 @@ def _api_resource_objects (resources, access_level, parent_resources = nil)
  #
  if resource.respond_to?'json_api_attrs'
  attributes do
- resource.json_api_attrs(access_level).each do |attribute|
+ resource.json_api_attrs(options).each do |attribute|
  set! attribute, resource.send(attribute)
  end
  end
@@ -109,21 +116,19 @@ def _api_resource_objects (resources, access_level, parent_resources = nil)
  # http://jsonapi.org/format/#document-resource-object-relationships
  #
  if resource.respond_to?'json_api_relations'
- unless resource.json_api_relations(access_level).blank?
+ unless resource.json_api_relations(options).blank?
  relationships do
- resource.json_api_relations(access_level).each do |relationship|
+ resource.json_api_relations(options).each do |relationship|
  set! relationship do
- links do
- begin
+ if @context
+ links do
  related @context.send("#{ relationship.pluralize }_path")
- rescue
- # No @context given, cannot find path
+ # TODO add a link to the relationship itself
  end
- # TODO add a link to the relationship itself
  end
 
  data do
- ::Kernel::Array(resource.send(relationship)).each do |relationship_instance|
+ [*(resource.send(relationship))].each do |relationship_instance|
  # Relationships shouldn't ever link to the parent resource
  #
  next if !parent_resources.nil? && parent_resources.include?(relationship_instance)
@@ -139,11 +144,16 @@ def _api_resource_objects (resources, access_level, parent_resources = nil)
  end
  end
 
- links do
- begin
+ if resource.respond_to?'json_api_meta'
+ # We don't want to see 'meta': null
+ ignore_nil! true
+ meta resource.json_api_meta(options)
+ ignore_nil! @ignore_nil
+ end
+
+ if @context
+ links do
  set! 'self', @context.send("#{ resource.class.name.demodulize.to_s.downcase }_path", resource)
- rescue
- # No @context given, cannot find path
  end
  end
  end

lib/jbuilder/json_api/version.rb

@@ -1,3 +1,3 @@
 module JsonAPI
- VERSION = '0.0.1'
+ VERSION = '1.0.0'
 end

spec/jbuilder/examples/errors.json

@@ -7,26 +7,15 @@
  "code": 112,
  "title": "Not found",
  "source": {
- "pointer": null,
- "paramater": null
+ "pointer": "http://posts_path"
  },
  "links": {
- "about": null
+ "about": "https://en.wikipedia.org/wiki/HTTP_404"
  }
  },
  {
  "id": 2,
- "status": null,
- "detail": null,
- "code": null,
- "title": "Another error",
- "source": {
- "pointer": null,
- "paramater": null
- },
- "links": {
- "about": null
- }
+ "title": "Another error"
  }
  ]
 }

spec/jbuilder/examples/errors_meta.json

@@ -15,26 +15,15 @@
  "code": 112,
  "title": "Not found",
  "source": {
- "pointer": null,
- "paramater": null
+ "pointer": "http://posts_path"
  },
  "links": {
- "about": null
+ "about": "https://en.wikipedia.org/wiki/HTTP_404"
  }
  },
  {
  "id": 2,
- "status": null,
- "detail": null,
- "code": null,
- "title": "Another error",
- "source": {
- "pointer": null,
- "paramater": null
- },
- "links": {
- "about": null
- }
+ "title": "Another error"
  }
  ]
 }

spec/jbuilder/examples/internal_errors.json

@@ -0,0 +1,9 @@
+{
+ "errors": [
+ {
+ "status": 500,
+ "detail": "undefined method `id' for 42:Fixnum",
+ "title": "NoMethodError"
+ }
+ ]
+}

spec/jbuilder/examples/resources_admin.json

@@ -37,6 +37,9 @@
  }
  ]
  }
+ },
+ "meta": {
+ "blah": "Just another meta info for post #1"
  }
  },
  {
@@ -76,6 +79,9 @@
  }
  ]
  }
+ },
+ "meta": {
+ "blah": "Just another meta info for post #2"
  }
  }
  ],