jsonapi-serializers 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ccad99bd078e37fa43bab5ffd42d9fae85414c33
-  data.tar.gz: c4d9d97a4550a955c7d9f95c9b59e70cc60896f2
+  metadata.gz: b670315a342425c1d55f313aa4bc0830e1b0a69e
+  data.tar.gz: d2be33728c559adbee37316b70087369d5513389
 SHA512:
-  metadata.gz: 6eb60b10f45d7892c4828b125b5a0efc139f41e1c0f737a48bcb4ffedea7162e78e5189d05e916ade934a197dec7f400b1a844c6f34bf5c1647896cee2098657
-  data.tar.gz: f3a8ec61f5c47a1ee73760865bf7dfc6903c77d12b7aa587753ee4c4626556f3e81697455f60a9118a14002ed4978a21129e7138b86fc118d0b9e2af58aabaed
+  metadata.gz: 70dc34dd00b999e5805012212e80daa22510a2665b77366e657c6e809a7812ca143af7db8789fb88fe9a590f5c343bd25a164fee1903da79f74df0d52fb186d6
+  data.tar.gz: e254988e99b57b4108c7cecf35e065751b164722dc751fb14bdf46818f8922a3162c7780b3479625450a21d41872005411c6fbe2a6bfa56c6778a41a5f926ae0

data/README.md

