active_model_serializers 0.8.3 → 0.10.0.rc4

data/docs/general/adapters.md

@@ -0,0 +1,162 @@
+[Back to Guides](../README.md)
+
+# Adapters
+
+ActiveModelSerializers offers the ability to configure which adapter
+to use both globally and/or when serializing (usually when rendering).
+
+The global adapter configuration is set on [`ActiveModelSerializers.config`](configuration_options.md).
+It should be set only once, preferably at initialization.
+
+For example:
+
+```ruby
+ActiveModelSerializers.config.adapter = ActiveModel::Serializer::Adapter::JsonApi
+```
+
+or
+
+```ruby
+ActiveModelSerializers.config.adapter = :json_api
+```
+
+or
+
+```ruby
+ActiveModelSerializers.config.adapter = :json
+```
+
+The local adapter option is in the format `adapter: adapter`, where `adapter` is
+any of the same values as set globally.
+
+The configured adapter can be set as a symbol, class, or class name, as described in
+[Advanced adapter configuration](adapters.md#advanced-adapter-configuration).
+
+The `Attributes` adapter does not include a root key. It is just the serialized attributes.
+
+Use either the `JSON` or `JSON API` adapters if you want the response document to have a root key.
+
+## Built in Adapters
+
+### Attributes - Default
+
+It's the default adapter, it generates a json response without a root key.
+Doesn't follow any specific convention.
+
+### JSON
+
+The response document always with a root key.
+
+The root key **can't be overridden**, and will be derived from the resource being serialized.
+
+Doesn't follow any specific convention.
+
+### JSON API
+
+This adapter follows **version 1.0** of the [format specified](../jsonapi/schema.md) in
+[jsonapi.org/format](http://jsonapi.org/format).
+
+#### Included
+
+It will include the associated resources in the `"included"` member
+when the resource names are included in the `include` option.
+Including nested associated resources is also supported.
+
+```ruby
+  render json: @posts, include: ['author', 'comments', 'comments.author']
+  # or
+  render json: @posts, include: 'author,comments,comments.author'
+```
+
+In addition, two types of wildcards may be used:
+
+- `*` includes one level of associations.
+- `**` includes all recursively.
+
+These can be combined with other paths.
+
+```ruby
+  render json: @posts, include: '**' # or '*' for a single layer
+```
+
+The format of the `include` option can be either:
+
+- a String composed of a comma-separated list of [relationship paths](http://jsonapi.org/format/#fetching-includes).
+- an Array of Symbols and Hashes.
+- a mix of both.
+
+The following would render posts and include:
+
+- the author
+- the author's comments, and
+- every resource referenced by the author's comments (recursively).
+
+It could be combined, like above, with other paths in any combination desired.
+
+```ruby
+  render json: @posts, include: 'author.comments.**'
+```
+
+##### Security Considerations
+
+Since the included options may come from the query params (i.e. user-controller):
+
+```ruby
+  render json: @posts, include: params[:include]
+```
+
+The user could pass in `include=**`.
+
+We recommend filtering any user-supplied includes appropriately.
+
+## Advanced adapter configuration
+
+### Registering an adapter
+
+The default adapter can be configured, as above, to use any class given to it.
+
+An adapter may also be specified, e.g. when rendering, as a class or as a symbol.
+If a symbol, then the adapter must be, e.g. `:great_example`,
+`ActiveModel::Serializer::Adapter::GreatExample`, or registered.
+
+There are two ways to register an adapter:
+
+1) The simplest, is to subclass `ActiveModel::Serializer::Adapter`, e.g. the below will
+register the `Example::UsefulAdapter` as `:useful_adapter`.
+
+```ruby
+module Example
+  class UsefulAdapter < ActiveModel::Serializer::Adapter
+  end
+end
+```
+
+You'll notice that the name it registers is the class name underscored, not the full namespace.
+
+Under the covers, when the `ActiveModel::Serializer::Adapter` is subclassed, it registers
+the subclass as `register(:useful_adapter, Example::UsefulAdapter)`
+
+2) Any class can be registered as an adapter by calling `register` directly on the
+`ActiveModel::Serializer::Adapter` class. e.g., the below registers `MyAdapter` as
+`:special_adapter`.
+
+```ruby
+class MyAdapter; end
+ActiveModel::Serializer::Adapter.register(:special_adapter, MyAdapter)
+```
+
+### Looking up an adapter
+
+| Method | Return value |
+| :------------ |:---------------|
+| `ActiveModel::Serializer::Adapter.adapter_map` | A Hash of all known adapters `{ adapter_name => adapter_class }` |
+| `ActiveModel::Serializer::Adapter.adapters` | A (sorted) Array of all known `adapter_names` |
+| `ActiveModel::Serializer::Adapter.lookup(name_or_klass)` |  The `adapter_class`, else raises an `ActiveModel::Serializer::Adapter::UnknownAdapter` error |
+| `ActiveModel::Serializer::Adapter.adapter_class(adapter)` | Delegates to `ActiveModel::Serializer::Adapter.lookup(adapter)` |
+| `ActiveModel::Serializer.adapter` | A convenience method for `ActiveModel::Serializer::Adapter.lookup(config.adapter)` |
+
+The registered adapter name is always a String, but may be looked up as a Symbol or String.
+Helpfully, the Symbol or String is underscored, so that `get(:my_adapter)` and `get("MyAdapter")`
+may both be used.
+
+For more information, see [the Adapter class on GitHub](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializer/adapter.rb)

data/docs/general/caching.md

@@ -0,0 +1,52 @@
+[Back to Guides](../README.md)
+
+# Caching
+
+To cache a serializer, call ```cache``` and pass its options.
+The options are the same options of ```ActiveSupport::Cache::Store```, plus
+a ```key``` option that will be the prefix of the object cache
+on a pattern ```"#{key}/#{object.id}-#{object.updated_at}"```.
+
+The cache support is optimized to use the cached object in multiple request. An object cached on a ```show``` request will be reused at the ```index```. If there is a relationship with another cached serializer it will also be created and reused automatically.
+
+**[NOTE] Every object is individually cached.**
+
+**[NOTE] The cache is automatically expired after an object is updated, but it's not deleted.**
+
+```ruby
+cache(options = nil) # options: ```{key, expires_in, compress, force, race_condition_ttl}```
+```
+
+Take the example bellow:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  cache key: 'post', expires_in: 3.hours
+  attributes :title, :body
+
+  has_many :comments
+end
+```
+
+On this example every ```Post``` object will be cached with
+the key ```"post/#{post.id}-#{post.updated_at}"```. You can use this key to expire it as you want,
+but in this case it will be automatically expired after 3 hours.
+
+## Fragment Caching
+
+If there is some API endpoint that shouldn't be fully cached, you can still optimise it, using Fragment Cache on the attributes and relationships that you want to cache.
+
+You can define the attribute by using ```only``` or ```except``` option on cache method.
+
+**[NOTE] Cache serializers will be used at their relationships**
+
+Example:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  cache key: 'post', expires_in: 3.hours, only: [:title]
+  attributes :title, :body
+
+  has_many :comments
+end
+```

data/docs/general/configuration_options.md

@@ -0,0 +1,27 @@
+[Back to Guides](../README.md)
+
+# Configuration Options
+
+The following configuration options can be set on `ActiveModelSerializers.config`,
+preferably inside an initializer.
+
+## General
+
+- `adapter`: The [adapter](adapters.md) to use. Possible values: `:attributes, :json, :json_api`. Default: `:attributes`.
+- `serializer_lookup_enabled`: When `false`, serializers must be explicitly specified. Default: `true`
+
+## JSON API
+
+- `jsonapi_resource_type`: Whether the `type` attributes of resources should be singular or plural. Possible values: `:singular, :plural`. Default: `:plural`.
+- `jsonapi_include_toplevel_object`: Whether to include a [top level JSON API member](http://jsonapi.org/format/#document-jsonapi-object)
+   in the response document.
+   Default: `false`.
+- Used when `jsonapi_include_toplevel_object` is `true`:
+  - `jsonapi_version`: The latest version of the spec the API conforms to.
+    Default: `'1.0'`.
+  - `jsonapi_toplevel_meta`: Optional metadata. Not included if empty.
+    Default: `{}`.
+
+## Hooks
+
+To run a hook when ActiveModelSerializers is loaded, use `ActiveSupport.on_load(:action_controller) do end`

data/docs/general/getting_started.md

@@ -0,0 +1,98 @@
+[Back to Guides](../README.md)
+
+# Getting Started
+
+## Creating a Serializer
+
+The easiest way to create a new serializer is to generate a new resource, which
+will generate a serializer at the same time:
+
+```
+$ rails g resource post title:string body:string
+```
+
+This will generate a serializer in `app/serializers/post_serializer.rb` for
+your new model. You can also generate a serializer for an existing model with
+the serializer generator:
+
+```
+$ rails g serializer post
+```
+
+The generated serializer will contain basic `attributes` and
+`has_many`/`has_one`/`belongs_to` declarations, based on the model. For example:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :title, :body
+
+  has_many :comments
+  has_one :author
+end
+```
+
+and
+
+```ruby
+class CommentSerializer < ActiveModel::Serializer
+  attributes :name, :body
+
+  belongs_to :post_id
+end
+```
+
+The attribute names are a **whitelist** of attributes to be serialized.
+
+The `has_many`, `has_one`, and `belongs_to` declarations describe relationships between
+resources. By default, when you serialize a `Post`, you will get its `Comments`
+as well.
+
+For more information, see [Serializers](/docs/general/serializers.md).
+
+### Namespaced Models
+
+When serializing a model inside a namespace, such as `Api::V1::Post`, ActiveModelSerializers will expect the corresponding serializer to be inside the same namespace (namely `Api::V1::PostSerializer`).
+
+### Model Associations and Nested Serializers
+
+When declaring a serializer for a model with associations, such as:
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  has_many :comments
+end
+```
+ActiveModelSerializers will look for `PostSerializer::CommentSerializer` in priority, and fall back to `::CommentSerializer` in case the former does not exist. This allows for more control over the way a model gets serialized as an association of an other model.
+
+For example, in the following situation:
+
+```ruby
+class CommentSerializer < ActiveModel::Serializer
+  attributes :body, :date, :nb_likes
+end
+
+class PostSerializer < ActiveModel::Serializer
+  has_many :comments
+  class CommentSerializer < ActiveModel::Serializer
+    attributes :body_short
+  end
+end
+```
+
+ActiveModelSerializers will use `PostSerializer::CommentSerializer` (thus including only the `:body_short` attribute) when serializing a `Comment` as part of a `Post`, but use `::CommentSerializer` when serializing a `Comment` directly (thus including `:body, :date, :nb_likes`).
+
+## Rails Integration
+
+ActiveModelSerializers will automatically integrate with your Rails app,
+so you won't need to update your controller.
+This is a example of how the controller will look:
+
+```ruby
+class PostsController < ApplicationController
+
+  def show
+    @post = Post.find(params[:id])
+    render json: @post
+  end
+
+end
+```

data/docs/general/instrumentation.md

@@ -0,0 +1,40 @@
+[Back to Guides](../README.md)
+
+# Instrumentation
+
+ActiveModelSerializers uses the
+[ActiveSupport::Notification API](http://guides.rubyonrails.org/active_support_instrumentation.html#subscribing-to-an-event),
+which allows for subscribing to events, such as for logging.
+
+## Events
+
+Name:
+
+`render.active_model_serializers`
+
+Payload (example):
+
+```ruby
+{
+  serializer: PostSerializer,
+  adapter: ActiveModel::Serializer::Adapter::Attributes
+}
+```
+
+Subscribing:
+
+```ruby
+ActiveSupport::Notifications.subscribe 'render.active_model_serializers' do |name, started, finished, unique_id, data|
+  # whatever
+end
+ActiveSupport::Notifications.subscribe 'render.active_model_serializers' do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  # event.payload
+  # whatever
+end
+```
+
+## [LogSubscriber](http://api.rubyonrails.org/classes/ActiveSupport/LogSubscriber.html)
+
+ActiveModelSerializers includes an `ActiveModelSerializers::LogSubscriber` that attaches to
+`render.active_model_serializers`.

data/docs/general/logging.md

@@ -0,0 +1,14 @@
+[Back to Guides](../README.md)
+
+# Logging
+
+The default logger in a Rails application will be `Rails.logger`.
+
+When there is no `Rails.logger`, the default logger is an instance of
+`ActiveSupport::TaggedLogging` logging to STDOUT.
+
+You may customize the logger in an initializer, for example:
+
+```ruby
+ActiveModelSerializers.logger = Logger.new(STDOUT)
+```

data/docs/general/rendering.md

@@ -0,0 +1,153 @@
+[Back to Guides](../README.md)
+
+# Rendering
+
+### Implicit Serializer
+
+In your controllers, when you use `render :json`, Rails will now first search
+for a serializer for the object and use it if available.
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+
+    render json: @post
+  end
+end
+```
+
+In this case, Rails will look for a serializer named `PostSerializer`, and if
+it exists, use it to serialize the `Post`.
+
+### Explicit Serializer
+
+If you wish to use a serializer other than the default, you can explicitly pass it to the renderer.
+
+#### 1. For a resource:
+
+```ruby
+  render json: @post, serializer: PostPreviewSerializer
+```
+
+#### 2. For a resource collection:
+
+Specify the serializer for each resource with `each_serializer`
+
+```ruby
+render json: @posts, each_serializer: PostPreviewSerializer
+```
+
+The default serializer for collections is `CollectionSerializer`.
+
+Specify the collection serializer with the `serializer` option.
+
+```ruby
+render json: @posts, serializer: CollectionSerializer, each_serializer: PostPreviewSerializer
+```
+
+## Serializing non-ActiveRecord objects
+
+All serializable resources must pass the
+[ActiveModel::Serializer::Lint::Tests](../../lib/active_model/serializer/lint.rb#L17).
+
+See the ActiveModelSerializers::Model for a base class that implements the full
+API for a plain-old Ruby object (PORO).
+
+## SerializableResource options
+
+The `options` hash passed to `render` or `ActiveModel::SerializableResource.new(resource, options)`
+are partitioned into `serializer_opts` and `adapter_opts`. `adapter_opts` are passed to new Adapters;
+`serializer_opts` are passed to new Serializers.
+
+The `adapter_opts` are specified in [ActiveModel::SerializableResource::ADAPTER_OPTIONS](../../lib/active_model/serializable_resource.rb#L4).
+The `serializer_opts` are the remaining options.
+
+(In Rails, the `options` are also passed to the `as_json(options)` or `to_json(options)`
+methods on the resource serialization by the Rails JSON renderer.  They are, therefore, important
+to know about, but not part of ActiveModelSerializers.)
+
+See [ARCHITECTURE](../ARCHITECTURE.md) for more information.
+
+### adapter_opts
+
+#### fields
+
+PR please :)
+
+#### adapter
+
+PR please :)
+
+#### meta
+
+If you want a `meta` attribute in your response, specify it in the `render`
+call:
+
+```ruby
+render json: @post, meta: { total: 10 }
+```
+
+The key can be customized using `meta_key` option.
+
+```ruby
+render json: @post, meta: { total: 10 }, meta_key: "custom_meta"
+```
+
+`meta` will only be included in your response if you are using an Adapter that supports `root`,
+as JsonAPI and Json adapters, the default adapter (Attributes) doesn't have `root`.
+
+#### meta_key
+
+PR please :)
+
+#### links
+
+PR please :)
+
+### serializer_opts
+
+#### include
+
+PR please :)
+
+#### root
+
+The resource root is derived from the class name of the resource being serialized.
+e.g. `UserPostSerializer.new(UserPost.new)` will be serialized with the root `user_post` or `user_posts` according the adapter collection pluralization rules.
+
+Specify the root by passing it as an argument to `render`. For example:
+
+```ruby
+  render json: @user_post, root: "admin_post", adapter: :json
+```
+
+This will be rendered as:
+```json
+  {
+    "admin_post": {
+      "title": "how to do open source"
+    }
+  }
+```
+Note: the `Attributes` adapter (default) does not include a resource root.
+
+#### serializer
+
+PR please :)
+
+#### scope
+
+PR please :)
+
+#### scope_name
+
+PR please :)
+
+## Using a serializer without `render`
+
+See [Usage outside of a controller](../howto/outside_controller_use.md#serializing-before-controller-render).
+
+## Pagination
+
+See [How to add pagination links](https://github.com/rails-api/active_model_serializers/blob/master/docs/howto/add_pagination_links.md).