active_model_serializers 0.10.0 → 0.10.5

data/docs/howto/add_relationship_links.md

@@ -0,0 +1,140 @@
+[Back to Guides](../README.md)
+
+# How to add relationship links
+
+ActiveModelSerializers offers you many ways to add links in your JSON, depending on your needs.
+The most common use case for links is supporting nested resources.
+
+The following examples are without included relationship data (`include` param is empty),
+specifically the following Rails controller was used for these examples:
+
+```ruby
+class Api::V1::UsersController < ApplicationController
+  def show
+    render jsonapi: User.find(params[:id]),
+      serializer: Api::V1::UserSerializer,
+      include: []
+  end
+end
+```
+
+Bear in mind though that ActiveModelSerializers are [framework-agnostic](outside_controller_use.md), Rails is just a common example here.
+
+### Links as an attribute of a resource
+**This is applicable to JSON and Attributes adapters**
+
+You can define an attribute in the resource, named `links`.
+
+```ruby
+class Api::V1::UserSerializer < ActiveModel::Serializer
+  include Rails.application.routes.url_helpers
+
+  attributes :id, :name
+
+  attribute :links do
+    id = object.id
+    {
+      self: api_v1_user_path(id),
+      microposts: api_v1_microposts_path(user_id: id)
+    }
+  end
+end
+```
+
+Using the `JSON` adapter, this will result in:
+
+```json
+{
+  "user": {
+    "id": "1",
+    "name": "John",
+    "links": {
+      "self": "/api/v1/users/1",
+      "microposts": "/api/v1/microposts?user_id=1"
+    }
+  }
+}
+```
+
+
+### Links as a property of the resource definiton
+**This is only applicable to JSONAPI adapter**
+
+You can use the `link` class method to define the links you need in the resource's primary data.
+
+```ruby
+class Api::V1::UserSerializer < ActiveModel::Serializer
+  attributes :id, :name
+
+  link(:self) { api_v1_user_path(object.id) }
+  link(:microposts) { api_v1_microposts_path(user_id: object.id) }
+end
+```
+
+Using the `JSONAPI` adapter, this will result in:
+
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "users",
+    "attributes": {
+      "name": "Example User"
+    },
+    "links": {
+      "self": "/api/v1/users/1",
+      "microposts": "/api/v1/microposts?user_id=1"
+    }
+  }
+}
+```
+
+### Links that follow the JSONAPI spec
+**This is only applicable to JSONAPI adapter**
+
+If you have a JSONAPI-strict client that you are working with (like `ember-data`)
+you need to construct the links inside the relationships. Also the link to fetch the
+relationship data must be under the `related` attribute, whereas to manipulate the
+relationship (in case of many-to-many relationship) must be under the `self` attribute.
+
+You can find more info in the [spec](http://jsonapi.org/format/#document-resource-object-relationships).
+
+Here is how you can do this:
+
+```ruby
+class Api::V1::UserSerializer < ActiveModel::Serializer
+  attributes :id, :name
+
+  has_many :microposts, serializer: Api::V1::MicropostSerializer do
+    link(:related) { api_v1_microposts_path(user_id: object.id) }
+
+    microposts = object.microposts
+    # The following code is needed to avoid n+1 queries.
+    # Core devs are working to remove this necessity.
+    # See: https://github.com/rails-api/active_model_serializers/issues/1325
+    microposts.loaded? ? microposts : microposts.none
+  end
+end
+```
+
+This will result in:
+
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "users",
+    "attributes": {
+      "name": "Example User"
+    },
+    "relationships": {
+      "microposts": {
+        "data": [],
+        "links": {
+          "related": "/api/v1/microposts?user_id=1"
+        }
+      }
+    }
+  }
+}
+```

data/docs/howto/add_root_key.md

@@ -1,3 +1,5 @@
+[Back to Guides](../README.md)
+
 # How to add root key
 
 Add the root key to your API is quite simple with ActiveModelSerializers. The **Adapter** is what determines the format of your JSON response. The default adapter is the ```Attributes``` which doesn't have the root key, so your response is something similar to:
