Skip to content

Commit 96ddc4c

Browse files
beaubybeauby
authored
Update docs. (#17)
1 parent 566c1fb commit 96ddc4c

9 files changed

Lines changed: 57 additions & 257 deletions

File tree

‎source/guides/deserialization/defining.html.md‎

Lines changed: 1 addition & 181 deletions
Original file line numberDiff line numberDiff line change
@@ -6,184 +6,4 @@ layout: guides
66
Custom deserializable resources are defined by subclassing
77
`JSONAPI::Deserializable::Resource` and using its DSL.
88

9-
Example:
10-
11-
```ruby
12-
class DeserializablePost < JSONAPI::Deserializable::Resource
13-
attribute :date do |attr|
14-
{ created_at: attr }
15-
end
16-
17-
relationship :author do |_rel, id, type|
18-
{ user_id: id,
19-
user_type: type }
20-
end
21-
22-
relationship :comments do |_rel, ids, _types|
23-
{ response_ids: ids }
24-
end
25-
end
26-
27-
# Will allow to build the following hash:
28-
# => {
29-
# type: 'posts',
30-
# id: '5',
31-
# created_at: '2016-11-18',
32-
# title: 'Hello JSON API',
33-
# user_id: '12',
34-
# user_type: 'users',
35-
# response_ids: ['54', '32', '72']
36-
# }
37-
```
38-
39-
The principle is simple: the payload elements for which a custom deserialization
40-
scheme was defined will use that, while other fields will be deserialized using
41-
the default deserialization scheme (which can itself be configured).
42-
43-
Note: If the targeted element does not exist in the payload, the corresponding
44-
fields are not defined.
45-
46-
## Type
47-
48-
The type of the primary data can be accessed via the `type` DSL method.
49-
50-
Example:
51-
52-
```ruby
53-
class DeserializablePost < JSONAPI::Deserializable::Post
54-
# ...
55-
type do |t|
56-
{ primary_type: t.capitalize }
57-
end
58-
end
59-
```
60-
61-
## Id
62-
63-
The id of the primary data can be accessed via the `id` DSL method.
64-
65-
Example:
66-
67-
```ruby
68-
class DeserializablePost < JSONAPI::Deserializable::Post
69-
# ...
70-
id do |i|
71-
{ primary_id: i.to_i }
72-
end
73-
end
74-
```
75-
76-
## Attributes
77-
78-
Attributes of the primary data can be accessed via the `attribute` DSL method.
79-
The `attribute` method takes a symbol representing the name of the targeted
80-
attribute in the input payload, and a block to define field(s) of the resulting
81-
hash.
82-
83-
Example:
84-
85-
```ruby
86-
class DeserializablePost < JSONAPI::Deserializable::Post
87-
# ...
88-
attribute :date do |d|
89-
{ created_at: d }
90-
end
91-
end
92-
```
93-
94-
## Relationships
95-
96-
Relationships of the primary data can be accessed via the `has_many` and
97-
`has_one` DSL methods.
98-
99-
### To-many relationships
100-
101-
The `has_many` DSL method takes a symbol representing the name of the targeted
102-
relationship in the input payload, and a block to define field(s) of the
103-
resulting hash. The block is called with three parameters: `relationship` (the
104-
whole relationship hash of the input payload), `ids` (an array of the ids of
105-
related resources), and `types` (an array of types of the related resources).
106-
107-
Example:
108-
109-
```ruby
110-
class DeserializablePost < JSONAPI::Deserializable::Post
111-
# ...
112-
has_many :comments do |rel, ids, types|
113-
{ comment_ids: ids,
114-
comment_types: types.map(&:capitalize),
115-
comment_meta: rel['meta'] }
116-
end
117-
end
118-
```
119-
120-
### To-one relationships
121-
122-
The `has_one` DSL method takes a symbol representing the name of the targeted
123-
relationship in the input payload, and a block to define field(s) of the
124-
resulting hash. The block is called with three parameters: `relationship` (the
125-
whole relationship hash of the input payload), `id` (the id of the related
126-
resource), and `type` (the type of the related resource).
127-
128-
Example:
129-
130-
```ruby
131-
class DeserializablePost < JSONAPI::Deserializable::Post
132-
# ...
133-
has_one :author do |rel, id, type|
134-
{ author_id: id,
135-
author_type: type.capitalize,
136-
author_meta: rel['meta'] }
137-
end
138-
end
139-
```
140-
141-
## Meta
142-
143-
Not available yet.
144-
145-
## Links
146-
147-
Not available yet.
148-
149-
## Configuration
150-
151-
The default deserialization scheme can be configure in the following way:
152-
153-
```ruby
154-
# Modifying the global default deserialization scheme
155-
JSONAPI::Deserializable::Resource.configure do |config|
156-
config.default_id = proc { |id| { id: id } }
157-
config.default_type = proc { |type| { type: type } }
158-
config.default_attribute = proc do |key, value|
159-
{ key => value }
160-
end
161-
config.default_has_one = proc do |key, rel, id, type|
162-
{ "#{key}_id}".to_sym => id, "#{key}_type".to_sym => type }
163-
end
164-
config.default_has_many = proc do |key, rel, ids, types|
165-
{ "#{key}_ids}".to_sym => ids, "#{key}_types".to_sym => types }
166-
end
167-
end
168-
169-
# Modifying the default deserialization scheme of a single deserializable
170-
# resource class
171-
172-
class DeserializablePost < JSONAPI::Deserializable::Resource
173-
# ...
174-
end
175-
176-
DeserializablePost.configure do |config|
177-
config.default_id = proc { |id| { id: id } }
178-
config.default_type = proc { |type| { type: type } }
179-
config.default_attribute = proc do |key, value|
180-
{ key => value }
181-
end
182-
config.default_has_one = proc do |key, rel, id, type|
183-
{ "#{key}_id".to_sym => id, "#{key}_type".to_sym => type }
184-
end
185-
config.default_has_many = proc do |key, rel, ids, types|
186-
{ "#{key}_ids".to_sym => ids, "#{key}_types".to_sym => types }
187-
end
188-
end
189-
```
9+
Documentation currently being rewritten.

‎source/guides/deserialization/deserializing.html.md‎

Lines changed: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -6,23 +6,7 @@ layout: guides
66
Deserializing an input payload is straightforward: simply call the
77
deserializable resource.
88

9-
Example (generic deserializable resource):
10-
11-
```ruby
12-
JSONAPI::Deserializable::Resource.call(json_hash)
13-
# => {
14-
# type: 'posts',
15-
# id: '5',
16-
# title: 'Hello JSON API',
17-
# date: '2016-11-18',
18-
# author_id: '12',
19-
# author_type: 'users',
20-
# comments_ids: ['54', '32', '72']
21-
# comments_types: ['comments', 'comments', 'comments']
22-
# }
23-
```
24-
25-
Example (custom deserializable resource):
9+
Example:
2610

2711
```ruby
2812
DeserializablePost.call(json_hash)
@@ -58,7 +42,7 @@ Example:
5842

5943
```ruby
6044
class PostsController < ApplicationController
61-
deserializable_resource :post, DeserializablePost, only: [:create, :update]
45+
deserializable_resource :post, class: DeserializablePost, only: [:create, :update]
6246

6347
# ...
6448

‎source/guides/deserialization/index.html.md‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,9 @@ layout: guides
33
---
44
# Deserialization
55

6-
Any resource payload can be deserialized into a standardized format using the
7-
`JSONAPI::Deserializable::Resource` class. In case you need more control over
8-
the generated hash (modifying some field names, or modifying the default
9-
deserialization scheme for attributes/relationships), you can define custom
10-
*deserializable resources*. Deserializable resources map the members of a
11-
payload to fields of a hash. They are defined via an intuitive DSL.
6+
Deserializable resources map the members of a payload to fields of a hash.
7+
They are defined by subclassing `JSONAPI::Deserializable::Resource` via an
8+
intuitive DSL.
129

1310
Once your deserializable resources are defined, you can call them on hashes
1411
representing input JSON API payloads, and obtain a hash that you can use

‎source/guides/index.html.md‎

Lines changed: 2 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ validation of JSON API documents,
1515
+ [jsonapi-renderer](https://github.com/jsonapi-rb/renderer) for low-level
1616
rendering of JSON API documents,
1717
+ [jsonapi-serializable](https://github.com/jsonapi-rb/serializable) for
18-
building serializable resource classes from your business object,
18+
building serializable resource classes from your business object -- those are
19+
usually referred to as "serializers" in other libs,
1920
+ [jsonapi-deserializable](https://github.com/jsonapi-rb/deserializable) for
2021
building deserializable resource classes that transform an incoming JSON API
2122
payload into a custom hash,
@@ -29,18 +30,6 @@ generators,
2930
[Hanami](http://hanamirb.org) with Hanami::Controller::Action integration and
3031
(soon) generators.
3132

32-
## Overview
33-
34-
jsonapi-rb works by defining *mappers* (or *presenters*) to translate your
35-
business objects to JSON API documents, and JSON API payloads to custom hashes.
36-
37-
The *deserializable resources* (the mappers from JSON API payloads to custom
38-
hashes) can be used directly, as the input payload will only contain flat data.
39-
40-
The *serializable resources*, on the other hand, need to be coordinated through
41-
a *renderer* (as JSON API response document usually contain a graph of resources
42-
related to each other).
43-
4433
## Guides
4534

4635
These guides should get you up to speed with using jsonapi-rb. If you have more

‎source/guides/serialization/defining.html.md‎

Lines changed: 22 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ class SerializablePost < JSONAPI::Serializable::Resource
2020

2121
belongs_to :author
2222

23-
has_many :comments, class: 'V2::SerializableComment' do
23+
has_many :comments do
2424
data do
2525
@object.published_comments
2626
end
@@ -45,25 +45,32 @@ end
4545
```
4646

4747
The principle is simple: you declare elements of the JSON API resource and
48-
specify their values.
48+
optionally specify their values.
4949

5050
The underying object is available throughout the DSL as the instance variable
5151
`@object`. (In general, all *exposures* - that is, variables made available in
52-
the `render` call - are available throughout the DSL as instance variables.)
52+
the `render` call via the `expose` option - are available throughout the DSL
53+
as instance variables.)
5354

5455
## Type
5556

5657
The `type` property is declared via the DSL method of the same name, and takes
57-
a symbol or a string.
58+
a symbol, a string, or a block.
5859

59-
Example:
60+
Examples:
6061

6162
```ruby
6263
class SerializablePost < JSONAPI::Serializable::Resource
6364
type 'posts'
6465
end
6566
```
6667

68+
```ruby
69+
class SerializablePost < JSONAPI::Serializable::Resource
70+
type { @object.type }
71+
end
72+
```
73+
6774
## Id
6875

6976
The `id` property is declared via the DSL method of the same name, and takes a
@@ -92,6 +99,11 @@ Example:
9299
class SerializablePost < JSONAPI::Serializable::Resource
93100
# ...
94101
attribute :date # This will have value @object.date
102+
```
103+
104+
```ruby
105+
class SerializablePost < JSONAPI::Serializable::Resource
106+
# ...
95107
attribute :date do
96108
@object.created_at
97109
end
@@ -111,13 +123,13 @@ class SerializablePost < JSONAPI::Serializable::Resource
111123
meta foo: 'bar'
112124
end
113125
```
114-
or dynamically in a block:
126+
or dynamically in a block (in case it needs access to the exposures):
115127

116128
```ruby
117129
class SerializablePost < JSONAPI::Serializable::Resource
118130
# ...
119131
meta do
120-
{ foo: 'bar' }
132+
{ foo: @object.foo }
121133
end
122134
end
123135
```
@@ -237,20 +249,11 @@ class SerializablePost < JSONAPI::Serializable::Resource
237249
end
238250
```
239251

252+
Note that while this usage is supported, it is actually recommended to set a
253+
global explicit mapping at the renderer level.
254+
240255
### Linkage data overriding
241256

242257
Note: it is also possible to manually override the linkage data for a
243258
relationship (which can be useful to add linkage-level meta information) via the
244259
`linkage` DSL method.
245-
246-
## Rails generators
247-
248-
The jsonapi-rails gem comes with generators for serializable resource classes.
249-
It infers the attributes and relationships from your model definition.
250-
251-
Usage:
252-
253-
```
254-
$ bundle exec rails generate jsonapi:serializable Post
255-
> created app/serializable/serializable_post.rb
256-
```

‎source/guides/serialization/index.html.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,10 @@ layout: guides
55

66
In order to build JSON API documents from your data, you need to define some
77
*serializable resources*. Serializable resources encapsulate your domain objects
8-
(which can be any kind of objects) and present them in a suitable way for JSON
9-
API serialization. They are defined via an intuitive yet extensive DSL.
8+
(which can be any kind of objects -- `ActiveRecord`s, POROs, etc.) and present
9+
them in a suitable way for JSON API serialization. They are defined via an
10+
intuitive yet extensive DSL. In other libraries, serializable resources are
11+
usually called "serializers".
1012

1113
Once your serializable resources are defined, you can pass your business objects
1214
to the *renderer*, that will build the appropriate serializable resources, and

0 commit comments

Comments
 (0)