1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
[Back to Guides](../README.md)
# How to add relationship links
ActiveModelSerializers offers you many ways to add links in your JSON, depending on your needs.
The most common use case for links is supporting nested resources.
The following examples are without included relationship data (`include` param is empty),
specifically the following Rails controller was used for these examples:
```ruby
class Api::V1::UsersController < ApplicationController
def show
render jsonapi: User.find(params[:id]),
serializer: Api::V1::UserSerializer,
include: []
end
end
```
Bear in mind though that ActiveModelSerializers are [framework-agnostic](outside_controller_use.md), Rails is just a common example here.
### Links as an attribute of a resource
**This is applicable to JSON and Attributes adapters**
You can define an attribute in the resource, named `links`.
```ruby
class Api::V1::UserSerializer < ActiveModel::Serializer
include Rails.application.routes.url_helpers
attributes :id, :name
attribute :links do
id = object.id
{
self: api_v1_user_path(id),
microposts: api_v1_microposts_path(user_id: id)
}
end
end
```
Using the `JSON` adapter, this will result in:
```json
{
"user": {
"id": "1",
"name": "John",
"links": {
"self": "/api/v1/users/1",
"microposts": "/api/v1/microposts?user_id=1"
}
}
}
```
### Links as a property of the resource definiton
**This is only applicable to JSONAPI adapter**
You can use the `link` class method to define the links you need in the resource's primary data.
```ruby
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) }
end
```
Using the `JSONAPI` adapter, this will result in:
```json
{
"data": {
"id": "1",
"type": "users",
"attributes": {
"name": "Example User"
},
"links": {
"self": "/api/v1/users/1",
"microposts": "/api/v1/microposts?user_id=1"
}
}
}
```
### Links that follow the JSONAPI spec
**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 construct 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 < ActiveModel::Serializer
attributes :id, :name
has_many :microposts, serializer: Api::V1::MicropostSerializer do
link(:related) { api_v1_microposts_path(user_id: object.id) }
microposts = object.microposts
# The following code is needed to avoid n+1 queries.
# Core devs are working to remove this necessity.
# See: https://github.com/rails-api/active_model_serializers/issues/1325
microposts.loaded? ? microposts : microposts.none
end
end
```
This will result in:
```json
{
"data": {
"id": "1",
"type": "users",
"attributes": {
"name": "Example User"
},
"relationships": {
"microposts": {
"data": [],
"links": {
"related": "/api/v1/microposts?user_id=1"
}
}
}
}
}
```
|
