Merge remote-tracking branch 'remotes/origin/master' into rails5

Author: lgebhardt

README.md

@@ -1,8 +1,8 @@
-# JSONAPI::Resources [![Build Status](https://secure.travis-ci.org/cerebris/jsonapi-resources.svg?branch=master)](http://travis-ci.org/cerebris/jsonapi-resources) [![Code Climate](https://codeclimate.com/github/cerebris/jsonapi-resources/badges/gpa.svg)](https://codeclimate.com/github/cerebris/jsonapi-resources)
+# JSONAPI::Resources [![Gem Version](https://badge.fury.io/rb/jsonapi-resources.svg)](https://badge.fury.io/rb/jsonapi-resources) [![Build Status](https://secure.travis-ci.org/cerebris/jsonapi-resources.svg?branch=master)](http://travis-ci.org/cerebris/jsonapi-resources) [![Code Climate](https://codeclimate.com/github/cerebris/jsonapi-resources/badges/gpa.svg)](https://codeclimate.com/github/cerebris/jsonapi-resources)
 
 [![Join the chat at https://gitter.im/cerebris/jsonapi-resources](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/cerebris/jsonapi-resources?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-**_NOTE: This Rails 5 branch is a work in progress. It contains some monkey patches (in `test_helper.rb`) to allow existing tests to pass with Rails 5.0.0.beta1.1_. Things may break with future changes to Rails.**
+**_NOTE: There is a Rails 5 branch that is a work in progress. In addition to some changes for Rails 5 support it contains some monkey patches (in `test_helper.rb`) to allow existing tests to pass with Rails 5.0.0.beta1.1_. Things may break with future changes to Rails. If you are using RAILS 5 it is recommended that you use the rails 5 branch.**
 
 `JSONAPI::Resources`, or "JR", provides a framework for developing a server that complies with the
 [JSON API](http://jsonapi.org/) specification.
@@ -29,6 +29,7 @@ backed by ActiveRecord models or by custom objects.
     * [Pagination] (#pagination)
     * [Included relationships (side-loading resources)] (#included-relationships-side-loading-resources)
     * [Resource meta] (#resource-meta)
+    * [Custom Links] (#resource-meta)
     * [Callbacks] (#callbacks)
   * [Controllers] (#controllers)
     * [Namespaces] (#namespaces)
@@ -787,12 +788,22 @@ The `paged` `paginator` returns results based on pages of a fixed size. Valid `p
 If `number` is omitted the first page is returned. If `size` is omitted the `default_page_size` from the configuration
 settings is used.
 
+```
+GET /articles?page%5Bnumber%5D=10&page%5Bsize%5D=10 HTTP/1.1
+Accept: application/vnd.api+json
+```
+
 ###### Offset Paginator
 
 The `offset` `paginator` returns results based on an offset from the beginning of the resultset. Valid `page` parameters
 are `offset` and `limit`. If `offset` is omitted a value of 0 will be used. If `limit` is omitted the `default_page_size`
 from the configuration settings is used.
 
+```
+GET /articles?page%5Blimit%5D=10&page%5Boffset%5D=10 HTTP/1.1
+Accept: application/vnd.api+json
+```
+
 ###### Custom Paginators
 
 Custom `paginators` can be used. These should derive from `Paginator`. The `apply` method takes a `relation` and
@@ -931,6 +942,72 @@ method is called with an `options` has. The `options` hash will contain the foll
  * `:serializer` -> the serializer instance
  * `:serialization_options` -> the contents of the `serialization_options` method on the controller.
 
+#### Custom Links
+
+Custom links can be included for each resource by overriding the `custom_links` method. If a non empty hash is returned from `custom_links`, it will be merged with the default links hash containing the resource's `self` link. The `custom_links` method is called with the same `options` hash used by for [resource meta information](#resource-meta). The `options` hash contains the following:
+
+ * `:serializer` -> the serializer instance
+ * `:serialization_options` -> the contents of the `serialization_options` method on the controller.
+
+For example:
+
+```ruby
+class CityCouncilMeeting < JSONAPI::Resource
+  attribute :title, :location, :approved
+
+  def custom_links(options)
+    { minutes: options[:serialzer].link_builder.self_link(self) + "/minutes" }
+  end
+end
+```
+
+This will create a custom link with the key `minutes`, which will be merged with the default `self` link, like so:
+
+```json
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "cityCouncilMeetings",
+      "links": {
+        "self": "http://city.gov/api/city-council-meetings/1",
+        "minutes": "http://city.gov/api/city-council-meetings/1/minutes"
+      },
+      "attributes": {...}
+    },
+    //...
+  ]
+}
+```
+
+Of course, the `custom_links` method can include logic to include links only when relevant:
+
+````ruby
+class CityCouncilMeeting < JSONAPI::Resource
+  attribute :title, :location, :approved
+
+  delegate :approved?, to: :model
+
+  def custom_links(options)
+    extra_links = {}
+    if approved?
+      extra_links[:minutes] = options[:serialzer].link_builder.self_link(self) + "/minutes"
+    end
+    extra_links
+  end
+end
+```
+
+It's also possibly to suppress the default `self` link by returning a hash with `{self: nil}`:
+
+````ruby
+class Selfless < JSONAPI::Resource
+  def custom_links(options)
+    {self: nil}
+  end
+end
+```
+
 #### Callbacks
 
 `ActiveSupport::Callbacks` is used to provide callback functionality, so the behavior is very similar to what you may be
@@ -1020,6 +1097,14 @@ JSONAPI.configure do |config|
 end
 ```
 
+To use a specific `OperationsProcessor` in a `ResourceController`, override the `create_operations_processor` method:
+
+```ruby
+def create_operations_processor
+  CountingActiveRecordOperationsProcessor.new
+end
+```
+
 The callback code will be called after each find. It will use the same options as the find operation, without the
 pagination, to collect the record count. This is stored in the `operation_meta`, which will be returned in the top level
 meta element.

lib/jsonapi/paginator.rb

@@ -58,7 +58,7 @@ def links_page_params(options = {})
 
       previous_offset = 0 if previous_offset < 0
 
-      links_page_params['previous'] = {
+      links_page_params['prev'] = {
         'offset' => previous_offset,
         'limit' => @limit
       }

lib/jsonapi/resource.rb

@@ -152,6 +152,15 @@ def meta(_options)
       {}
     end
 
+    # Override this to return custom links
+    # must return a hash, which will be merged with the default { self: 'self-url' } links hash
+    # links keys will be not be formatted with the key formatter for the serializer by default.
+    # They can however use the serializer's format_key and format_value methods if desired
+    # the _options hash will contain the serializer and the serialization_options
+    def custom_links(_options)
+      {}
+    end
+
     private
 
     def save
@@ -531,7 +540,11 @@ def apply_filter(records, filter, value, options = {})
         strategy = _allowed_filters.fetch(filter.to_sym, Hash.new)[:apply]
 
         if strategy
-          strategy.call(records, value, options)
+          if strategy.is_a?(Symbol) || strategy.is_a?(String)
+            send(strategy, records, value, options)
+          else
+            strategy.call(records, value, options)
+          end
         else
           records.where(filter => value)
         end
@@ -630,7 +643,12 @@ def verify_filter(filter, raw, context = nil)
         strategy = _allowed_filters.fetch(filter, Hash.new)[:verify]
 
         if strategy
-          [filter, strategy.call(filter_values, context)]
+          if strategy.is_a?(Symbol) || strategy.is_a?(String)
+            values = send(strategy, filter_values, context)
+          else
+            values = strategy.call(filter_values, context)
+          end
+          [filter, values]
         else
           if is_filter_relationship?(filter)
             verify_relationship_filter(filter, filter_values, context)

lib/jsonapi/resource_serializer.rb

@@ -114,19 +114,18 @@ def object_hash(source, include_directives)
 
       obj_hash['type'] = format_key(source.class._type.to_s)
 
-      links = relationship_links(source)
+      links = links_hash(source)
       obj_hash['links'] = links unless links.empty?
 
-      attributes = attribute_hash(source)
+      attributes = attributes_hash(source)
       obj_hash['attributes'] = attributes unless attributes.empty?
 
-      relationships = relationship_data(source, include_directives)
+      relationships = relationships_hash(source, include_directives)
       obj_hash['relationships'] = relationships unless relationships.nil? || relationships.empty?
 
-      meta = source.meta(custom_generation_options)
-      if meta.is_a?(Hash) && !meta.empty?
-        obj_hash['meta'] = meta
-      end
+      meta = meta_hash(source)
+      obj_hash['meta'] = meta unless meta.empty?
+
       obj_hash
     end
 
@@ -139,7 +138,7 @@ def requested_fields(klass)
       end
     end
 
-    def attribute_hash(source)
+    def attributes_hash(source)
       requested = requested_fields(source.class)
       fields = source.fetchable_fields & source.class._attributes.keys.to_a
       fields = requested & fields unless requested.nil?
@@ -159,7 +158,23 @@ def custom_generation_options
       }
     end
 
-    def relationship_data(source, include_directives)
+    def meta_hash(source)
+      meta = source.meta(custom_generation_options)
+      (meta.is_a?(Hash) && meta) || {}
+    end
+
+    def links_hash(source)
+      {
+        self: link_builder.self_link(source)
+      }.merge(custom_links_hash(source)).compact
+    end
+
+    def custom_links_hash(source)
+      custom_links = source.custom_links(custom_generation_options)
+      (custom_links.is_a?(Hash) && custom_links) || {}
+    end
+
+    def relationships_hash(source, include_directives)
       relationships = source.class._relationships
       requested = requested_fields(source.class)
       fields = relationships.keys
@@ -197,7 +212,7 @@ def relationship_data(source, include_directives)
                 if include_linkage && !relationships_only
                   add_included_object(id, object_hash(resource, ia))
                 elsif include_linked_children || relationships_only
-                  relationship_data(resource, ia)
+                  relationships_hash(resource, ia)
                 end
               end
             elsif relationship.is_a?(JSONAPI::Relationship::ToMany)
@@ -208,7 +223,7 @@ def relationship_data(source, include_directives)
                 if include_linkage && !relationships_only
                   add_included_object(id, object_hash(resource, ia))
                 elsif include_linked_children || relationships_only
-                  relationship_data(resource, ia)
+                  relationships_hash(resource, ia)
                 end
               end
             end
@@ -217,13 +232,6 @@ def relationship_data(source, include_directives)
       end
     end
 
-    def relationship_links(source)
-      links = {}
-      links[:self] = link_builder.self_link(source)
-
-      links
-    end
-
     def already_serialized?(type, id)
       type = format_key(type)
       @included_objects.key?(type) && @included_objects[type].key?(id)
@@ -299,7 +307,7 @@ def foreign_key_types_and_values(source, relationship)
       if relationship.is_a?(JSONAPI::Relationship::ToMany)
         if relationship.polymorphic?
           source._model.public_send(relationship.name).pluck(:type, :id).map do |type, id|
-            [type.pluralize, IdValueFormatter.format(id)]
+            [type.underscore.pluralize, IdValueFormatter.format(id)]
           end
         else
           source.public_send(relationship.foreign_key).map do |value|