@@ -24,6 +24,7 @@ This library is up-to-date with the finalized v1 JSON API spec.
 * [Relationships](#relationships)
   * [Compound documents and includes](#compound-documents-and-includes)
   * [Relationship path handling](#relationship-path-handling)
+  * [Control links and data in relationships](#control-links-and-data-in-relationships)
 * [Rails example](#rails-example)
 * [Sinatra example](#sinatra-example)
 * [Unfinished business](#unfinished-business)
@@ -333,7 +334,7 @@ JSONAPI::Serializer.serialize_errors(user.errors)
 
 A more complete usage example (assumes ActiveModel):
 
-```
+```ruby
 class Api::V1::ReposController < Api::V1::BaseController
   def create
     post = Post.create(post_params)
@@ -509,6 +510,52 @@ Notice a few things:
 
 The `include` param also accepts a string of [relationship paths](http://jsonapi.org/format/#fetching-includes), ie. `include: 'author,comments,comments.user'` so you can pass an `?include` query param directly through to the serialize method. Be aware that letting users pass arbitrary relationship paths might introduce security issues depending on your authorization setup, where a user could `include` a relationship they might not be authorized to see directly. Be aware of what you allow API users to include.
 
+### Control `links` and `data` in relationships
+
+The JSON API spec allows relationships objects to contain `links`, `data`, or both.
+
+By default, `links` are included in each relationship. You can remove links for a specific relationship by passing `include_links: false` to `has_one` or `has_many`. For example:
+
+```ruby
+has_many :comments, include_links: false  # Default is include_links: true.
+```
+
+Notice that `links` are now excluded for the `comments` relationship:
+
+```json
+   "relationships": {
+     "author": {
+       "links": {
+         "self": "/posts/1/relationships/author",
+         "related": "/posts/1/author"
+       }
+     },
+     "comments": {}
+   }
+```
+
+By default, `data` is excluded in each relationship. You can enable data for a specific relationship by passing `include_data: true` to `has_one` or `has_many`. For example:
+
+```ruby
+has_one :author, include_data: true  # Default is include_data: false.
+```
+
+Notice that linkage data is now included for the `author` relationship:
+
+```json
+   "relationships": {
+     "author": {
+       "links": {
+         "self": "/posts/1/relationships/author",
+         "related": "/posts/1/author"
+       },
+       "data": {
+         "type": "users",
+         "id": "1"
+       }
+     }
+```
+
 ## Rails example
 
 ```ruby

data/lib/jsonapi-serializers/attributes.rb

@@ -52,6 +52,8 @@ module JSONAPI
       private :add_attribute
 
       def add_to_one_association(name, options = {}, &block)
+        options[:include_links] = options.fetch(:include_links, true)
+        options[:include_data] = options.fetch(:include_data, false)
         @to_one_associations ||= {}
         @to_one_associations[name] = {
           attr_or_block: block_given? ? block : name,
@@ -61,6 +63,8 @@ module JSONAPI
       private :add_to_one_association
 
       def add_to_many_association(name, options = {}, &block)
+        options[:include_links] = options.fetch(:include_links, true)
+        options[:include_data] = options.fetch(:include_data, false)
         @to_many_associations ||= {}
         @to_many_associations[name] = {
           attr_or_block: block_given? ? block : name,

data/lib/jsonapi-serializers/serializer.rb

@@ -97,13 +97,16 @@ module JSONAPI
           formatted_attribute_name = format_name(attribute_name)
 
           data[formatted_attribute_name] = {}
-          links_self = relationship_self_link(attribute_name)
-          links_related = relationship_related_link(attribute_name)
-          data[formatted_attribute_name]['links'] = {} if links_self || links_related
-          data[formatted_attribute_name]['links']['self'] = links_self if links_self
-          data[formatted_attribute_name]['links']['related'] = links_related if links_related
 
-          if @_include_linkages.include?(formatted_attribute_name)
+          if attr_data[:options][:include_links]
+            links_self = relationship_self_link(attribute_name)
+            links_related = relationship_related_link(attribute_name)
+            data[formatted_attribute_name]['links'] = {} if links_self || links_related
+            data[formatted_attribute_name]['links']['self'] = links_self if links_self
+            data[formatted_attribute_name]['links']['related'] = links_related if links_related
+          end
+
+          if @_include_linkages.include?(formatted_attribute_name) || attr_data[:options][:include_data]
             object = has_one_relationship(attribute_name, attr_data)
             if object.nil?
               # Spec: Resource linkage MUST be represented as one of the following:
@@ -125,17 +128,20 @@ module JSONAPI
           formatted_attribute_name = format_name(attribute_name)
 
           data[formatted_attribute_name] = {}
-          links_self = relationship_self_link(attribute_name)
-          links_related = relationship_related_link(attribute_name)
-          data[formatted_attribute_name]['links'] = {} if links_self || links_related
-          data[formatted_attribute_name]['links']['self'] = links_self if links_self
-          data[formatted_attribute_name]['links']['related'] = links_related if links_related
+
+          if attr_data[:options][:include_links]
+            links_self = relationship_self_link(attribute_name)
+            links_related = relationship_related_link(attribute_name)
+            data[formatted_attribute_name]['links'] = {} if links_self || links_related
+            data[formatted_attribute_name]['links']['self'] = links_self if links_self
+            data[formatted_attribute_name]['links']['related'] = links_related if links_related
+          end
 
           # Spec: Resource linkage MUST be represented as one of the following:
           # - an empty array ([]) for empty to-many relationships.
           # - an array of linkage objects for non-empty to-many relationships.
           # http://jsonapi.org/format/#document-structure-resource-relationships
-          if @_include_linkages.include?(formatted_attribute_name)
+          if @_include_linkages.include?(formatted_attribute_name) || attr_data[:options][:include_data]
             data[formatted_attribute_name]['data'] = []
             objects = has_many_relationship(attribute_name, attr_data) || []
             objects.each do |obj|

data/lib/jsonapi-serializers/version.rb

@@ -1,5 +1,5 @@
 module JSONAPI
   module Serializer
-    VERSION = '0.10.0'
+    VERSION = '0.11.0'
   end
 end

data/spec/serializer_spec.rb

@@ -352,6 +352,72 @@ describe JSONAPI::Serializer do
         },
       })
     end
+
+    it 'allows to exclude linkages for relationships' do
+      long_comments = create_list(:long_comment, 2)
+      post = create(:post, :with_author, long_comments: long_comments)
+      primary_data = serialize_primary(post, { serializer: MyApp::PostSerializerWithoutIncludeLinks })
+      expect(primary_data).to eq({
+        'id' => '1',
+        'type' => 'posts',
+        'attributes' => {
+          'title' => 'Title for Post 1'
+        },
+        'links' => {
+          'self' => '/posts/1',
+        },
+        'relationships' => {
+          'author' => {
+          },
+          'long-comments' => {
+          },
+        }
+      })
+    end
+
+    it 'allows to include data for relationships' do
+      long_comments = create_list(:long_comment, 2)
+      post = create(:post, :with_author, long_comments: long_comments)
+      primary_data = serialize_primary(post, { serializer: MyApp::PostSerializerWithIncludeData })
+      expect(primary_data).to eq({
+        'id' => '1',
+        'type' => 'posts',
+        'attributes' => {
+          'title' => 'Title for Post 1'
+        },
+        'links' => {
+          'self' => '/posts/1',
+        },
+        'relationships' => {
+          'author' => {
+            'links' => {
+              'self' => '/posts/1/relationships/author',
+              'related' => '/posts/1/author'
+            },
+            'data' => {
+              'type' => 'users',
+              'id' => '1'
+            }
+          },
+          'long-comments' => {
+            'links' => {
+              'self' => '/posts/1/relationships/long-comments',
+              'related' => '/posts/1/long-comments'
+            },
+            'data' => [
+              {
+                'type' => 'long-comments',
+                'id' => '1'
+              },
+              {
+                'type' => 'long-comments',
+                'id' => '2'
+              }
+            ]
+          },
+        }
+      })
+    end
   end
 
   # The members data and errors MUST NOT coexist in the same document.

data/spec/support/serializers.rb

@@ -94,7 +94,6 @@ module MyApp
 
   class PostSerializerWithMetadata
     include JSONAPI::Serializer
-    include JSONAPI::Serializer
 
     attribute :title
     attribute :long_content do
@@ -113,6 +112,32 @@ module MyApp
     end
   end
 
+  class PostSerializerWithoutIncludeLinks
+    include JSONAPI::Serializer
+
+    attribute :title
+
+    has_one :author, include_links: false
+    has_many :long_comments, include_links: false
+
+    def type
+      :posts
+    end
+  end
+
+  class PostSerializerWithIncludeData
+    include JSONAPI::Serializer
+
+    attribute :title
+
+    has_one :author, include_data: true
+    has_many :long_comments, include_data: true
+
+    def type
+      :posts
+    end
+  end
+
   class PostSerializerWithContext < PostSerializer
     attribute :body, if: :show_body?, unless: :hide_body?
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi-serializers
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Mike Fotinakis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-16 00:00:00.000000000 Z
+date: 2016-04-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport