Grammar fixing

Author: vasilakisfil

docs/howto/add_relationship_links.md

@@ -2,16 +2,17 @@
 
 # How to add relationship links
 
-AMS offers you many ways to add links in your JSON, depending on your needs.
+ActiveModelSerializers offers you many ways to add links in your JSON, depending on your needs.
+Usually the most common use case for links is supporting nested resources.
 
 The following examples are in Rails but the logic is the same for any framework
 used.
 
-The following examples preassume that you don't want to load any data for relationships (include param is empty),
+The following examples assume that you don't want to load any data for relationships (include param is empty),
 specifically the following Rails controller was used for those examples:
 
 ```ruby
-class Api::V1::UsersController
+class Api::V1::UsersController < ApplicationController
   def show
     render jsonapi: User.find(params[:id]),
       serializer: Api::V1::UserSerializer,
@@ -26,7 +27,7 @@ You can just define an attribute in the resource, named `links` and return the
 links you want there. An example:
 
 ```ruby
-class Api::V1::UserSerializer
+class Api::V1::UserSerializer < ActiveModel::Serializer
   attributes :id, :name, :links
 
   def links
@@ -56,21 +57,21 @@ This will resilt in (example is in jsonapi adapter):
 ```
 
 
-### Links as an property of the resource definiton
+### Links as a property of the resource definiton
 **This is only applicable to JSONAPI adapter**
 
 You can use the `links` helper method to define the links you need in the resource definition level. 
 
 ```ruby
-class Api::V1::UserSerializer
+class Api::V1::UserSerializer < ActiveModel::Serializer
   attributes :id, :name
 
-  link(:self) {api_v1_user_path(object.id)}
-  link(:microposts) {api_v1_microposts_path(user_id: object.id)}
+  link(:self) { api_v1_user_path(object.id) }
+  link(:microposts) { api_v1_microposts_path(user_id: object.id) }
 end
 ```
 
-This will resilt in (example is in jsonapi adapter): 
+This will resilt in (example is in jsonapi adapter):
 ```json
 {
     "data": {
@@ -91,17 +92,23 @@ This will resilt in (example is in jsonapi adapter):
 **This is only applicable to JSONAPI adapter**
 
 If you have a JSONAPI-strict client that you are working with (like `ember-data`)
-you need to struct the links inside the relationships. Here is how:
+you need to struct the links inside the relationships. Also the link to fetch the
+relationship data must be under the `related` attribute, whereas to manipulate the
+relationship (in case of many-to-many relationship) must be under the `self` attribute.
+
+You can find more info in the [spec](http://jsonapi.org/format/#document-resource-object-relationships).
+
+Here is how you can do this:
 
 ```ruby
-class Api::V1::UserSerializer
+class Api::V1::UserSerializer < ActiveModel::Serializer
   attributes :id, :name
 
   has_many :microposts, serializer: Api::V1::MicropostSerializer do
-    link(:microposts) {api_v1_microposts_path(user_id: object.id)}
+    link(:related) { api_v1_microposts_path(user_id: object.id) }
   end
 
-  #this is needed to avoid n+1, AMS core devs are working to remove this necessity
+  #this is needed to avoid n+1, gem core devs are working to remove this necessity
   #more on: https://github.com/rails-api/active_model_serializers/issues/1325
   def microposts
     object.microposts.loaded ? object.microposts : object.microposts.none
@@ -123,7 +130,7 @@ This will result in:
             "microposts": {
                 "data": [],
                 "links": {
-                    "microposts": "//example.com/blogs/relationships/posts"
+                  "related": "/api/v1/microposts?user_id=1"
                 }
             }
         }