Skip to content

Commit f4c003f

Browse files
beaubybeauby
authored
Update docs for new release. (#23)
1 parent dfcb8c1 commit f4c003f

10 files changed

Lines changed: 212 additions & 144 deletions

File tree

‎source/guides/getting_started/hanami.html.md.erb‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,37 @@ module Foo
6464
end
6565
```
6666

67+
5. Extend your actions to use jsonapi-rb:
68+
69+
When using jsonapi-rb with Hanami (via the jsonapi-hanami gem), enabling of
70+
jsonapi-rb features is opt-in, and is done by including
71+
`JSONAPI::Hanami::Action` in your actions.
72+
Rendering is done by setting options directly on the controller action instance.
73+
The primary data is set via the `self.data` setter.
74+
75+
Example:
76+
77+
```ruby
78+
module API::Controllers::Posts
79+
class Create
80+
include API::Action
81+
include JSONAPI::Hanami::Action
82+
83+
expose :url_helpers
84+
85+
def call(params)
86+
# ...
87+
@url_helpers = routes # Will be available inside serializable resources.
88+
89+
self.data = posts
90+
self.include = [:author, comments: [:author]]
91+
self.fields = { users: [:name, :email],
92+
posts: [:title, :content] }
93+
end
94+
end
95+
end
96+
```
97+
6798
## Examples
6899

69100
<%= partial 'peeks/hanami' %>

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
layout: guides
3+
---
4+
# Getting started
5+
6+
jsonapi-rb works by defining *serializable resources* for your business objects,
7+
which describe how to serialize a model of a given type in a given serialization
8+
context.
9+
10+
The *renderer* then builds a JSON API document from your business objects.
11+
In order to do so, it needs to find for each type of model the corresponding
12+
serializable resource class, instantiate it, and then combine all the JSON API
13+
representations of isolated resources.
14+
15+
Some context can be forwarded to the serializable resources: the *exposures*,
16+
specified when calling the renderer, are available within the serializable
17+
resource as instance variables.
18+
19+
- [Plain Ruby](/guides/getting_started/plain_ruby.html)
20+
- [Ruby on Rails](/guides/getting_started/rails.html)
21+
- [Hanami](/guides/getting_started/hanami.html)
22+
- [Sinatra](/guides/getting_started/sinatra.html)

‎source/guides/getting_started/plain_ruby.html.md.erb‎

Lines changed: 42 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,47 @@ layout: guides
33
---
44
# Getting started - Plain ruby
55

6-
Soon
6+
Once your [serializable resources](/guides/serialization) are defined, building
7+
a JSON API document from your business objects is straightforward.
78

8-
## Examples
9+
When using jsonapi-rb in plain ruby (or from within a framework outside of a
10+
controller), building documents is done by calling the `render` method of a
11+
`JSONAPI::Serializable::Renderer` instance.
912

10-
<%= partial 'peeks/plain' %>
13+
For a comprehensive list of renderer options, see
14+
[Renderer options](/guides/serialization/rendering.html).
15+
16+
## Rendering resources
17+
18+
```ruby
19+
renderer = JSONAPI::Serializable::Renderer.new
20+
21+
renderer.render(posts,
22+
class: { Post: SerializablePost, User: SerializableUser,
23+
Comment: SerializableComment },
24+
include: [:author, comments: [:author]],
25+
fields: { users: [:name, :email],
26+
posts: [:title, :content] })
27+
```
28+
29+
## Rendering relationships
30+
31+
```ruby
32+
renderer = JSONAPI::Serializable::Renderer.new
33+
34+
renderer.render(posts, relationship: :comments
35+
class: { Post: SerializablePost, User: SerializableUser,
36+
Comment: SerializableComment },
37+
include: [comments: [:author]],
38+
fields: { users: [:name, :email],
39+
posts: [:title, :content] })
40+
```
41+
42+
## Rendering errors
43+
44+
```ruby
45+
renderer = JSONAPI::Serializable::Renderer.new
46+
47+
renderer.render_errors(errors,
48+
class: { Hash: SerializableErrorHash })
49+
```

‎source/guides/getting_started/rails.html.md.erb‎

Lines changed: 95 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,100 @@ layout: guides
33
---
44
# Getting started - Ruby on Rails
55

6-
Soon
6+
Start by adding the following to your `Gemfile`:
77

8-
## Examples
8+
```ruby
9+
gem 'jsonapi-rails'
10+
```
911

10-
<%= partial 'peeks/rails' %>
12+
Then, once your [serializable resources](/guides/serialization) are defined, building
13+
a JSON API document from your business objects is straightforward: simply pass them
14+
to the `render` method.
15+
16+
For a comprehensive list of renderer options, see
17+
[Renderer options](/guides/serialization/rendering.html).
18+
19+
## Rendering resources
20+
21+
```ruby
22+
class PostsController < ActionController::Base
23+
# ...
24+
25+
def index
26+
render jsonapi: Posts.all, include: [:author, comments: [:author]],
27+
fields: { users: [:name, :email],
28+
posts: [:title, :content] }
29+
end
30+
31+
# ...
32+
end
33+
```
34+
35+
## Rendering relationships
36+
37+
```ruby
38+
class PostsController < ActionController::Base
39+
# ...
40+
41+
def comments_relationship
42+
post = Post.find(id: params[:id])
43+
render jsonapi: post, relationship: :comments,
44+
include: [comments: [:author]],
45+
fields: { users: [:name, :email],
46+
posts: [:title, :content] }
47+
end
48+
49+
# ...
50+
end
51+
```
52+
53+
## Rendering errors
54+
55+
```ruby
56+
class PostsController < ActionController::Base
57+
# ...
58+
59+
def create
60+
post = Post.new(params[:post])
61+
62+
if post.save
63+
render jsonapi: post
64+
else
65+
render jsonapi_errors: post.errors
66+
end
67+
end
68+
69+
# ...
70+
end
71+
```
72+
73+
## Configuration
74+
75+
### Application-wide settings
76+
77+
You can customize default behaviors in an initializer (`$ rails generate jsonapi:initializer`).
78+
79+
### Controller-wide settings
80+
81+
It is also possible to override application-wide settings at controller level. Simply define
82+
one of the available hooks:
83+
`jsonapi_class`, `jsonapi_errors_class`,`jsonapi_object`, `jsonapi_include`,
84+
`jsonapi_fields`, `jsonapi_expose`, `jsonapi_pagination`.
85+
86+
### Action-wide settings
87+
88+
It is always possible to override the application/controller-wide settings at action level
89+
by providing the relevant [renderer options](/guides/serialization/rendering.html).
90+
91+
### Serializable class lookup
92+
93+
By default, for an instance of `Article`, the corresponding serializable resource class
94+
will be guessed as `SerializableArticle`.
95+
96+
This behavior is customizable by overriding the `jsonapi_class` setting (or by supplying
97+
a `class` renderer option). Either set it to an explicit hash, or a hash with a dynamic
98+
default value for inferrence.
99+
100+
### Pagination
101+
102+
TODO

‎source/guides/index.html.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,5 +35,6 @@ generators,
3535
These guides should get you up to speed with using jsonapi-rb. If you have more
3636
questions, feel free to drop by on [Gitter](http://gitter.im/jsonapi-rb).
3737

38+
+ [Getting started](/guides/getting_started)
3839
+ [Serialization](/guides/serialization)
3940
+ [Deserialization](/guides/deserialization)

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

Lines changed: 0 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -221,37 +221,6 @@ By default, for an instance of class `Post`, the corresponding serializable
221221
resource class will be assumed to be `SerializablePost` (this behavior can be
222222
configured, see next section).
223223

224-
In case you want to explicitly set the serializable resource class that will be
225-
used for the related resources, you can specify it via the `class` option. Its
226-
value can be either a constant:
227-
228-
```ruby
229-
class SerializablePost < JSONAPI::Serializable::Resource
230-
# ...
231-
has_many :comments, class: New::SerializableComment
232-
end
233-
```
234-
a string:
235-
236-
```ruby
237-
class SerializablePost < JSONAPI::Serializable::Resource
238-
# ...
239-
has_many :comments, class: 'New::SerializableComment'
240-
end
241-
```
242-
or a hash (for polymorphic relationships):
243-
244-
```ruby
245-
class SerializablePost < JSONAPI::Serializable::Resource
246-
# ...
247-
has_one :author, class: { User: 'SpecialSerializableUser',
248-
Admin: 'SpecialSerializableAdmin' }
249-
end
250-
```
251-
252-
Note that while this usage is supported, it is actually recommended to set a
253-
global explicit mapping at the renderer level.
254-
255224
### Linkage data overriding
256225

257226
Note: it is also possible to manually override the linkage data for a

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

Lines changed: 0 additions & 8 deletions
This file was deleted.

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

Lines changed: 16 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -7,108 +7,28 @@ The renderer takes your business objects (which can be any ruby objects: POROs,
77
ActiveRecord models, or even plain hashes), along with some optional parameters
88
(`include`, `fields`, etc.), and builds the JSON API document.
99

10-
## Plain ruby
10+
The available global options are:
1111

12-
When using jsonapi-rb in plain ruby (or from within a framework outside of a
13-
controller), you can render a document as follows:
14-
15-
```ruby
16-
JSONAPI::Serializable::SuccessRenderer.render(posts)
17-
```
18-
19-
You can also pass options to the renderer:
20-
21-
```ruby
22-
JSONAPI::Serializable::SuccessRenderer.render(posts,
23-
include: [:author, comments: [:author]],
24-
fields: { users: [:name, :email],
25-
posts: [:title, :content] })
26-
```
27-
28-
For a comprehensive list of renderer options, see [Renderer options]().
29-
30-
## Ruby on Rails
31-
32-
When using jsonapi-rb with Rails (via the jsonapi-rails gem), rendering is done
33-
via the usual `render` controller method:
34-
35-
```ruby
36-
render jsonapi: posts
37-
```
38-
and options are passed as named arguments:
39-
40-
```ruby
41-
render jsonapi: posts,
42-
include: [:author, comments: [:author]],
43-
fields: { users: [:name, :email],
44-
posts: [:title, :content] }
45-
```
46-
47-
For a comprehensive list of renderer options, see [Renderer options]().
48-
49-
## Hanami
50-
51-
When using jsonapi-rb with Hanami (via the jsonapi-hanami gem), enabling of
52-
jsonapi-rb features is opt-in, and is done by including
53-
`JSONAPI::Hanami::Action` in your actions.
54-
Rendering is done by setting options directly on the controller action instance.
55-
The primary data is set via the `self.data` setter.
56-
57-
Exposures are available from within the `SerializableResource` class as instance
58-
variables.
59-
60-
Example:
61-
62-
```ruby
63-
module API::Controllers::Posts
64-
class Create
65-
include API::Action
66-
include JSONAPI::Hanami::Action
67-
68-
expose :url_helpers
69-
70-
def call(params)
71-
# ...
72-
@url_helpers = routes # Will be available inside serializable resources.
73-
74-
self.data = posts
75-
self.include = [:author, comments: [:author]]
76-
self.fields = { users: [:name, :email],
77-
posts: [:title, :content] }
78-
end
79-
end
80-
end
81-
```
82-
83-
For a comprehensive list of renderer options, see [Renderer options]().
84-
85-
## Renderer options
86-
87-
The available options are:
88-
89-
+ data-related options:
90-
+ `include`: the related resources to include in the document. This option can
91-
be specified as a string (e.g. `"author,comments.author"`), or as an array/
92-
hash of symbols (e.g. `[:author, comments: [:author]]`).
93-
+ `fields`: a restricted set of fields for some or all resources. This option
94-
can be specified as a hash of arrays of symbols (e.g.
95-
`{ users: [:name, :email], posts: [:title, :content] }`).
96-
+ `expose`: a hash of arbitrary variables that will be made available to the
97-
serializable resources as instance variables.
9812
+ serializable resource class related options:
99-
+ `inferrer`: a hash globally mapping model class names to serializable resource
100-
class names.
101-
+ `namespace`: the namespace in which to look for serializable resource
102-
classes. This option can be specified as a constant (e.g. `V2`), or as a
103-
string (e.g. `"V2"`).
104-
+ `class`: the serializable resource class(es) to be used for the primary
105-
data. This option can be specified as a constant (e.g. `SerializablePost`),
106-
as a string (e.g. `"SerializablePost"`), or as a hash (e.g.
107-
`{ Article: "SerializableFormattedArticle", Letter: "SerializableFormattedLetter" }`).
13+
+ `class`: a hash globally mapping model class names to serializable resource
14+
class names.
10815
+ top level properties:
10916
+ `links`: a set of top level links. This option can be specified as a hash.
11017
+ `meta`: top level meta information. This option can be specified as a hash.
11118
+ `jsonapi`: top level `jsonapi` object. This option can be specified as a
11219
hash.
11320
+ framework-specific options: in Hanami and Rails, the usual options such as
11421
`status` are respected.
22+
23+
When serializing resources and relationships, the following
24+
data-related options are also available:
25+
26+
+ `include`: the related resources to include in the document. This option can
27+
be specified as a string (e.g. `"author,comments.author"`), or as an array/
28+
hash of symbols (e.g. `[:author, comments: [:author]]`).
29+
+ `fields`: a restricted set of fields for some or all resources. This option
30+
can be specified as a hash of arrays of symbols (e.g.
31+
`{ users: [:name, :email], posts: [:title, :content] }`).
32+
+ `expose`: a hash of arbitrary variables that will be made available to the
33+
serializable resources as instance variables.
34+
+ `cache`: a cache supporting `fetch_multi` for fragment caching.

0 commit comments

Comments
 (0)