@@ -49,3 +51,5 @@ or if it returns a collection:
   ]
 }
 ```
+
+[There are several ways to specify root](../general/serializers.md#root) when using the JSON adapter.

data/docs/howto/grape_integration.md

@@ -0,0 +1,42 @@
+[Back to Guides](../README.md)
+
+The ActiveModelSerializers grape formatter relies on the existence of `env['grape.request']` which is implemeted by `Grape::Middleware::Globals`. You can meet his dependency by calling it before mounting the endpoints.
+
+In the simpliest way:
+
+```
+class API < Grape::API
+  # @note Make sure this is above you're first +mount+
+  use Grape::Middleware::Globals
+end
+```
+
+or more like what is shown in current Grape tutorials:
+
+```
+module MyApi
+  class ApiBase < Grape::API
+    use Grape::Middleware::Globals
+
+    require 'grape/active_model_serializers'
+    include Grape::ActiveModelSerializers
+
+    mount MyApi::V1::ApiBase
+  end
+end
+```
+
+You could meet this dependency with your own middleware. The invocation might look like:
+
+```
+module MyApi
+  class ApiBase < Grape::API
+    use My::Middleware::Thingamabob
+
+    require 'grape/active_model_serializers'
+    include Grape::ActiveModelSerializers
+
+    mount MyApi::V1::ApiBase
+  end
+end
+```

data/docs/howto/outside_controller_use.md

@@ -10,8 +10,8 @@ In ActiveModelSerializers versions 0.10 or later, serializing resources outside
 # Create our resource
 post = Post.create(title: "Sample post", body: "I love Active Model Serializers!")
 
-# Optional options parameters
-options = {}
+# Optional options parameters for both the serializer and instance
+options = {serializer: PostDetailedSerializer, username: 'sample user'}
 
 # Create a serializable resource instance
 serializable_resource = ActiveModelSerializers::SerializableResource.new(post, options)
@@ -19,10 +19,12 @@ serializable_resource = ActiveModelSerializers::SerializableResource.new(post, o
 # Convert your resource into json
 model_json = serializable_resource.as_json
 ```
