active_model_serializers_rails_2.3 0.9.0.alpha1

data/CHANGELOG.md

@@ -0,0 +1,87 @@
+# VERSION 0.9.0.pre
+
+* The following methods were removed
+  - Model#active\_model\_serializer
+  - Serializer#include!
+  - Serializer#include?
+  - Serializer#attr\_disabled=
+  - Serializer#cache
+  - Serializer#perform\_caching
+  - Serializer#schema (needs more discussion)
+  - Serializer#attribute
+  - Serializer#include\_#{name}? (filter method added)
+  - Serializer#attributes (took a hash)
+
+* The following things were added
+  - Serializer#filter method
+  - CONFIG object
+
+* Remove support for ruby 1.8 versions.
+
+* Require rails >= 3.2.
+
+# VERSION 0.8.1
+
+* Fix bug whereby a serializer using 'options' would blow up.
+
+# VERSION 0.8.0
+
+* Attributes can now have optional types.
+
+* A new DefaultSerializer ensures that POROs behave the same way as ActiveModels.
+
+* If you wish to override ActiveRecord::Base#to\_Json, you can now require
+  'active\_record/serializer\_override'. We don't recommend you do this, but
+  many users do, so we've left it optional.
+
+* Fixed a bug where ActionController wouldn't always have MimeResponds.
+
+* An optional caching feature allows you to cache JSON & hashes that AMS uses.
+  Adding 'cached true' to your Serializers will turn on this cache.
+
+* URL helpers used inside of Engines now work properly.
+
+* Serializers now can filter attributes with `only` and `except`:
+
+  ```
+  UserSerializer.new(user, only: [:first_name, :last_name])
+  UserSerializer.new(user, except: :first_name)
+  ```
+
+* Basic Mongoid support. We now include our mixins in the right place.
+
+* On Ruby 1.8, we now generate an `id` method that properly serializes `id`
+  columns. See issue #127 for more.
+
+* Add an alias for `scope` method to be the name of the context. By default
+  this is `current_user`. The name is automatically set when using
+  `serialization_scope` in the controller.
+
+* Pass through serialization options (such as `:include`) when a model
+  has no serializer defined.
+
+# VERSION 0.7.0
+
+* ```embed_key``` option to allow embedding by attributes other than IDs
+* Fix rendering nil with custom serializer
+* Fix global ```self.root = false```
+* Add support for specifying the serializer for an association as a String
+* Able to specify keys on the attributes method
+* Serializer Reloading via ActiveSupport::DescendantsTracker
+* Reduce double map to once; Fixes datamapper eager loading.
+
+# VERSION 0.6.0
+
+* Serialize sets properly
+* Add root option to ArraySerializer
+* Support polymorphic associations
+* Support :each_serializer in ArraySerializer
+* Add `scope` method to easily access the scope in the serializer
+* Fix regression with Rails 3.2.6; add Rails 4 support
+* Allow serialization_scope to be disabled with serialization_scope nil
+* Array serializer should support pure ruby objects besides serializers
+
+# VERSION 0.5.0
+
+* First tagged version
+* Changes generators to always generate an ApplicationSerializer

