Merge branch 'leandrocp-add-top-level-links'

Needs followup
- #1018 (comment)
- #1018 (comment)
- #1018 (comment)
- #1018 (comment)

Author: bf4

.gitignore

@@ -22,3 +22,4 @@ tmp
 .ruby-version
 .ruby-gemset
 vendor/bundle
+tags

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:
 

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
 

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)

test/action_controller/serialization_test.rb

@@ -45,6 +45,16 @@ def render_array_using_implicit_serializer_and_meta
           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 @@ def test_render_array_using_implicit_serializer_and_meta
         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,

test/adapter/json_api/links_test.rb

@@ -59,6 +59,15 @@ def test_toplevel_links
             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 = {