active_model_serializers_custom 0.10.90

data/docs/howto/add_pagination_links.md

@@ -0,0 +1,138 @@
+[Back to Guides](../README.md)
+
+# How to add pagination links
+
+### JSON API adapter
+
+Pagination links will be included in your response automatically as long as
+the resource is paginated and if you are using the ```JsonApi``` adapter.
+
+If you want pagination links in your response, use [Kaminari](https://github.com/amatsuda/kaminari)
+or [WillPaginate](https://github.com/mislav/will_paginate).
+
+Although the other adapters do not have this feature, it is possible to
+implement pagination links to `JSON` adapter. For more information about it,
+please check our docs.
+
+###### Kaminari examples
+
+```ruby
+#array
+@posts = Kaminari.paginate_array([1, 2, 3]).page(3).per(1)
+render json: @posts
+
+#active_record
+@posts = Post.page(3).per(1)
+render json: @posts
+```
+
+###### WillPaginate examples
+
+```ruby
+#array
+@posts = [1,2,3].paginate(page: 3, per_page: 1)
+render json: @posts
+
+#active_record
+@posts = Post.page(3).per_page(1)
+render json: @posts
+```
+
+```ruby
+ActiveModelSerializers.config.adapter = :json_api
+```
+
+ex:
+```json
+{
+  "data": [
+    {
+      "type": "articles",
+      "id": "3",
+      "attributes": {
+        "title": "JSON API paints my bikeshed!",
+        "body": "The shortest article. Ever.",
+        "created": "2015-05-22T14:56:29.000Z",
+        "updated": "2015-05-22T14:56:28.000Z"
+      }
+    }
+  ],
+  "links": {
+    "self": "http://example.com/articles?page[number]=3&page[size]=1",
+    "first": "http://example.com/articles?page[number]=1&page[size]=1",
+    "prev": "http://example.com/articles?page[number]=2&page[size]=1",
+    "next": "http://example.com/articles?page[number]=4&page[size]=1",
+    "last": "http://example.com/articles?page[number]=13&page[size]=1"
+  }
+}
+```
+
+ActiveModelSerializers pagination relies on a paginated collection with the methods `current_page`, `total_pages`, and `size`, such as are supported by both [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate).
+
+
+### JSON adapter
+
+If you are not using `JSON` adapter, pagination links will not be included automatically, but it is possible to do so using `meta` key.
+
+Add this method to your base API controller.
+
+```ruby
+def pagination_dict(collection)
+  {
+    current_page: collection.current_page,
+    next_page: collection.next_page,
+    prev_page: collection.prev_page, # use collection.previous_page when using will_paginate
+    total_pages: collection.total_pages,
+    total_count: collection.total_count
+  }
+end
+```
+
+Then, use it on your render method.
+
+```ruby
+render json: posts, meta: pagination_dict(posts)
+```
+
+ex.
+```json
+{
+  "posts": [
+    {
+      "id": 2,
+      "title": "JSON API paints my bikeshed!",
+      "body": "The shortest article. Ever."
+    }
+  ],
+  "meta": {
+    "current_page": 3,
+    "next_page": 4,
+    "prev_page": 2,
+    "total_pages": 10,
+    "total_count": 10
+  }
+}
+```
+
+You can also achieve the same result if you have a helper method that adds the pagination info in the meta tag. For instance, in your action specify a custom serializer.
+
+```ruby
+render json: @posts, each_serializer: PostPreviewSerializer, meta: meta_attributes(@posts)
+```
+
+```ruby
+#expects pagination!
+def meta_attributes(collection, extra_meta = {})
+  {
+    current_page: collection.current_page,
+    next_page: collection.next_page,
+    prev_page: collection.prev_page, # use collection.previous_page when using will_paginate
+    total_pages: collection.total_pages,
+    total_count: collection.total_count
+  }.merge(extra_meta)
+end
+```
+
+### Attributes adapter
+
+This adapter does not allow us to use `meta` key, due to that it is not possible to add pagination links.

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
+```