jsonapi-serializers 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8b8e2b1a0281f387fc8e6e3ee0c24747ada99067
-  data.tar.gz: 2ce4804f76c29485607f6738bee21dd00dac9db0
+  metadata.gz: 0a63fa6a767f6236335d147e099ca81b13e24d72
+  data.tar.gz: e8fe7e954d1b5a14d2903ff0d72923eb24d0abb8
 SHA512:
-  metadata.gz: d7d32a4701376557f93e848ee32c7a77f80ed1214a4de326a0c8dc85530f6211ed75476b060a8716162391928af36cb7ac6e551fbf29f99c40e3d5a305cf87f3
-  data.tar.gz: bcb13f91e195f15b052d055957e904bd4e4704365292bf36e3c9c76d88bcab74903752b9670fde309169e525ff64389a444e205fed80841fc270f9518c9e8aa7
+  metadata.gz: 64417e501b68bb8e686eb362e8ea53c65afff161d5c9f0f881e08d15436c8f4b27fd06491ee5d479d74c99ce7ed5c78e72e001a82a18a019d56cbd7b99ef28e9
+  data.tar.gz: da8f7e8f9c78c18f5d6f6a2ae7b1399116a7876f40c0c71b4d59d36615be5ba88e7b5c978b3f536dbd61e071ea6fd103940044a3b3a3d89d08a66649f113ddf1

data/.travis.yml

@@ -5,7 +5,7 @@ rvm:
   - 1.9.3
   - 2.1.1
   - 2.2.2
-  - ruby-head
+  - 2.3.1
 before_install:
   - gem install bundler
 script: bundle exec rspec

data/README.md