data/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+Contributing to AMS
+===================
+
+First of all, **thank you**!
+
+Now, for the details:
+
+Please file issues on the [GitHub Issues
+list](https://github.com/rails-api/active_model_serializers/issues).
+
+Please discuss new features or ask for feedback about a new feature [on
+rails-api-core](https://groups.google.com/forum/#!forum/rails-api-core).
+
+If you want a feature implemented, the best way to get it done is to submit a
+pull request that implements it. Tests and docs would be nice.
+
+Please include a CHANGELOG with all entries that change behavior.
+
+:heart: :sparkling_heart: :heart:
+

data/DESIGN.textile

@@ -0,0 +1,586 @@
+<strong>This was the original design document for serializers.</strong> It is useful mostly for historical purposes as the public API has changed.
+
+h2. Rails Serializers
+
+This guide describes how to use Active Model serializers to build non-trivial JSON services in Rails. By reading this guide, you will learn:
+
+* When to use the built-in Active Model serialization
+* When to use a custom serializer for your models
+* How to use serializers to encapsulate authorization concerns
+* How to create serializer templates to describe the application-wide structure of your serialized JSON
+* How to build resources not backed by a single database table for use with JSON services
+
+This guide covers an intermediate topic and assumes familiarity with Rails conventions. It is suitable for applications that expose a
+JSON API that may return different results based on the authorization status of the user.
+
+h3. Serialization
+
+By default, Active Record objects can serialize themselves into JSON by using the `to_json` method. This method takes a series of additional
+parameter to control which properties and associations Rails should include in the serialized output.
+
+When building a web application that uses JavaScript to retrieve JSON data from the server, this mechanism has historically been the primary
+way that Rails developers prepared their responses. This works great for simple cases, as the logic for serializing an Active Record object
+is neatly encapsulated in Active Record itself.
+
+However, this solution quickly falls apart in the face of serialization requirements based on authorization. For instance, a web service
+may choose to expose additional information about a resource only if the user is entitled to access it. In addition, a JavaScript front-end
+may want information that is not neatly described in terms of serializing a single Active Record object, or in a different format than.
+
+In addition, neither the controller nor the model seems like the correct place for logic that describes how to serialize an model object
+*for the current user*.
+
+Serializers solve these problems by encapsulating serialization in an object designed for this purpose. If the default +to_json+ semantics,
+with at most a few configuration options serve your needs, by all means continue to use the built-in +to_json+. If you find yourself doing
+hash-driven-development in your controllers, juggling authorization logic and other concerns, serializers are for you!
+
+h3. The Most Basic Serializer
+
+A basic serializer is a simple Ruby object named after the model class it is serializing.
+
+<pre lang="ruby">
+class PostSerializer
+  def initialize(post, scope)
+    @post, @scope = post, scope
+  end
+
+  def as_json
+    { post: { title: @post.name, body: @post.body } }
+  end
+end
+</pre>
+
+A serializer is initialized with two parameters: the model object it should serialize and an authorization scope. By default, the
+authorization scope is the current user (+current_user+) but you can use a different object if you want. The serializer also
+implements an +as_json+ method, which returns a Hash that will be sent to the JSON encoder.
+
+Rails will transparently use your serializer when you use +render :json+ in your controller.
+
+<pre lang="ruby">
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+    render json: @post
+  end
+end
+</pre>
+
+Because +respond_with+ uses +render :json+ under the hood for JSON requests, Rails will automatically use your serializer when
+you use +respond_with+ as well.
+
+h4. +serializable_hash+
+
+In general, you will want to implement +serializable_hash+ and +as_json+ to allow serializers to embed associated content
+directly. The easiest way to implement these two methods is to have +as_json+ call +serializable_hash+ and insert the root.
+
+<pre lang="ruby">
+class PostSerializer
+  def initialize(post, scope)
+    @post, @scope = post, scope
+  end
+
+  def serializable_hash
+    { title: @post.name, body: @post.body }
+  end
+
+  def as_json
+    { post: serializable_hash }
+  end
+end
+</pre>
+
+h4. Authorization
+
+Let's update our serializer to include the email address of the author of the post, but only if the current user has superuser
+access.
+
+<pre lang="ruby">
+class PostSerializer
+  def initialize(post, scope)
+    @post, @scope = post, scope
+  end
+
+  def as_json
+    { post: serializable_hash }
+  end
+
+  def serializable_hash
+    hash = post
+    hash.merge!(super_data) if super?
+    hash
+  end
+
+private
+  def post
+    { title: @post.name, body: @post.body }
+  end
+
+  def super_data
+    { email: @post.email }
+  end
+
+  def super?
+    @scope.superuser?
+  end
+end
+</pre>
+
+h4. Testing
+
+One benefit of encapsulating our objects this way is that it becomes extremely straight-forward to test the serialization
+logic in isolation.
+
+<pre lang="ruby">
+require "ostruct"
+
+class PostSerializerTest < ActiveSupport::TestCase
+  # For now, we use a very simple authorization structure. These tests will need
+  # refactoring if we change that.
+  plebe = OpenStruct.new(super?: false)
+  god   = OpenStruct.new(super?: true)
+
+  post  = OpenStruct.new(title: "Welcome to my blog!", body: "Blah blah blah", email: "tenderlove@gmail.com")
+
+  test "a regular user sees just the title and body" do
+    json = PostSerializer.new(post, plebe).to_json
+    hash = JSON.parse(json)
+
+    assert_equal post.title, hash.delete("title")
+    assert_equal post.body, hash.delete("body")
+    assert_empty hash
+  end
+
+  test "a superuser sees the title, body and email" do
+    json = PostSerializer.new(post, god).to_json
+    hash = JSON.parse(json)
+
+    assert_equal post.title, hash.delete("title")
+    assert_equal post.body, hash.delete("body")
+    assert_equal post.email, hash.delete("email")
+    assert_empty hash
+  end
+end
+</pre>
+
+It's important to note that serializer objects define a clear interface specifically for serializing an existing object.
+In this case, the serializer expects to receive a post object with +name+, +body+ and +email+ attributes and an authorization
+scope with a +super?+ method.
+
+By defining a clear interface, it's must easier to ensure that your authorization logic is behaving correctly. In this case,
+the serializer doesn't need to concern itself with how the authorization scope decides whether to set the +super?+ flag, just
+whether it is set. In general, you should document these requirements in your serializer files and programatically via tests.
+The documentation library +YARD+ provides excellent tools for describing this kind of requirement:
+
+<pre lang="ruby">
+class PostSerializer
+  # @param [~body, ~title, ~email] post the post to serialize
+  # @param [~super] scope the authorization scope for this serializer
+  def initialize(post, scope)
+    @post, @scope = post, scope
+  end
+
+  # ...
+end
+</pre>
+
+h3. Attribute Sugar
+
+To simplify this process for a number of common cases, Rails provides a default superclass named +ActiveModel::Serializer+
+that you can use to implement your serializers.
+
+For example, you will sometimes want to simply include a number of existing attributes from the source model into the outputted
+JSON. In the above example, the +title+ and +body+ attributes were always included in the JSON. Let's see how to use
++ActiveModel::Serializer+ to simplify our post serializer.
+
+<pre lang="ruby">
+class PostSerializer < ActiveModel::Serializer
+  attributes :title, :body
+
+  def serializable_hash
+    hash = attributes
+    hash.merge!(super_data) if super?
+    hash
+  end
+
+private
+  def super_data
+    { email: @post.email }
+  end
+
+  def super?
+    @scope.superuser?
+  end
+end
+</pre>
+
+First, we specified the list of included attributes at the top of the class. This will create an instance method called
++attributes+ that extracts those attributes from the post model.
+
+NOTE: Internally, +ActiveModel::Serializer+ uses +read_attribute_for_serialization+, which defaults to +read_attribute+, which defaults to +send+. So if you're rolling your own models for use with the serializer, you can use simple Ruby accessors for your attributes if you like.
+
+Next, we use the attributes method in our +serializable_hash+ method, which allowed us to eliminate the +post+ method we hand-rolled
+earlier. We could also eliminate the +as_json+ method, as +ActiveModel::Serializer+ provides a default +as_json+ method for
+us that calls our +serializable_hash+ method and inserts a root. But we can go a step further!
+
+<pre lang="ruby">
+class PostSerializer < ActiveModel::Serializer
+  attributes :title, :body
+
+private
+  def attributes
+    hash = super
+    hash.merge!(email: post.email) if super?
+    hash
+  end
+
+  def super?
+    @scope.superuser?
+  end
+end
+</pre>
+
+The superclass provides a default +initialize+ method as well as a default +serializable_hash+ method, which uses
++attributes+. We can call +super+ to get the hash based on the attributes we declared, and then add in any additional
+attributes we want to use.
+
+NOTE: +ActiveModel::Serializer+ will create an accessor matching the name of the current class for the resource you pass in. In this case, because we have defined a PostSerializer, we can access the resource with the +post+ accessor.
+
+h3. Associations
+
+In most JSON APIs, you will want to include associated objects with your serialized object. In this case, let's include
+the comments with the current post.
+
+<pre lang="ruby">
+class PostSerializer < ActiveModel::Serializer
+  attributes :title, :body
+  has_many :comments
+
+private
+  def attributes
+    hash = super
+    hash.merge!(email: post.email) if super?
+    hash
+  end
+
+  def super?
+    @scope.superuser?
+  end
+end
+</pre>
+
+The default +serializable_hash+ method will include the comments as embedded objects inside the post.
+
+<pre lang="json">
+{
+  post: {
+    title: "Hello Blog!",
+    body: "This is my first post. Isn't it fabulous!",
+    comments: [
+      {
+        title: "Awesome",
+        body: "Your first post is great"
+      }
+    ]
+  }
+}
+</pre>
+
+Rails uses the same logic to generate embedded serializations as it does when you use +render :json+. In this case,
+because you didn't define a +CommentSerializer+, Rails used the default +as_json+ on your comment object.
+
+If you define a serializer, Rails will automatically instantiate it with the existing authorization scope.
+
+<pre lang="ruby">
+class CommentSerializer
+  def initialize(comment, scope)
+    @comment, @scope = comment, scope
+  end
+
+  def serializable_hash
+    { title: @comment.title }
+  end
+
+  def as_json
+    { comment: serializable_hash }
+  end
+end
+</pre>
+
+If we define the above comment serializer, the outputted JSON will change to:
+
+<pre lang="json">
+{
+  post: {
+    title: "Hello Blog!",
+    body: "This is my first post. Isn't it fabulous!",
+    comments: [{ title: "Awesome" }]
+  }
+}
+</pre>
+
+Let's imagine that our comment system allows an administrator to kill a comment, and we only want to allow
+users to see the comments they're entitled to see. By default, +has_many :comments+ will simply use the
++comments+ accessor on the post object. We can override the +comments+ accessor to limit the comments used
+to just the comments we want to allow for the current user.
+
+<pre lang="ruby">
+class PostSerializer < ActiveModel::Serializer
+  attributes :title. :body
+  has_many :comments
+
+private
+  def attributes
+    hash = super
+    hash.merge!(email: post.email) if super?
+    hash
+  end
+
+  def comments
+    post.comments_for(scope)
+  end
+
+  def super?
+    @scope.superuser?
+  end
+end
+</pre>
+
++ActiveModel::Serializer+ will still embed the comments, but this time it will use just the comments
+for the current user.
+
+NOTE: The logic for deciding which comments a user should see still belongs in the model layer. In general, you should encapsulate concerns that require making direct Active Record queries in scopes or public methods on your models.
+
+h4. Modifying Associations
+
+You can also rename associations if required. Say for example you have an association that
+makes sense to be named one thing in your code, but another when data is serialized.
+You can use the <code:key</code> option to specify a different name for an association.
+Here is an example:
+
+<pre lang="ruby">
+class UserSerializer < ActiveModel::Serializer
+  has_many :followed_posts, key: :posts
+  has_one :owned_account, key: :account
+end
+</pre>
+
+Using the <code>:key</code> without a <code>:serializer</code> option will use implicit detection
+to determine a serializer. In this example, you'd have to define two classes: <code>PostSerializer</code>
+and <code>AccountSerializer</code>. You can also add the <code>:serializer</code> option
+to set it explicitly:
+
+<pre lang="ruby">
+class UserSerializer < ActiveModel::Serializer
+  has_many :followed_posts, key: :posts, serializer: CustomPostSerializer
+  has_one :owne_account, key: :account, serializer: PrivateAccountSerializer
+end
+</pre>
+
+h3. Customizing Associations
+
+Not all front-ends expect embedded documents in the same form. In these cases, you can override the
+default +serializable_hash+, and use conveniences provided by +ActiveModel::Serializer+ to avoid having to
+build up the hash manually.
+
+For example, let's say our front-end expects the posts and comments in the following format:
+
+<pre lang="json">
+{
+  post: {
+    id: 1
+    title: "Hello Blog!",
+    body: "This is my first post. Isn't it fabulous!",
+    comments: [1,2]
+  },
+  comments: [
+    {
+      id: 1
+      title: "Awesome",
+      body: "Your first post is great"
+    },
+    {
+      id: 2
+      title: "Not so awesome",
+      body: "Why is it so short!"
+    }
+  ]
+}
+</pre>
+
+We could achieve this with a custom +as_json+ method. We will also need to define a serializer for comments.
+
+<pre lang="ruby">
+class CommentSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body
+
+  # define any logic for dealing with authorization-based attributes here
+end
+
+class PostSerializer < ActiveModel::Serializer
+  attributes :title, :body
+  has_many :comments
+
+  def as_json
+    { post: serializable_hash }.merge!(associations)
+  end
+
+  def serializable_hash
+    post_hash = attributes
+    post_hash.merge!(association_ids)
+    post_hash
+  end
+
+private
+  def attributes
+    hash = super
+    hash.merge!(email: post.email) if super?
+    hash
+  end
+
+  def comments
+    post.comments_for(scope)
+  end
+
+  def super?
+    @scope.superuser?
+  end
+end
+</pre>
+
+Here, we used two convenience methods: +associations+ and +association_ids+. The first,
++associations+, creates a hash of all of the define associations, using their defined
+serializers. The second, +association_ids+, generates a hash whose key is the association
+name and whose value is an Array of the association's keys.
+
+The +association_ids+ helper will use the overridden version of the association, so in
+this case, +association_ids+ will only include the ids of the comments provided by the
++comments+ method.
+
+
+h3. Special Association Serializers
+
+So far, associations defined in serializers use either the +as_json+ method on the model
+or the defined serializer for the association type. Sometimes, you may want to serialize
+associated models differently when they are requested as part of another resource than
+when they are requested on their own.
+
+For instance, we might want to provide the full comment when it is requested directly,
+but only its title when requested as part of the post. To achieve this, you can define
+a serializer for associated objects nested inside the main serializer.
+
+<pre lang="ruby">
+class PostSerializer < ActiveModel::Serializer
+  class CommentSerializer < ActiveModel::Serializer
+    attributes :id, :title
+  end
+
+  # same as before
+  # ...
+end
+</pre>
+
+In other words, if a +PostSerializer+ is trying to serialize comments, it will first
+look for +PostSerializer::CommentSerializer+ before falling back to +CommentSerializer+
+and finally +comment.as_json+.
+
+h3. Overriding the Defaults
+
+h4. Authorization Scope
+
+By default, the authorization scope for serializers is +:current_user+. This means
+that when you call +render json: @post+, the controller will automatically call
+its +current_user+ method and pass that along to the serializer's initializer.
+
+If you want to change that behavior, simply use the +serialization_scope+ class
+method.
+
+<pre lang="ruby">
+class PostsController < ApplicationController
+  serialization_scope :current_app
+end
+</pre>
+
+You can also implement an instance method called (no surprise) +serialization_scope+,
+which allows you to define a dynamic authorization scope based on the current request.
+
+WARNING: If you use different objects as authorization scopes, make sure that they all implement whatever interface you use in your serializers to control what the outputted JSON looks like.
+
+h3. Using Serializers Outside of a Request
+
+The serialization API encapsulates the concern of generating a JSON representation of
+a particular model for a particular user. As a result, you should be able to easily use
+serializers, whether you define them yourself or whether you use +ActiveModel::Serializer+
+outside a request.
+
+For instance, if you want to generate the JSON representation of a post for a user outside
+of a request:
+
+<pre lang="ruby">
+user = get_user # some logic to get the user in question
+PostSerializer.new(post, user).to_json # reliably generate JSON output
+</pre>
+
+If you want to generate JSON for an anonymous user, you should be able to use whatever
+technique you use in your application to generate anonymous users outside of a request.
+Typically, that means creating a new user and not saving it to the database:
+
+<pre lang="ruby">
+user = User.new # create a new anonymous user
+PostSerializer.new(post, user).to_json
+</pre>
+
+In general, the better you encapsulate your authorization logic, the more easily you
+will be able to use the serializer outside of the context of a request. For instance,
+if you use an authorization library like Cancan, which uses a uniform +user.can?(action, model)+,
+the authorization interface can very easily be replaced by a plain Ruby object for
+testing or usage outside the context of a request.
+
+h3. Collections
+
+So far, we've talked about serializing individual model objects. By default, Rails
+will serialize collections, including when using the +associations+ helper, by
+looping over each element of the collection, calling +serializable_hash+ on the element,
+and then grouping them by their type (using the plural version of their class name
+as the root).
+
+For example, an Array of post objects would serialize as:
+
+<pre lang="json">
+{
+  posts: [
+    {
+      title: "FIRST POST!",
+      body: "It's my first pooooost"
+    },
+    { title: "Second post!",
+      body: "Zomg I made it to my second post"
+    }
+  ]
+}
+</pre>
+
+If you want to change the behavior of serialized Arrays, you need to create
+a custom Array serializer.
+
+<pre lang="ruby">
+class ArraySerializer < ActiveModel::ArraySerializer
+  def serializable_array
+    serializers.map do |serializer|
+      serializer.serializable_hash
+    end
+  end
+
+  def as_json
+    hash = { root => serializable_array }
+    hash.merge!(associations)
+    hash
+  end
+end
+</pre>
+
+When generating embedded associations using the +associations+ helper inside a
+regular serializer, it will create a new <code>ArraySerializer</code> with the
+associated content and call its +serializable_array+ method. In this case, those
+embedded associations will not recursively include associations.
+
+When generating an Array using +render json: posts+, the controller will invoke
+the +as_json+ method, which will include its associations and its root.