diff --git a/.gitignore b/.gitignore
index cd2acb28..2bc7e6c8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,3 +22,4 @@ tmp
 .ruby-version
 .ruby-gemset
 vendor/bundle
+tags
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 78f48842..042a35b0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -66,6 +66,8 @@ Features:
     CollectionSerializer for clarity, add ActiveModelSerializers.config.collection_serializer (@bf4)
 - [#1295](https://github.com/rails-api/active_model_serializers/pull/1295) Add config `serializer_lookup_enabled` that,
   when disabled, requires serializers to explicitly specified. (@trek)
+- [#1247](https://github.com/rails-api/active_model_serializers/pull/1247) Add top-level links (@beauby)
+  * Add more tests and docs for top-level links (@leandrocp)
 
 Fixes:
 
diff --git a/docs/README.md b/docs/README.md
index 7f0a8ac0..cf658fb6 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -23,6 +23,7 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 - [How to add pagination links](howto/add_pagination_links.md)
 - [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md)
 - [Testing ActiveModelSerializers](howto/test.md)
+- [How to add top-level links](howto/add_top_level_links.md) (```JSON-API``` only)
 
 ## Integrations
 
diff --git a/docs/howto/add_top_level_links.md b/docs/howto/add_top_level_links.md
new file mode 100644
index 00000000..bcb0ea18
--- /dev/null
+++ b/docs/howto/add_top_level_links.md
@@ -0,0 +1,40 @@
+# How to add top-level links
+
+JsonApi supports a [links object](http://jsonapi.org/format/#document-links) to be specified at top-level, that you can specify in the `render`:
+
+```ruby
+  links_object = {
+    href: "http://example.com/api/posts",
+    meta: {
+      count: 10
+    }
+  }
+  render json: @posts, links: links_object
+```
+
+That's the result:
+
+```json
+{
+  "data": [
+    {
+      "type": "posts",
+      "id": "1",
+      "attributes": {
+        "title": "JSON API is awesome!",
+        "body": "You should be using JSON API",
+        "created": "2015-05-22T14:56:29.000Z",
+        "updated": "2015-05-22T14:56:28.000Z"
+      }
+    }
+  ],
+  "links": {
+    "href": "http://example.com/api/posts",
+    "meta": {
+      "count": 10
+    }
+  }
+}
+```
+
+This feature is specific to JsonApi, so you have to use the use the [JsonApi Adapter](https://github.com/rails-api/active_model_serializers/blob/master/docs/general/adapters.md#jsonapi)
diff --git a/test/action_controller/serialization_test.rb b/test/action_controller/serialization_test.rb
index d2fe3959..7e6ea6cc 100644
--- a/test/action_controller/serialization_test.rb
+++ b/test/action_controller/serialization_test.rb
@@ -45,6 +45,16 @@ module ActionController
           render json: @profiles, meta: { total: 10 }
         end
 
+        def render_array_using_implicit_serializer_and_links
+          with_adapter ActiveModel::Serializer::Adapter::JsonApi do
+            @profiles = [
+              Profile.new(name: 'Name 1', description: 'Description 1', comments: 'Comments 1')
+            ]
+
+            render json: @profiles, links: { self: 'http://example.com/api/profiles/1' }
+          end
+        end
+
         def render_object_with_cache_enabled
           @comment = Comment.new(id: 1, body: 'ZOMG A COMMENT')
           @author  = Author.new(id: 1, name: 'Joao Moura.')
@@ -254,6 +264,29 @@ module ActionController
         assert_equal expected.to_json, @response.body
       end
 
+      def test_render_array_using_implicit_serializer_and_links
+        get :render_array_using_implicit_serializer_and_links
+
+        expected = {
+          data: [
+            {
+              id: assigns(:profiles).first.id.to_s,
+              type: 'profiles',
+              attributes: {
+                name: 'Name 1',
+                description: 'Description 1'
+              }
+            }
+          ],
+          links: {
+            self: 'http://example.com/api/profiles/1'
+          }
+        }
+
+        assert_equal 'application/json', @response.content_type
+        assert_equal expected.to_json, @response.body
+      end
+
       def test_render_with_cache_enable
         expected = {
           id: 1,
diff --git a/test/adapter/json_api/links_test.rb b/test/adapter/json_api/links_test.rb
index 0e7d5e32..5b9b872c 100644
--- a/test/adapter/json_api/links_test.rb
+++ b/test/adapter/json_api/links_test.rb
@@ -59,6 +59,15 @@ module ActiveModel
             assert_equal(expected, hash[:links])
           end
 
+          def test_nil_toplevel_links
+            hash = ActiveModel::SerializableResource.new(
+              @post,
+              adapter: :json_api,
+              links: nil
+            ).serializable_hash
+            assert_equal(nil, hash[:links])
+          end
+
           def test_resource_links
             hash = serializable(@author, adapter: :json_api).serializable_hash
             expected = {