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] 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.