@@ -18,12 +18,13 @@ This library is up-to-date with the finalized v1 JSON API spec.
   * [Custom attributes](#custom-attributes)
   * [More customizations](#more-customizations)
   * [Base URL](#base-url)
-  * [Root jsonapi object](#root-jsonapi-object)
   * [Root metadata](#root-metadata)
   * [Root links](#root-links)
   * [Root errors](#root-errors)
+  * [Root jsonapi object](#root-jsonapi-object)
   * [Explicit serializer discovery](#explicit-serializer-discovery)
   * [Namespace serializers](#namespace-serializers)
+  * [Sparse fieldsets](#sparse-fieldsets)
 * [Relationships](#relationships)
   * [Compound documents and includes](#compound-documents-and-includes)
   * [Relationship path handling](#relationship-path-handling)
@@ -318,14 +319,6 @@ JSONAPI::Serializer.serialize(post, base_url: 'http://example.com')
 
 Note: if you override `self_link` in your serializer and leave out `base_url`, it will not be included.
 
-### Root 'jsonapi' object
-
-You can pass a `jsonapi` argument to specify a [top-level "jsonapi" key](http://jsonapi.org/format/#document-jsonapi-object) containing the version of JSON:API in use:
-
-```ruby
-JSONAPI::Serializer.serialize(post, jsonapi: {version: '1.0'})
-```
-
 ### Root metadata
 
 You can pass a `meta` argument to specify top-level metadata:
@@ -372,6 +365,14 @@ class Api::V1::ReposController < Api::V1::BaseController
 end
 ```
 
+### Root 'jsonapi' object
+
+You can pass a `jsonapi` argument to specify a [top-level "jsonapi" key](http://jsonapi.org/format/#document-jsonapi-object) containing the version of JSON:API in use:
+
+```ruby
+JSONAPI::Serializer.serialize(post, jsonapi: {version: '1.0'})
+```
+
 ### Explicit serializer discovery
 
 By default, jsonapi-serializers assumes that the serializer class for `Namespace::User` is `Namespace::UserSerializer`. You can override this behavior on a per-object basis by implementing the `jsonapi_serializer_class_name` method.
@@ -416,6 +417,35 @@ JSONAPI::Serializer.serialize(post, namespace: Api::V2)
 
 This option overrides the `jsonapi_serializer_class_name` method.
 
+### Sparse fieldsets
+
+The JSON:API spec allows to return only [specific fields](http://jsonapi.org/format/#fetching-sparse-fieldsets) from attributes and relationships.
+
+For example, if you wanted to return only the `title` field and `author` relationship link for `posts`:
+
+```ruby
+fields =
+JSONAPI::Serializer.serialize(post, fields: {posts: [:title]})
+```
+
+Sparse fieldsets also affect relationship links. In this case, only the `author` relationship link would be included:
+
+``` ruby
+JSONAPI::Serializer.serialize(post, fields: {posts: [:title, :author]})
+```
+
+Sparse fieldsets operate on a per-type basis, so they affect all resources in the response including in compound documents. For example, this will affect both the `posts` type in the primary data and the `users` type in the compound data:
+
+``` ruby
+JSONAPI::Serializer.serialize(
+  post,
+  fields: {posts: ['title', 'author'], users: ['name']},
+  include: 'author',
+)
+```
+
+Sparse fieldsets support comma-separated strings (`fields: {posts: 'title,author'}`, arrays of strings (`fields: {posts: ['title', 'author']}`), single symbols (`fields: {posts: :title}`), and arrays of symbols (`fields: {posts: [:title, :author]}`).
+
 ## Relationships
 
 You can easily specify relationships with the `has_one` and `has_many` directives.
@@ -783,7 +813,6 @@ See [Releases](https://github.com/fotinakis/jsonapi-serializers/releases).
 
 ## Unfinished business
 
-* Support for the `fields` spec is planned, would love a PR contribution for this.
 * Support for pagination/sorting is unlikely to be supported because it would likely involve coupling to ActiveRecord, but please open an issue if you have ideas of how to support this generically.
 
 ## Contributing

data/lib/jsonapi-serializers/serializer.rb

@@ -33,6 +33,7 @@ module JSONAPI
         @base_url = options[:base_url]
 
         # Internal serializer options, not exposed through attr_accessor. No touchie.
+        @_fields = options[:fields] || {}
         @_include_linkages = options[:include_linkages] || []
       end
 
@@ -165,7 +166,7 @@ module JSONAPI
         return {} if self.class.attributes_map.nil?
         attributes = {}
         self.class.attributes_map.each do |attribute_name, attr_data|
-          next if !should_include_attr?(attr_data[:options][:if], attr_data[:options][:unless])
+          next if !should_include_attr?(attribute_name, attr_data)
           value = evaluate_attr_or_block(attribute_name, attr_data[:attr_or_block])
           attributes[format_name(attribute_name)] = value
         end
@@ -176,7 +177,7 @@ module JSONAPI
         return {} if self.class.to_one_associations.nil?
         data = {}
         self.class.to_one_associations.each do |attribute_name, attr_data|
-          next if !should_include_attr?(attr_data[:options][:if], attr_data[:options][:unless])
+          next if !should_include_attr?(attribute_name, attr_data)
           data[attribute_name] = attr_data
         end
         data
@@ -190,7 +191,7 @@ module JSONAPI
         return {} if self.class.to_many_associations.nil?
         data = {}
         self.class.to_many_associations.each do |attribute_name, attr_data|
-          next if !should_include_attr?(attr_data[:options][:if], attr_data[:options][:unless])
+          next if !should_include_attr?(attribute_name, attr_data)
           data[attribute_name] = attr_data
         end
         data
@@ -200,11 +201,14 @@ module JSONAPI
         evaluate_attr_or_block(attribute_name, attr_data[:attr_or_block])
       end
 
-      def should_include_attr?(if_method_name, unless_method_name)
+      def should_include_attr?(attribute_name, attr_data)
         # Allow "if: :show_title?" and "unless: :hide_title?" attribute options.
+        if_method_name = attr_data[:options][:if]
+        unless_method_name = attr_data[:options][:unless]
         show_attr = true
         show_attr &&= send(if_method_name) if if_method_name
         show_attr &&= !send(unless_method_name) if unless_method_name
+        show_attr &&= @_fields[type.to_s].include?(attribute_name) if @_fields[type.to_s]
         show_attr
       end
       protected :should_include_attr?
@@ -252,6 +256,7 @@ module JSONAPI
       options[:jsonapi] = options.delete('jsonapi') || options[:jsonapi]
       options[:meta] = options.delete('meta') || options[:meta]
       options[:links] = options.delete('links') || options[:links]
+      options[:fields] = options.delete('fields') || options[:fields] || {}
 
       # Deprecated: use serialize_errors method instead
       options[:errors] = options.delete('errors') || options[:errors]
@@ -260,12 +265,27 @@ module JSONAPI
       includes = options[:include]
       includes = (includes.is_a?(String) ? includes.split(',') : includes).uniq if includes
 
+      # Transforms input so that the comma-separated fields are separate symbols in array
+      # and keys are stringified
+      # Example:
+      # {posts: 'title,author,long_comments'} => {'posts' => [:title, :author, :long_comments]}
+      # {posts: ['title', 'author', 'long_comments'} => {'posts' => [:title, :author, :long_comments]}
+      #
+      fields = {}
+      # Normalize fields to accept a comma-separated string or an array of strings.
+      options[:fields].map do |type, whitelisted_fields|
+        whitelisted_fields = [whitelisted_fields] if whitelisted_fields.is_a?(Symbol)
+        whitelisted_fields = whitelisted_fields.split(',') if whitelisted_fields.is_a?(String)
+        fields[type.to_s] = whitelisted_fields.map(&:to_sym)
+      end
+
       # An internal-only structure that is passed through serializers as they are created.
       passthrough_options = {
         context: options[:context],
         serializer: options[:serializer],
         namespace: options[:namespace],
         include: includes,
+        fields: fields,
         base_url: options[:base_url]
       }
 
@@ -328,6 +348,7 @@ module JSONAPI
           included_passthrough_options = {}
           included_passthrough_options[:base_url] = passthrough_options[:base_url]
           included_passthrough_options[:context] = passthrough_options[:context]
+          included_passthrough_options[:fields] = passthrough_options[:fields]
           included_passthrough_options[:serializer] = find_serializer_class(data[:object], options)
           included_passthrough_options[:namespace] = passthrough_options[:namespace]
           included_passthrough_options[:include_linkages] = data[:include_linkages]

data/lib/jsonapi-serializers/version.rb

@@ -1,5 +1,5 @@
 module JSONAPI
   module Serializer
-    VERSION = '0.15.0'
+    VERSION = '0.16.0'
   end
 end

data/spec/serializer_spec.rb

@@ -441,12 +441,12 @@ describe JSONAPI::Serializer do
     it 'can include a top level errors node' do
       errors = [
         {
-          'source' => { 'pointer' => '/data/attributes/first-name' },
+          'source' => {'pointer' => '/data/attributes/first-name'},
           'title' => 'Invalid Attribute',
           'detail' => 'First name must contain at least three characters.'
         },
         {
-          'source' => { 'pointer' => '/data/attributes/first-name' },
+          'source' => {'pointer' => '/data/attributes/first-name'},
           'title' => 'Invalid Attribute',
           'detail' => 'First name must contain an emoji.'
         }
@@ -477,15 +477,15 @@ describe JSONAPI::Serializer do
       user = DummyUser.new
       jsonapi_errors = [
         {
-          'source' => { 'pointer' => '/data/attributes/email' },
+          'source' => {'pointer' => '/data/attributes/email'},
           'detail' => 'Email is invalid'
         },
         {
-          'source' => { 'pointer' => '/data/attributes/email' },
+          'source' => {'pointer' => '/data/attributes/email'},
           'detail' => "Email can't be blank"
         },
         {
-          'source' => { 'pointer' => '/data/attributes/first-name' },
+          'source' => {'pointer' => '/data/attributes/first-name'},
           'detail' => "First name can't be blank"
         }
       ]
@@ -854,6 +854,113 @@ describe JSONAPI::Serializer do
         })
       end
     end
+
+    context 'sparse fieldsets' do
+      it 'allows to limit fields(attributes) for serialized resource' do
+        first_user = create(:user)
+        second_user = create(:user)
+        first_comment = create(:long_comment, user: first_user)
+        second_comment = create(:long_comment, user: second_user)
+        long_comments = [first_comment, second_comment]
+        post = create(:post, :with_author, long_comments: long_comments)
+
+        serialized_data = JSONAPI::Serializer.serialize(post, fields: {posts: :title})
+        expect(serialized_data).to eq ({
+          'data' => {
+            'type' => 'posts',
+            'id' => post.id.to_s,
+            'attributes' => {
+              'title' => post.title,
+            },
+            'links' => {
+              'self' => '/posts/1'
+            }
+          }
+        })
+      end
+      it 'allows to limit fields(relationships) for serialized resource' do
+        first_user = create(:user)
+        second_user = create(:user)
+        first_comment = create(:long_comment, user: first_user)
+        second_comment = create(:long_comment, user: second_user)
+        long_comments = [first_comment, second_comment]
+        post = create(:post, :with_author, long_comments: long_comments)
+
+        fields = {posts: 'title,author,long_comments'}
+        serialized_data = JSONAPI::Serializer.serialize(post, fields: fields)
+        expect(serialized_data['data']['relationships']).to eq ({
+          'author' => {
+            'links' => {
+              'self' => '/posts/1/relationships/author',
+              'related' => '/posts/1/author'
+            }
+          },
+          'long-comments' => {
+            'links' => {
+              'self' => '/posts/1/relationships/long-comments',
+              'related' => '/posts/1/long-comments'
+            }
+          }
+        })
+      end
+      it "allows also to pass specific fields as array instead of comma-separates values" do
+        first_user = create(:user)
+        second_user = create(:user)
+        first_comment = create(:long_comment, user: first_user)
+        second_comment = create(:long_comment, user: second_user)
+        long_comments = [first_comment, second_comment]
+        post = create(:post, :with_author, long_comments: long_comments)
+
+        serialized_data = JSONAPI::Serializer.serialize(post, fields: {posts: ['title', 'author']})
+        expect(serialized_data['data']['attributes']).to eq ({
+          'title' => post.title
+        })
+        expect(serialized_data['data']['relationships']).to eq ({
+          'author' => {
+            'links' => {
+              'self' => '/posts/1/relationships/author',
+              'related' => '/posts/1/author'
+            }
+          }
+        })
+      end
+      it 'allows to limit fields(attributes and relationships) for included resources' do
+        first_user = create(:user)
+        second_user = create(:user)
+        first_comment = create(:long_comment, user: first_user)
+        second_comment = create(:long_comment, user: second_user)
+        long_comments = [first_comment, second_comment]
+        post = create(:post, :with_author, long_comments: long_comments)
+
+        expected_primary_data = serialize_primary(post, {
+          serializer: MyApp::PostSerializer,
+          include_linkages: ['author'],
+          fields: {'posts' => [:title, :author] }
+        })
+
+        fields = {posts: 'title,author', users: ''}
+        serialized_data = JSONAPI::Serializer.serialize(post, fields: fields, include: 'author')
+        expect(serialized_data).to eq ({
+          'data' => expected_primary_data,
+          'included' => [
+            serialize_primary(
+              post.author,
+              serializer: MyAppOtherNamespace::UserSerializer,
+              fields: {'users' => []},
+            )
+          ]
+        })
+
+        fields = {posts: 'title,author'}
+        serialized_data = JSONAPI::Serializer.serialize(post, fields: fields, include: 'author')
+        expect(serialized_data).to eq ({
+          'data' => expected_primary_data,
+          'included' => [
+            serialize_primary(post.author, serializer: MyAppOtherNamespace::UserSerializer)
+          ]
+        })
+      end
+    end
   end
 
   describe 'serialize (class method)' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi-serializers
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Mike Fotinakis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-01 00:00:00.000000000 Z
+date: 2016-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport