active_model_serializers/docs/general/deserialization.md

Back to Guides

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:

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:

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:

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.