Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

clarify rails controller serialization #25

Open
wants to merge 1 commit into
base: source
Choose a base branch
from
+37 −4
Open

clarify rails controller serialization #25

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 37 additions & 4 deletions source/guides/getting_started/rails.html.md.erb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,30 @@ Start by adding the following to your `Gemfile`:
gem 'jsonapi-rails'
```

Then, once your [serializable resources](/guides/serialization) are defined, building
Every object and its relationships that you intend to render will need to be
defined as [serializable resources](/guides/serialization). Then, building
a JSON API document from your business objects is straightforward: simply pass them
to the `render` method.

For a comprehensive list of renderer options, see
[Renderer options](/guides/serialization/rendering.html).
## Rendering a single resource

In this example, the `Post` model should have a corresponding `SerializableScan`,
then all that is required for `jsonapi-rails` to render it is the use of the
`:jsonapi` option with `render`:

```ruby
class PostsController < ActionController::Base
# ...

def index
render jsonapi: Posts.all
end

# ...
end
```

## Rendering resources
## Rendering resources with related resources included.

```ruby
class PostsController < ActionController::Base
Expand All @@ -32,8 +48,16 @@ class PostsController < ActionController::Base
end
```

In this example, `SerializableResource`s should be defined for `Post`, `Comment`
and `User` (the `Author` relationship's class). The include parameter maps to
jsonapi's concept of inclusion, and will produce an `includes` top level member.


## Rendering relationships

To render relationships per the `jsonapi` spec, the relationships should be
defined as such and included:

```ruby
class PostsController < ActionController::Base
# ...
Expand All @@ -50,6 +74,12 @@ class PostsController < ActionController::Base
end
```

Again, in this example a `PostSerializer`, `CommentSerializer` and `UserSerializer`
should exist. This will produce a compound document that describes the `Post`,
and its `Comment` relationships, with the serialized `Comment` and author (`User`)
included in the resulting json.


## Rendering errors

```ruby
Expand All @@ -70,6 +100,9 @@ class PostsController < ActionController::Base
end
```

For a comprehensive list of renderer options, see
[Renderer options](/guides/serialization/rendering.html).

## Configuration

### Application-wide settings
Expand Down