active_model_serializers 0.8.3 → 0.10.8

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

@@ -0,0 +1,62 @@
+[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:
+
+```json
+{
+  "id": 1,
+  "title": "Awesome Post Tile",
+  "content": "Post content"
+}
+```
+
+In order to add the root key you need to use the ```JSON``` Adapter, you can change this in an initializer:
+
+```ruby
+ActiveModelSerializers.config.adapter = :json
+```
+
+Note that adapter configuration has no effect on a serializer that is called
+directly, e.g. in a serializer unit test. Instead, something like
+`UserSerializer.new(user).as_json` will *always* behave as if the adapter were
+the 'Attributes' adapter. See [Outside Controller
+Usage](../howto/outside_controller_use.md) for more details on recommended
+usage.
+
+You can also specify a class as adapter, as long as it complies with the ActiveModelSerializers adapters interface.
+It will add the root key to all your serialized endpoints.
+
+ex:
+
+```json
+{
+  "post": {
+    "id": 1,
+    "title": "Awesome Post Tile",
+    "content": "Post content"
+  }
+}
+```
+
+or if it returns a collection:
+
+```json
+{
+  "posts": [
+    {
+      "id": 1,
+      "title": "Awesome Post Tile",
+      "content": "Post content"
+    },
+    {
+      "id": 2,
+      "title": "Another Post Tile",
+      "content": "Another post content"
+    }
+  ]
+}
+```
+
+[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

@@ -0,0 +1,66 @@
+[Back to Guides](../README.md)
+
+## Using ActiveModelSerializers Outside Of A Controller
+
+### Serializing a resource
+
+In ActiveModelSerializers versions 0.10 or later, serializing resources outside of the controller context is fairly simple:
+
+```ruby
+# Create our resource
+post = Post.create(title: "Sample post", body: "I love Active Model Serializers!")
+
+# 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)
+
+# 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 the serializer class for a specific resource, you can do the following:
+
+```ruby
+# Create our resource
+post = Post.create(title: "Another Example", body: "So much fun.")
+
+# Optional options parameters
+options = {}
+
+# Retrieve the default serializer for posts
+serializer = ActiveModel::Serializer.serializer_for(post, options)
+```
+
+You could also retrieve the serializer via:
+
+```ruby
+ActiveModelSerializers::SerializableResource.new(post, options).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
+
+At times, you might want to use a serializer without rendering it to the view. For those cases, you can create an instance of `ActiveModelSerializers::SerializableResource` with
+the resource you want to be serialized and call `.as_json`.
+
+```ruby
+def create
+  message = current_user.messages.create!(message_params)
+  message_json = ActiveModelSerializers::SerializableResource.new(message).as_json
+  MessageCreationWorker.perform(message_json)
+  head 204
+end
+```

data/docs/howto/passing_arbitrary_options.md

@@ -0,0 +1,27 @@
+[Back to Guides](../README.md)
+
+# Passing Arbitrary Options To A Serializer
+
+In addition to the [`serialization_scope`](../general/serializers.md#scope), any options passed to `render`
+that are not reserved for the [adapter](../general/rendering.md#adapter_opts)
+are available in the serializer as [instance_options](../general/serializers.md#instance_options).
+
+For example, we could pass in a field, such as `user_id` into our serializer.
+
+```ruby
+# posts_controller.rb
+class PostsController < ApplicationController
+  def dashboard
+    render json: @post, user_id: 12
+  end
+end
+
+# post_serializer.rb
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body
+
+  def comments_by_me
+    Comments.where(user_id: instance_options[:user_id], post_id: object.id)
+  end
+end
+```

data/docs/howto/serialize_poro.md

@@ -0,0 +1,73 @@
+[Back to Guides](../README.md)
+
+# 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 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]
+    @level = attributes[:level]
+  end
+
+  def self.model_name
+    @_model_name ||= ActiveModel::Name.new(self)
+  end
+end
+```
+
+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
+  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
+```
+
+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

@@ -0,0 +1,154 @@
+[Back to Guides](../README.md)
+
+# How to test
+
+## Controller Serializer Usage
+
+ActiveModelSerializers provides a `assert_serializer` method to be used on your controller tests to
+assert that a specific serializer was used.
+
+```ruby
+class PostsControllerTest < ActionController::TestCase
+  test "should render post serializer" do
+    get :index
+    assert_serializer "PostSerializer"
+  end
+end
+```
+
+See [ActiveModelSerializers::Test::Serializer](../../lib/active_model_serializers/test/serializer.rb)
+for more examples and documentation.
+
+## Serialization against a schema
+
+### Dependencies
+
+To use the `assert_response_schema` you need to have the
+[`json_schema`](https://github.com/brandur/json_schema) on your Gemfile. Please
+add it to your Gemfile and run `$ bundle install`.
+
+### Minitest test helpers
+
+ActiveModelSerializers provides a `assert_response_schema` method to be used on your controller tests to
+assert the response against a [JSON Schema](http://json-schema.org/). Let's take
+a look in an example.
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+
+    render json: @post
+  end
+end
+```
+
+To test the `posts#show` response of this controller we need to create a file
+named `test/support/schemas/posts/show.json`. The helper uses a naming convention
+to locate the file.
+
+This file is a JSON Schema representation of our response.
+
+```json
+{
+  "properties": {
+    "title" : { "type" : "string" },
+    "content" : { "type" : "string" }
+  }
+}
+```
+
+With all in place we can go to our test and use the helper.
+
+```ruby
+class PostsControllerTest < ActionController::TestCase
+  test "should render right response" do
+    get :index
+    assert_response_schema
+  end
+end
+```
+
+#### Load a custom schema
+
+If we need to use another schema, for example when we have a namespaced API that
+shows the same response, we can pass the path of the schema.
+
+```ruby
+module V1
+  class PostsController < ApplicationController
+    def show
+      @post = Post.find(params[:id])
+
+      render json: @post
+    end
+  end
+end
+```
+
+```ruby
+class V1::PostsControllerTest < ActionController::TestCase
+  test "should render right response" do
+    get :index
+    assert_response_schema('posts/show.json')
+  end
+end
+```
+
+#### Change the schema path
+
+By default all schemas are created at `test/support/schemas`. If we are using
+RSpec for example we can change this to `spec/support/schemas` defining the
+default schema path in an initializer.
+
+```ruby
+ActiveModelSerializers.config.schema_path = 'spec/support/schemas'
+```
+
+#### Using with the Heroku’s JSON Schema-based tools
+
+To use the test helper with the [prmd](https://github.com/interagent/prmd) and
+[committee](https://github.com/interagent/committee).
+
+We need to change the schema path to the recommended by prmd:
+
+```ruby
+ActiveModelSerializers.config.schema_path = 'docs/schema/schemata'
+```
+
+We also need to structure our schemata according to Heroku's conventions
+(e.g. including
+[required metadata](https://github.com/interagent/prmd/blob/master/docs/schemata.md#meta-data)
+and [links](https://github.com/interagent/prmd/blob/master/docs/schemata.md#links).
+
+#### JSON Pointers
+
+If we plan to use [JSON
+Pointers](http://spacetelescope.github.io/understanding-json-schema/UnderstandingJSONSchema.pdf) we need to define the `id` attribute on the schema. Example:
+
+```js
+// attributes.json
+
+{
+  "id": "file://attributes.json#",
+  "properties": {
+    "name" : { "type" : "string" },
+    "description" : { "type" : "string" }
+  }
+}
+```
+
+```js
+// show.json
+
+{
+  "properties": {
+    "name": {
+      "$ref": "file://attributes.json#/properties/name"
+    },
+    "description": {
+      "$ref": "file://attributes.json#/properties/description"
+    }
+  }
+}
+```