From 3aeb34b0b85689798e079a5148b75ca9a3b50ea8 Mon Sep 17 00:00:00 2001
From: Lucas Hosseini <lucas.hosseini@gmail.com>
Date: Wed, 13 Jan 2016 08:40:38 +0100
Subject: [PATCH 1/2] Add docs for deserialization.

---
 docs/README.md                  |  1 +
 docs/general/deserialization.md | 34 +++++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+)
 create mode 100644 docs/general/deserialization.md

diff --git a/docs/README.md b/docs/README.md
index a20c086e..ced76cbd 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -13,6 +13,7 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 - [Rendering](general/rendering.md)
 - [Caching](general/caching.md)
 - [Logging](general/logging.md)
+- [Deserialization](general/deserialization.md)
 - [Instrumentation](general/instrumentation.md)
 - [JSON API Schema](jsonapi/schema.md)
 - [ARCHITECTURE](ARCHITECTURE.md)
diff --git a/docs/general/deserialization.md b/docs/general/deserialization.md
new file mode 100644
index 00000000..29bb29f6
--- /dev/null
+++ b/docs/general/deserialization.md
@@ -0,0 +1,34 @@
+[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 }`)
+
+Example:
+
+```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
+```
+
+## Attributes/Json
+
+There is currently no deserialization for those adapters.

From 586ff09cc5a07005e8257b82307ff2ad4c05db2f Mon Sep 17 00:00:00 2001
From: "L. Preston Sego III" <LPSego3+dev@gmail.com>
Date: Thu, 17 Mar 2016 07:58:51 -0400
Subject: [PATCH 2/2] Added more detailed examples to deserialization.md from
 json_api/deserialization.rb

---
 docs/general/deserialization.md | 68 ++++++++++++++++++++++++++++++++-
 1 file changed, 67 insertions(+), 1 deletion(-)

diff --git a/docs/general/deserialization.md b/docs/general/deserialization.md
index 29bb29f6..56dda833 100644
--- a/docs/general/deserialization.md
+++ b/docs/general/deserialization.md
@@ -15,7 +15,7 @@ The `ActiveModelSerializers::Deserialization` defines two methods (namely `jsona
     - except: `Array` of blacklisted fields
     - keys: `Hash` of fields the name of which needs to be modified (e.g. `{ :author => :user, :date => :created_at }`)
 
-Example:
+Examples:
 
 ```ruby
 class PostsController < ActionController::Base
@@ -29,6 +29,72 @@ class PostsController < ActionController::Base
 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.