From 8854a3a83a26facef50509c52623f5e68a126781 Mon Sep 17 00:00:00 2001
From: patch malone <46642059+patch-malone@users.noreply.github.com>
Date: Sun, 13 Jan 2019 07:13:47 +0000
Subject: [PATCH 1/2] Update the Rails getting started guide

---
 .../guides/getting_started/rails.html.md.erb  | 116 ++++++++++++++++--
 1 file changed, 107 insertions(+), 9 deletions(-)

diff --git a/source/guides/getting_started/rails.html.md.erb b/source/guides/getting_started/rails.html.md.erb
index 8b9d603..2830c8f 100644
--- a/source/guides/getting_started/rails.html.md.erb
+++ b/source/guides/getting_started/rails.html.md.erb
@@ -3,22 +3,50 @@ layout: guides
 ---
 # Getting started - Ruby on Rails
 
-Start by adding the following to your `Gemfile`:
+Start by adding the `jsonapi-rails` gem to your `Gemfile`:
 
 ```ruby
 gem 'jsonapi-rails'
 ```
 
-Then, once your [serializable resources](/guides/serialization) are defined, building
-a JSON API document from your business objects is straightforward: simply pass them
-to the `render` method.
+Then run `bundle install`.
 
-For a comprehensive list of renderer options, see
-[Renderer options](/guides/serialization/rendering.html).
+## Defining Serializable and Deserializable resources
 
-## Rendering resources
+Now define your serializable and deserializable resources.
+
+### Serializable resources
 
 ```ruby
+# app/serializers/post.rb
+class SerializablePost < JSONAPI::Serializable::Resource
+  type 'posts'
+
+  attributes :title, :content, :tag_ids, :created_at, :updated_at
+
+  belongs_to :author
+  has_many :comments
+  has_many :users
+end
+```
+
+### Deserializable resources
+
+```ruby
+# app/deserializers/post.rb
+class DeserializablePost < JSONAPI::Deserializable::Resource
+  attributes :title, :content, :tag_ids
+end
+```
+
+## Rendering resources from controllers
+
+Once your [serializable resources](/guides/serialization) are defined, building
+a JSON API document from your business objects is straightforward. `jsonapi-rails` ties in
+to the standard Rails [`render`](https://guides.rubyonrails.org/layouts_and_rendering.html) method.
+
+```ruby
+# app/controllers/posts_controller.rb
 class PostsController < ActionController::Base
   # ...
 
@@ -32,7 +60,10 @@ class PostsController < ActionController::Base
 end
 ```
 
-## Rendering relationships
+For a comprehensive list of renderer options, see
+[Renderer options](/guides/serialization/rendering.html).
+
+### Rendering relationships
 
 ```ruby
 class PostsController < ActionController::Base
@@ -50,7 +81,7 @@ class PostsController < ActionController::Base
 end
 ```
 
-## Rendering errors
+### Rendering errors
 
 ```ruby
 class PostsController < ActionController::Base
@@ -70,6 +101,73 @@ class PostsController < ActionController::Base
 end
 ```
 
+### A full controller example
+```ruby
+# app/controllers/posts_controller.rb
+class PostsController < ActionController::Base
+  deserializable_resource :post, only: [:create, :update]
+
+  def index
+    render jsonapi: Posts.all,
+           include: [:author, comments: [:author]],
+           fields: { users: [:name, :email],
+                     posts: [:title, :content] }
+  end
+
+  def show
+    render jsonapi: post, rendering_options
+  end
+
+  def create
+    post = Post.create(create_params)
+
+    if post.save
+      render jsonapi: post, rendering_options.merge(status: :created)
+    else
+      render jsonapi_errors: post.errors
+    end
+  end
+
+  def update
+    post = Post.find(params[:id])
+    post.assign_attributes(update_params)
+
+    if post.save
+      render jsonapi: post, rendering_options
+    else
+      render jsonapi_errors: post.errors
+    end
+  end
+
+  def destroy
+    post = Post.find(params[:id])
+
+    if post.destroy
+      head :no_content
+    else
+      head :conflict
+    end
+  end
+
+  private
+
+  def create_params
+    params.require(:post).permit(:title, :content, :tag_ids)
+  end
+
+  def update_params
+    params.require(:post).permit(:title, :content, :tag_ids)
+  end
+
+  def rendering_options
+    {
+      include: [:author, comments: [:author]],
+      fields: { users: [:name, :email] }
+    }
+  end
+end
+```
+
 ## Serializable Class Lookup
 
 By default, for an instance of `Post`, the corresponding serializable resource class

From 996316fac84832cf0a1ce6a19f54861c09709ae4 Mon Sep 17 00:00:00 2001
From: patch malone <46642059+patch-malone@users.noreply.github.com>
Date: Sun, 13 Jan 2019 07:17:29 +0000
Subject: [PATCH 2/2] Link to the getting started guides from the index page
 examples

---
 source/peeks/_hanami.md | 1 +
 source/peeks/_plain.md  | 2 ++
 source/peeks/_rails.md  | 2 ++
 3 files changed, 5 insertions(+)

diff --git a/source/peeks/_hanami.md b/source/peeks/_hanami.md
index e71979e..1b28efb 100644
--- a/source/peeks/_hanami.md
+++ b/source/peeks/_hanami.md
@@ -30,3 +30,4 @@ module API::Controllers::Posts
   end
 end
 ```
+Further instructions are in the [getting started guide for Hanami](guides/getting_started/hanami).
diff --git a/source/peeks/_plain.md b/source/peeks/_plain.md
index 77acab8..9ac729d 100644
--- a/source/peeks/_plain.md
+++ b/source/peeks/_plain.md
@@ -30,3 +30,5 @@ resource.to_h
 #      comments_types: ['comments', 'comments', 'comments']
 #    }
 ```
+
+Further instructions are in the [getting started guide for plain Ruby](guides/getting_started/plain_ruby).
diff --git a/source/peeks/_rails.md b/source/peeks/_rails.md
index 80dc420..4f4e89f 100644
--- a/source/peeks/_rails.md
+++ b/source/peeks/_rails.md
@@ -19,3 +19,5 @@ class PostsController < ApplicationController
   end
 end
 ```
+
+Further instructions are in the [getting started guide for Rails](guides/getting_started/rails).