+The object that is passed to `ActiveModelSerializers::SerializableResource.new` can be a single resource or a collection.
+The additional options are the same options that are passed [through controllers](../general/rendering.md#explicit-serializer).
 
 ### Looking up the Serializer for a Resource
 
-If you want to retrieve a serializer for a specific resource, you can do the following:
+If you want to retrieve the serializer class for a specific resource, you can do the following:
 
 ```ruby
 # Create our resource
@@ -41,7 +43,13 @@ You could also retrieve the serializer via:
 ActiveModelSerializers::SerializableResource.new(post, options).serializer
 ```
 
-Both approaches will return an instance, if any, of the resource's serializer.
+Both approaches will return the serializer class that will be used for the resource.
+
+Additionally, you could retrieve the serializer instance for the resource via:
+
+```ruby
+ActiveModelSerializers::SerializableResource.new(post, options).serializer_instance
+```
 
 ## Serializing before controller render
 

data/docs/howto/passing_arbitrary_options.md

@@ -11,7 +11,7 @@ For example, we could pass in a field, such as `user_id` into our serializer.
 ```ruby
 # posts_controller.rb
 class PostsController < ApplicationController
-  def dashboard  
+  def dashboard
     render json: @post, user_id: 12
   end
 end
@@ -20,7 +20,7 @@ end
 class PostSerializer < ActiveModel::Serializer
   attributes :id, :title, :body
 
-  def comments_by_me  
+  def comments_by_me
     Comments.where(user_id: instance_options[:user_id], post_id: object.id)
   end
 end

data/docs/howto/serialize_poro.md

@@ -2,13 +2,16 @@
 
 # How to serialize a Plain-Old Ruby Object (PORO)
 
-When you are first getting started with ActiveModelSerializers, it may seem only `ActiveRecord::Base` objects can be serializable, but pretty much any object can be serializable with ActiveModelSerializers.  Here is an example of a PORO that is serializable:
+When you are first getting started with ActiveModelSerializers, it may seem only `ActiveRecord::Base` objects can be serializable,
+but pretty much any object can be serializable with ActiveModelSerializers.
+Here is an example of a PORO that is serializable in most situations:
+
 ```ruby
 # my_model.rb
 class MyModel
   alias :read_attribute_for_serialization :send
   attr_accessor :id, :name, :level
-  
+
   def initialize(attributes)
     @id = attributes[:id]
     @name = attributes[:name]
@@ -21,12 +24,50 @@ class MyModel
 end
 ```
 
-Fortunately, ActiveModelSerializers provides a [`ActiveModelSerializers::Model`](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/model.rb) which you can use in production code that will make your PORO a lot cleaner.  The above code now becomes:
+The [ActiveModel::Serializer::Lint::Tests](../../lib/active_model/serializer/lint.rb)
+define and validate which methods ActiveModelSerializers expects to be implemented.
+
+An implementation of the complete spec is included either for use or as reference:
+[`ActiveModelSerializers::Model`](../../lib/active_model_serializers/model.rb).
+You can use in production code that will make your PORO a lot cleaner.
+
+The above code now becomes:
+
 ```ruby
 # my_model.rb
 class MyModel < ActiveModelSerializers::Model
-  attr_accessor :id, :name, :level
+  attributes :id, :name, :level
+end
+```
+
+The default serializer would be `MyModelSerializer`.
+
+*IMPORTANT*: There is a surprising behavior (bug) in the current implementation of ActiveModelSerializers::Model that
+prevents an accessor from modifying attributes on the instance.  The fix for this bug
+is a breaking change, so we have made an opt-in configuration.
+
+New applications should set:
+
+```ruby
+ActiveModelSerializers::Model.derive_attributes_from_names_and_fix_accessors
+```
+
+Existing applications can use the fix *and* avoid breaking changes
+by making a superclass for new models. For example:
+
+```ruby
+class SerializablePoro < ActiveModelSerializers::Model
+  derive_attributes_from_names_and_fix_accessors
 end
 ```
 
-The default serializer would be `MyModelSerializer`.
+So that `MyModel` above would inherit from `SerializablePoro`.
+
+`derive_attributes_from_names_and_fix_accessors` prepends the `DeriveAttributesFromNamesAndFixAccessors`
+module and does the following:
+
+- `id` will *always* be in the attributes. (This is until we separate out the caching requirement for POROs.)
+- Overwrites the `attributes` method to that it only returns declared attributes.
+ `attributes` will now be a frozen hash with indifferent access.
+
+For more information, see [README: What does a 'serializable resource' look like?](../../README.md#what-does-a-serializable-resource-look-like).

data/docs/howto/test.md

@@ -1,3 +1,5 @@
+[Back to Guides](../README.md)
+
 # How to test
 
 ## Controller Serializer Usage

data/docs/howto/upgrade_from_0_8_to_0_10.md

@@ -0,0 +1,265 @@
+[Back to Guides](../README.md)
+
+# How to migrate from `0.8` to `0.10` safely
+
+## Disclaimer
+### Proceed at your own risk
+This document attempts to outline steps to upgrade your app based on the collective experience of
+developers who have done this already. It may not cover all edge cases and situations that may cause issues,
+so please proceed with a certain level of caution.
+
+## Overview
+This document outlines the steps needed to migrate from `0.8` to `0.10`. The method described
+below has been created via the collective knowledge of contributions of those who have done
+the migration successfully. The method has been tested specifically for migrating from `0.8.3`
+to `0.10.2`.
+
+The high level approach is to upgrade to `0.10` and change all serializers to use
+a backwards-compatible `ActiveModel::V08::Serializer`or `ActiveModel::V08::CollectionSerializer`
+and a `ActiveModelSerializers::Adapter::V08Adapter`. After a few more manual changes, you should have the same
+functionality as you had with `AMS 0.8`. Then, you can continue to develop in your app by creating
+new serializers that don't use these backwards compatible versions and slowly migrate
+existing serializers to the `0.10` versions as needed.
+
+### `0.10` breaking changes
+- Passing a serializer to `render json:` is no longer supported
+
+```ruby
+render json: CustomerSerializer.new(customer) # rendered in 0.8, errors in 0.10
+```
+
+- Passing a nil resource to serializer now fails
+
+```ruby
+CustomerSerializer.new(nil) # returned nil in 0.8, throws error in 0.10
+```
+
+- Attribute methods are no longer defined on the serializer, and must be explicitly
+  accessed through `object`
+
+```ruby
+class MySerializer
+  attributes :foo, :bar
+
+  def foo
+    bar + 1 # bar does not work, needs to be object.bar in 0.10
+  end
+end
+```
+
+ - `root` option to collection serializer behaves differently
+
+```ruby
+# in 0.8
+ActiveModel::ArraySerializer.new(resources, root: "resources")
+# resulted in { "resources": <serialized_resources> }, does not work in 0.10
+```
+
+- No default serializer when serializer doesn't exist
+- `@options` changed to `instance_options`
+- Nested relationships are no longer walked by default. Use the `:include` option at **controller `render`** level to specify what relationships to walk. E.g. `render json: @post, include: {comments: :author}` if you want the `author` relationship walked, otherwise the json would only include the post with comments. See: https://github.com/rails-api/active_model_serializers/pull/1127
+- To emulate `0.8`'s walking of arbitrarily deep relationships use: `include: '**'`. E.g. `render json: @post, include: '**'`
+
+## Steps to migrate
+
+### 1. Upgrade the `active_model_serializer` gem in you `Gemfile`
+Change to `gem 'active_model_serializers', '~> 0.10'` and run `bundle install`
+
+### 2. Add `ActiveModel::V08::Serializer`
+
+```ruby
+module ActiveModel
+  module V08
+    class Serializer < ActiveModel::Serializer
+      include Rails.application.routes.url_helpers
+
+      # AMS 0.8 would delegate method calls from within the serializer to the
+      # object.
+      def method_missing(*args)
+        method = args.first
+        read_attribute_for_serialization(method)
+      end
+
+      alias_method :options, :instance_options
+
+      # Since attributes could be read from the `object` via `method_missing`,
+      # the `try` method did not behave as before. This patches `try` with the
+      # original implementation plus the addition of
+      # ` || object.respond_to?(a.first, true)` to check if the object responded to
+      # the given method.
+      def try(*a, &b)
+        if a.empty? || respond_to?(a.first, true) || object.respond_to?(a.first, true)
+          try!(*a, &b)
+        end
+      end
+
+      # AMS 0.8 would return nil if the serializer was initialized with a nil
+      # resource.
+      def serializable_hash(adapter_options = nil,
+                            options = {},
+                            adapter_instance =
+                              self.class.serialization_adapter_instance)
+        object.nil? ? nil : super
+      end
+    end
+  end
+end
+
+```
+Add this class to your app however you see fit. This is the class that your existing serializers
+that inherit from `ActiveModel::Serializer` should inherit from.
+
+### 3. Add `ActiveModel::V08::CollectionSerializer`
+```ruby
+module ActiveModel
+  module V08
+    class CollectionSerializer < ActiveModel::Serializer::CollectionSerializer
+      # In AMS 0.8, passing an ArraySerializer instance with a `root` option
+      # properly nested the serialized resources within the given root.
+      # Ex.
+      #
+      # class MyController < ActionController::Base
+      #   def index
+      #     render json: ActiveModel::Serializer::ArraySerializer
+      #       .new(resources, root: "resources")
+      #   end
+      # end
+      #
+      # Produced
+      #
+      # {
+      #   "resources": [
+      #     <serialized_resource>,
+      #     ...
+      #   ]
+      # }
+      def as_json(options = {})
+        if root
+          {
+            root => super
+          }
+        else
+          super
+        end
+      end
+
+      # AMS 0.8 used `DefaultSerializer` if it couldn't find a serializer for
+      # the given resource. When not using an adapter, this is not true in
+      # `0.10`
+      def serializer_from_resource(resource, serializer_context_class, options)
+        serializer_class =
+          options.fetch(:serializer) { serializer_context_class.serializer_for(resource) }
+
+        if serializer_class.nil? # rubocop:disable Style/GuardClause
+          DefaultSerializer.new(resource, options)
+        else
+          serializer_class.new(resource, options.except(:serializer))
+        end
+      end
+
+      class DefaultSerializer
+        attr_reader :object, :options
+
+        def initialize(object, options={})
+          @object, @options = object, options
+        end
+
+        def serializable_hash
+          @object.as_json(@options)
+        end
+      end
+    end
+  end
+end
+```
+Add this class to your app however you see fit. This is the class that existing uses of
+`ActiveModel::ArraySerializer` should be changed to use.
+
+### 4. Add `ActiveModelSerializers::Adapter::V08Adapter`
+```ruby
+module ActiveModelSerializers
+  module Adapter
+    class V08Adapter < ActiveModelSerializers::Adapter::Base
+      def serializable_hash(options = nil)
+        options ||= {}
+
+        if serializer.respond_to?(:each)
+          if serializer.root
+            delegate_to_json_adapter(options)
+          else
+            serializable_hash_for_collection(options)
+          end
+        else
+          serializable_hash_for_single_resource(options)
+        end
+      end
+
+      def serializable_hash_for_collection(options)
+        serializer.map do |s|
+          V08Adapter.new(s, instance_options)
+            .serializable_hash(options)
+        end
+      end
+
+      def serializable_hash_for_single_resource(options)
+        if serializer.object.is_a?(ActiveModel::Serializer)
+          # It is recommended that you add some logging here to indicate
+          # places that should get converted to eventually allow for this
+          # adapter to get removed.
+          @serializer = serializer.object
+        end
+
+        if serializer.root
+          delegate_to_json_adapter(options)
+        else
+          options = serialization_options(options)
+          serializer.serializable_hash(instance_options, options, self)
+        end
+      end
+
+      def delegate_to_json_adapter(options)
+        ActiveModelSerializers::Adapter::Json
+          .new(serializer, instance_options)
+          .serializable_hash(options)
+      end
+    end
+  end
+end
+```
+Add this class to your app however you see fit.
+
+Add
+```ruby
+ActiveModelSerializers.config.adapter =
+  ActiveModelSerializers::Adapter::V08Adapter
+```
+to `config/active_model_serializer.rb` to configure AMS to use this
+class as the default adapter.
+
+### 5. Change inheritors of `ActiveModel::Serializer` to inherit from `ActiveModel::V08::Serializer`
+Simple find/replace
+
+### 6. Remove `private` keyword from serializers
+Simple find/replace. This is required to allow the `ActiveModel::V08::Serializer`
+to have proper access to the methods defined in the serializer.
+
+You may be able to change the `private` to `protected`, but this is hasn't been tested yet.
+
+### 7. Remove references to `ActiveRecord::Base#active_model_serializer`
+This method is no longer supported in `0.10`.
+
+`0.10` does a good job of discovering serializers for `ActiveRecord` objects.
+
+### 8. Rename `ActiveModel::ArraySerializer` to `ActiveModel::V08::CollectionSerializer`
+Find/replace uses of `ActiveModel::ArraySerializer` with `ActiveModel::V08::CollectionSerializer`.
+
+Also, be sure to change the `each_serializer` keyword to `serializer` when calling making the replacement.
+
+### 9. Replace uses of `@options` to `instance_options` in serializers
+Simple find/replace
+
+## Conclusion
+After you've done the steps above, you should test your app to ensure that everything is still working properly.
+
+If you run into issues, please contribute back to this document so others can benefit from your knowledge.
+