active_model_serializers 0.8.3 → 0.10.0

data/docs/general/adapters.md

@@ -0,0 +1,245 @@
+[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 = ActiveModelSerializers::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.
+
+##### Example output
+
+```json
+{
+  "title": "Title 1",
+  "body": "Body 1",
+  "publish_at": "2020-03-16T03:55:25.291Z",
+  "author": {
+    "first_name": "Bob",
+    "last_name": "Jones"
+  },
+  "comments": [
+    {
+      "body": "cool"
+    },
+    {
+      "body": "awesome"
+    }
+  ]
+}
+```
+
+### 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.
+
+##### Example output
+
+```json
+{
+  "post": {
+    "title": "Title 1",
+    "body": "Body 1",
+    "publish_at": "2020-03-16T03:55:25.291Z",
+    "author": {
+      "first_name": "Bob",
+      "last_name": "Jones"
+    },
+    "comments": [{
+      "body": "cool"
+    }, {
+      "body": "awesome"
+    }]
+  }
+}
+```
+
+### JSON API
+
+This adapter follows **version 1.0** of the [format specified](../jsonapi/schema.md) in
+[jsonapi.org/format](http://jsonapi.org/format).
+
+##### Example output
+
+```json
+{
+  "data": {
+    "id": "1337",
+    "type": "posts",
+    "attributes": {
+      "title": "Title 1",
+      "body": "Body 1",
+      "publish-at": "2020-03-16T03:55:25.291Z"
+    },
+    "relationships": {
+      "author": {
+        "data": {
+          "id": "1",
+          "type": "authors"
+        }
+      },
+      "comments": {
+        "data": [{
+          "id": "7",
+          "type": "comments"
+        }, {
+          "id": "12",
+          "type": "comments"
+        }]
+      }
+    },
+    "links": {
+      "post-authors": "https://example.com/post_authors"
+    },
+    "meta": {
+      "rating": 5,
+      "favorite-count": 10
+    }
+  }
+}
+```
+
+#### 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`,
+`ActiveModelSerializers::Adapter::GreatExample`, or registered.
+
+There are two ways to register an adapter:
+
+1) The simplest, is to subclass `ActiveModelSerializers::Adapter::Base`, e.g. the below will
+register the `Example::UsefulAdapter` as `"example/useful_adapter"`.
+
+```ruby
+module Example
+  class UsefulAdapter < ActiveModelSerializers::Adapter::Base
+  end
+end
+```
+
+You'll notice that the name it registers is the underscored namespace and class.
+
+Under the covers, when the `ActiveModelSerializers::Adapter::Base` is subclassed, it registers
+the subclass as `register("example/useful_adapter", Example::UsefulAdapter)`
+
+2) Any class can be registered as an adapter by calling `register` directly on the
+`ActiveModelSerializers::Adapter` class. e.g., the below registers `MyAdapter` as
+`:special_adapter`.
+
+```ruby
+class MyAdapter; end
+ActiveModelSerializers::Adapter.register(:special_adapter, MyAdapter)
+```
+
+### Looking up an adapter
+
+| Method | Return value |
+| :------------ |:---------------|
+| `ActiveModelSerializers::Adapter.adapter_map` | A Hash of all known adapters `{ adapter_name => adapter_class }` |
+| `ActiveModelSerializers::Adapter.adapters` | A (sorted) Array of all known `adapter_names` |
+| `ActiveModelSerializers::Adapter.lookup(name_or_klass)` |  The `adapter_class`, else raises an `ActiveModelSerializers::Adapter::UnknownAdapter` error |
+| `ActiveModelSerializers::Adapter.adapter_class(adapter)` | Delegates to `ActiveModelSerializers::Adapter.lookup(adapter)` |
+| `ActiveModelSerializers::Adapter.configured_adapter` | A convenience method for `ActiveModelSerializers::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_serializers/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,100 @@
+[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` (default)
+- `:json`
+- `:json_api`
+
+##### serializer_lookup_enabled
+
+Enable automatic serializer lookup.
+
+Possible values:
+
+- `true` (default)
+- `false`
+
+When `false`, serializers must be explicitly specified.
+
+##### key_transform
+
+The [key transform](key_transforms.md) to use.
+
+
+| Option | Result |
+|----|----|
+| `:camel` | ExampleKey |
+| `:camel_lower` | exampleKey |
+| `:dash` | example-key |
+| `:unaltered` | the original, unaltered key |
+| `:underscore` | example_key |
+| `nil` | use the adapter default |
+
+Each adapter has a default key transform configured:
+
+| Adapter | Default Key Transform |
+|----|----|
+| `Json` | `:unaltered` |
+| `JsonApi` | `:dash` |
+
+`config.key_transform` is a global override of the adapter default. Adapters
+still prefer the render option `:key_transform` over this setting.
+
+
+## JSON API
+
+
+##### jsonapi_resource_type
+
+Sets whether the [type](http://jsonapi.org/format/#document-resource-identifier-objects)
+of the resource should be `singularized` or `pluralized` when it is not
+[explicitly specified by the serializer](https://github.com/rails-api/active_model_serializers/blob/master/docs/general/serializers.md#type)
+
+Possible values:
+
+- `:singular`
+- `:plural` (default)
+
+##### jsonapi_include_toplevel_object
+
+Include a [top level jsonapi member](http://jsonapi.org/format/#document-jsonapi-object)
+in the response document.
+
+Possible values:
+
+- `true`
+- `false` (default)
+
+##### jsonapi_version
+
+The latest version of the spec to which the API conforms.
+
+Default: `'1.0'`.
+
+*Used when `jsonapi_include_toplevel_object` is `true`*
+
+##### jsonapi_toplevel_meta
+
+Optional top-level metadata. Not included if empty.
+
+Default: `{}`.
+
+*Used when `jsonapi_include_toplevel_object` is `true`*
+
+
+## Hooks
+
+To run a hook when ActiveModelSerializers is loaded, use
+`ActiveSupport.on_load(:action_controller) do end`

data/docs/general/deserialization.md

@@ -0,0 +1,100 @@
+[Back to Guides](../README.md)
+
+# Deserialization
+
+This is currently an *experimental* feature. The interface may change.
+
+## JSON API
+
+The `ActiveModelSerializers::Deserialization` defines two methods (namely `jsonapi_parse` and `jsonapi_parse!`), which take a `Hash` or an instance of `ActionController::Parameters` representing a JSON API payload, and return a hash that can directly be used to create/update models. The bang version throws an `InvalidDocument` exception when parsing fails, whereas the "safe" version simply returns an empty hash.
+
+- Parameters
+  - document: `Hash` or `ActionController::Parameters` instance
+  - options:
+    - only: `Array` of whitelisted fields
+    - except: `Array` of blacklisted fields
+    - keys: `Hash` of fields the name of which needs to be modified (e.g. `{ :author => :user, :date => :created_at }`)
+
+Examples:
+
+```ruby
+class PostsController < ActionController::Base
+  def create
+    Post.create(create_params)
+  end
+
+  def create_params
+    ActiveModelSerializers::Deserialization.jsonapi_parse(params, only: [:title, :content, :author])
+  end
+end
+```
+
+
+
+Given a JSON API document,
+
+```
+document = {
+  'data' => {
+    'id' => 1,
+    'type' => 'post',
+    'attributes' => {
+      'title' => 'Title 1',
+      'date' => '2015-12-20'
+    },
+    'associations' => {
+      'author' => {
+        'data' => {
+          'type' => 'user',
+          'id' => '2'
+        }
+      },
+      'second_author' => {
+        'data' => nil
+      },
+      'comments' => {
+        'data' => [{
+          'type' => 'comment',
+          'id' => '3'
+        },{
+          'type' => 'comment',
+          'id' => '4'
+        }]
+      }
+    }
+  }
+}
+```
+
+The entire document can be parsed without specifying any options:
+```ruby
+ActiveModelSerializers::Deserialization.jsonapi_parse(document)
+#=>
+# {
+#   title: 'Title 1',
+#   date: '2015-12-20',
+#   author_id: 2,
+#   second_author_id: nil
+#   comment_ids: [3, 4]
+# }
+```
+
+and fields, relationships, and polymorphic relationships can be specified via the options:
+
+```ruby
+ActiveModelSerializers::Deserialization
+  .jsonapi_parse(document, only: [:title, :date, :author],
+                           keys: { date: :published_at },
+                           polymorphic: [:author])
+#=>
+# {
+#   title: 'Title 1',
+#   published_at: '2015-12-20',
+#   author_id: '2',
+#   author_type: 'user'
+# }
+```
+
+## Attributes/Json
+
+There is currently no deserialization for those adapters.

data/docs/general/getting_started.md

@@ -0,0 +1,133 @@
+[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`).
+
+### Extending a Base `ApplicationSerializer`
+
+By default, new serializers descend from `ActiveModel::Serializer`. However, if
+you wish to share behavior across your serializers, you can create an
+`ApplicationSerializer` at `app/serializers/application_serializer.rb`:
+
+```ruby
+class ApplicationSerializer < ActiveModel::Serializer
+end
+```
+
+Then any newly-generated serializers will automatically descend from
+`ApplicationSerializer`.
+
+```
+$ rails g serializer post
+```
+
+Now generates:
+
+```ruby
+class PostSerializer < ApplicationSerializer
+  attributes :id
+end
+````
+
+## 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
+```
+
+If you wish to use Rails url helpers for link generation, e.g., `link(:resources) { resources_url }`, ensure your application sets
+`Rails.application.routes.default_url_options`.
+
+```ruby
+Rails.application.routes.default_url_options = {
+    host: 'example.com'
+}
+```

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: ActiveModelSerializers::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/key_transforms.md

@@ -0,0 +1,40 @@
+[Back to Guides](../README.md)
+
+# Key Transforms
+
+Key Transforms modify the casing of keys and keys referenced in values in
+serialized responses.
+
+Provided key transforms:
+
+| Option | Result |
+|----|----|
+| `:camel` | ExampleKey |
+| `:camel_lower` | exampleKey |
+| `:dash` | example-key |
+| `:unaltered` | the original, unaltered key |
+| `:underscore` | example_key |
+| `nil` | use the adapter default |
+
+Key translation precedence is as follows:
+
+##### Adapter option
+
+`key_transform` is provided as an option via render.
+
+```render json: posts, each_serializer: PostSerializer, key_transform: :camel_lower```
+
+##### Configuration option
+
+`key_transform` is set in `ActiveModelSerializers.config.key_transform`.
+
+```ActiveModelSerializers.config.key_transform = :camel_lower```
+
+##### Adapter default
+
+Each adapter has a default transform configured:
+
+| Adapter | Default Key Transform |
+|----|----|
+| `Json` | `:unaltered` |
+| `JsonApi` | `:dash` |