active_model_serializers 0.10.6 → 0.10.13

data/docs/general/adapters.md

@@ -1,263 +0,0 @@
-[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 json response is always rendered with a root key.
-
-The root key can be overridden by:
-* passing the `root` option in the render call. See details in the [Rendering Guides](rendering.md#overriding-the-root-key).
-* setting the `type` of the serializer. See details in the [Serializers Guide](serializers.md#type).
-
-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
-    }
-  }
-}
-```
-
-### Include option
-
-Which [serializer associations](https://github.com/rails-api/active_model_serializers/blob/master/docs/general/serializers.md#associations) are rendered can be specified using the `include` option. The option usage is consistent with [the include option in the JSON API spec](http://jsonapi.org/format/#fetching-includes), and is available in all adapters.
-
-Example of the usage:
-```ruby
-  render json: @posts, include: ['author', 'comments', 'comments.author']
-  # or
-  render json: @posts, include: 'author,comments,comments.author'
-```
-
-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.
-
-An empty string or an empty array will prevent rendering of any associations.
-
-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 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.**'
-```
-
-**Note:** Wildcards are ActiveModelSerializers-specific, they are not part of the JSON API spec.
-
-The default include for the JSON API adapter is no associations. The default for the JSON and Attributes adapters is all associations.
-
-For the JSON API adapter associated resources will be gathered in the `"included"` member. For the JSON and Attributes
-adapters associated resources will be rendered among the other attributes.
-
-Only for the JSON API adapter you can specify, which attributes of associated resources will be rendered. This feature
-is called [sparse fieldset](http://jsonapi.org/format/#fetching-sparse-fieldsets):
-
-```ruby
-  render json: @posts, include: 'comments', fields: { comments: ['content', 'created_at'] }
-```
-
-##### 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

@@ -1,58 +0,0 @@
-[Back to Guides](../README.md)
-
-# Caching
-
-## Warning
-
-There is currently a problem with caching in AMS [Caching doesn't improve performance](https://github.com/rails-api/active_model_serializers/issues/1586). Adding caching _may_ slow down your application, rather than speeding it up. We suggest you benchmark any caching you implement before using in a production enviroment
-
-___
-
-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 below:
-
-```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

@@ -1,169 +0,0 @@
-[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 |
-|----|----|
-| `Attributes` | `:unaltered` |
-| `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.
-
-*NOTE: Key transforms can be expensive operations. If key transforms are unnecessary for the
-application, setting `config.key_transform` to `:unaltered` will provide a performance boost.*
-
-##### default_includes
-What relationships to serialize by default.  Default: `'*'`, which includes one level of related
-objects. See [includes](adapters.md#included) for more info.
-
-
-##### serializer_lookup_chain
-
-Configures how serializers are searched for. By default, the lookup chain is
-
-```ruby
-ActiveModelSerializers::LookupChain::DEFAULT
-```
-
-which is shorthand for
-
-```ruby
-[
-  ActiveModelSerializers::LookupChain::BY_PARENT_SERIALIZER,
-  ActiveModelSerializers::LookupChain::BY_NAMESPACE,
-  ActiveModelSerializers::LookupChain::BY_RESOURCE_NAMESPACE,
-  ActiveModelSerializers::LookupChain::BY_RESOURCE
-]
-```
-
-Each of the array entries represent a proc. A serializer lookup proc will be yielded 3 arguments. `resource_class`, `serializer_class`, and `namespace`.
-
-Note that:
- - `resource_class` is the class of the resource being rendered
- - by default `serializer_class` is `ActiveModel::Serializer`
-   - for association lookup it's the "parent" serializer
- - `namespace` correspond to either the controller namespace or the [optionally] specified [namespace render option](./rendering.md#namespace)
-
-An example config could be:
-
-```ruby
-ActiveModelSerializers.config.serializer_lookup_chain = [
-  lambda do |resource_class, serializer_class, namespace|
-    "API::#{namespace}::#{resource_class}"
-  end
-]
-```
-
-If you simply want to add to the existing lookup_chain. Use `unshift`.
-
-```ruby
-ActiveModelSerializers.config.serializer_lookup_chain.unshift(
-  lambda do |resource_class, serializer_class, namespace|
-    # ...
-  end
-)
-```
-
-See [lookup_chain.rb](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/lookup_chain.rb) for further explanations and examples.
-
-## 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_namespace_separator
-
-Sets separator string for namespaced models to render `type` attribute.
-
-
-| Separator | Example: Admin::User |
-|----|----|
-| `'-'` (default) | 'admin-users'
-| `'--'` (recommended) | 'admin--users'
-
-See [Recommendation for dasherizing (kebab-case-ing) namespaced object, such as `Admin::User`](https://github.com/json-api/json-api/issues/850)
-for more discussion.
-
-##### 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

@@ -1,100 +0,0 @@
-[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'
-    },
-    'relationships' => {
-      '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/fields.md

@@ -1,31 +0,0 @@
-[Back to Guides](../README.md)
-
-# Fields
-
-If for any reason, you need to restrict the fields returned, you should use `fields` option.
-
-For example, if you have a serializer like this
-
-```ruby
-class UserSerializer < ActiveModel::Serializer
-  attributes :access_token, :first_name, :last_name
-end
-```
-
-and in a specific controller, you want to return `access_token` only, `fields` will help you:
-
-```ruby
-class AnonymousController < ApplicationController
-  def create
-    render json: User.create(activation_state: 'anonymous'), fields: [:access_token], status: 201
-  end
-end
-```
-
-Note that this is only valid for the `json` and `attributes` adapter. For the `json_api` adapter, you would use
-
-```ruby
-render json: @user, fields: { users: [:access_token] }
-```
-
-Where `users` is the JSONAPI type.