active_model_serializers 0.10.7 → 0.10.10

data/docs/howto/upgrade_from_0_8_to_0_10.md

@@ -1,265 +0,0 @@
-[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.
-

data/docs/integrations/ember-and-json-api.md

@@ -1,147 +0,0 @@
-[Back to Guides](../README.md)
-
-# Integrating with Ember and JSON API
-
- - [Preparation](./ember-and-json-api.md#preparation)
- - [Server-Side Changes](./ember-and-json-api.md#server-side-changes)
- - [Adapter Changes](./ember-and-json-api.md#adapter-changes)
-   - [Serializer Changes](./ember-and-json-api.md#serializer-changes)
- - [Including Nested Resources](./ember-and-json-api.md#including-nested-resources)
-
-## Preparation
-
-Note: This guide assumes that `ember-cli` is used for your ember app.
-
-The JSON API specification calls for hyphens for multi-word separators. ActiveModelSerializers uses underscores.
-To solve this, in Ember, both the adapter and the serializer will need some modifications:
-
-### Server-Side Changes
-
-First, set the adapter type in an initializer file:
-
-```ruby
-# config/initializers/active_model_serializers.rb
-ActiveModelSerializers.config.adapter = :json_api
-```
-
-or:
-
-```ruby
-# config/initializers/active_model_serializers.rb
-ActiveModelSerializers.config.adapter = ActiveModelSerializers::Adapter::JsonApi
-```
-
-You will also want to set the `key_transform` to `:unaltered` since you will adjust the attributes in your Ember serializer to use underscores instead of dashes later. You could also use `:underscore`, but `:unaltered` is better for performance.
-
-```ruby
-# config/initializers/active_model_serializers.rb
-ActiveModelSerializers.config.key_transform = :unaltered
-```
-
-In order to properly handle JSON API responses, we need to register a JSON API renderer, like so:
-
-```ruby
-# config/initializers/active_model_serializers.rb
-ActiveSupport.on_load(:action_controller) do
-  require 'active_model_serializers/register_jsonapi_renderer'
-end
-```
-Rails also requires your controller to tell it that you accept and generate JSONAPI data.  To do that, you use `respond_to` in your controller handlers to tell rails you are consuming and returning jsonapi format data. Without this, Rails will refuse to parse the request body into params.  You can add `ActionController::MimeResponds` to your application controller to enable this:
-
-```ruby
-class ApplicationController < ActionController::API
-  include ActionController::MimeResponds
-end
-```
-Then, in your controller you can tell rails you're accepting and rendering the jsonapi format:
-```ruby
- # POST /post
-  def create
-    @post = Post.new(post_params)
-    respond_to do |format|
-      if @post.save
-        format.jsonapi { render jsonapi: @post, status: :created, location: @post }
-      else
-        format.jsonapi { render jsonapi: @post.errors, status: :unprocessable_entity }
-      end
-    end
-  end
-  
-    # Only allow a trusted parameter "white list" through.
-    def post_params
-      ActiveModelSerializers::Deserialization.jsonapi_parse!(params, only: [:title, :body] )
-    end
-end
-```
-
-#### Note: 
-In Rails 5, the "unsafe" method ( `jsonapi_parse!` vs the safe `jsonapi_parse`) throws an `InvalidDocument` exception when the payload does not meet basic criteria for JSON API deserialization.
-
-
-### Adapter Changes
-
-```javascript
-// app/adapters/application.js
-import Ember from 'ember';
-import DS from 'ember-data';
-import ENV from "../config/environment";
-const { underscore, pluralize } = Ember.String;
-
-export default  DS.JSONAPIAdapter.extend({
-  namespace: 'api',
-  // if your rails app is on a different port from your ember app
-  // this can be helpful for development.
-  // in production, the host for both rails and ember should be the same.
-  host: ENV.host,
-
-  // allows the multiword paths in urls to be underscored
-  pathForType: function(type) {
-    let underscored = underscore(type);
-    return pluralize(underscored);
-  },
-
-});
-```
-
-### Serializer Changes
-
-```javascript
-// app/serializers/application.js
-import Ember from 'ember';
-import DS from 'ember-data';
-var underscore = Ember.String.underscore;
-
-export default DS.JSONAPISerializer.extend({
-  keyForAttribute: function(attr) {
-    return underscore(attr);
-  },
-
-  keyForRelationship: function(rawKey) {
-    return underscore(rawKey);
-  }
-});
-
-```
-
-
-## Including Nested Resources
-
-Ember Data can request related records by using `include`.  Below are some examples of how to make Ember Data request the inclusion of related records. For more on `include` usage, see: [The JSON API include examples](./../general/adapters.md#JSON-API)
-
-```javascript
-store.findRecord('post', postId, { include: 'comments' } );
-```
-which will generate the path /posts/{postId}?include='comments'
-
-So then in your controller, you'll want to be sure to have something like:
-```ruby
-render jsonapi: @post, include: params[:include]
-```
-
-If you want to use `include` on a collection, you'd write something like this:
-
-```javascript
-store.query('post', { include: 'comments' });
-```
-
-which will generate the path `/posts?include='comments'`

data/docs/integrations/grape.md

@@ -1,19 +0,0 @@
-# Integration with Grape
-
-[Grape](https://github.com/ruby-grape/grape) is an opinionated micro-framework for creating REST-like APIs in ruby.
-
-ActiveModelSerializers currently supports Grape >= 0.13, < 1.0
-
-To add [Grape](https://github.com/ruby-grape/grape) support, enable the formatter and helper functions by including `Grape::ActiveModelSerializers` in your base endpoint. For example:
-
-```ruby
-module Example
-  class Dummy < Grape::API
-    require 'grape/active_model_serializers'
-    include Grape::ActiveModelSerializers
-    mount Example::V1::Base
-  end
-end
-```
-
-Aside from this, [configuration](../general/configuration_options.md) of ActiveModelSerializers is exactly the same.

data/docs/jsonapi/errors.md

@@ -1,56 +0,0 @@
-[Back to Guides](../README.md)
-
-# [JSON API Errors](http://jsonapi.org/format/#errors)
-
-Rendering error documents requires specifying the error serializer(s):
-
-- Serializer:
-  - For a single resource: `serializer: ActiveModel::Serializer::ErrorSerializer`.
-  - For a collection: `serializer: ActiveModel::Serializer::ErrorsSerializer`, `each_serializer: ActiveModel::Serializer::ErrorSerializer`.
-
-The resource **MUST** have a non-empty associated `#errors` object.
-The `errors` object must have a `#messages` method that returns a hash of error name to array of
-descriptions.
-
-## Use in controllers
-
-```ruby
-resource = Profile.new(name: 'Name 1',
-                       description: 'Description 1',
-                       comments: 'Comments 1')
-resource.errors.add(:name, 'cannot be nil')
-resource.errors.add(:name, 'must be longer')
-resource.errors.add(:id, 'must be a uuid')
-
-render json: resource, status: 422, adapter: :json_api, serializer: ActiveModel::Serializer::ErrorSerializer
-# #=>
-#  { :errors =>
-#    [
-#      { :source => { :pointer => '/data/attributes/name' }, :detail => 'cannot be nil' },
-#      { :source => { :pointer => '/data/attributes/name' }, :detail => 'must be longer' },
-#      { :source => { :pointer => '/data/attributes/id' }, :detail => 'must be a uuid' }
-#    ]
-#  }.to_json
-```
-
-## Direct error document generation
-
-```ruby
-options = nil
-resource = ModelWithErrors.new
-resource.errors.add(:name, 'must be awesome')
-
-serializable_resource = ActiveModelSerializers::SerializableResource.new(
-  resource, {
-    serializer: ActiveModel::Serializer::ErrorSerializer,
-    adapter: :json_api
-  })
-serializable_resource.as_json(options)
-# #=>
-# {
-#   :errors =>
-#     [
-#       { :source => { :pointer => '/data/attributes/name' }, :detail => 'must be awesome' }
-#     ]
-# }
-```