rails.html.md.erb

---
layout: guides
---
# Getting started - Ruby on Rails

Start by adding the following to your `Gemfile`:

```ruby
gem 'jsonapi-rails'
```

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.

## 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 with related resources included.

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

  def index
    render jsonapi: Posts.all, include: [:author, comments: [:author]],
           fields: { users: [:name, :email],
                     posts: [:title, :content] }
  end

  # ...
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
  # ...

  def comments_relationship
    post = Post.find(id: params[:id])
    render jsonapi: post, relationship: :comments,
           include: [comments: [:author]],
           fields: { users: [:name, :email],
                     posts: [:title, :content] }
  end

  # ...
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
class PostsController < ActionController::Base
  # ...

  def create
    post = Post.new(params[:post])

    if post.save
      render jsonapi: post
    else
      render jsonapi_errors: post.errors
    end
  end

  # ...
end
```

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

## Configuration

### Application-wide settings

You can customize default behaviors in an initializer (`$ rails generate jsonapi:initializer`).

### Controller-wide settings

It is also possible to override application-wide settings at controller level. Simply define
one of the available hooks:
`jsonapi_class`, `jsonapi_errors_class`,`jsonapi_object`, `jsonapi_include`,
`jsonapi_fields`, `jsonapi_expose`, `jsonapi_pagination`.

### Action-wide settings

It is always possible to override the application/controller-wide settings at action level
by providing the relevant [renderer options](/guides/serialization/rendering.html).

### Serializable class lookup

By default, for an instance of `Article`, the corresponding serializable resource class
will be guessed as `SerializableArticle`.

This behavior is customizable by overriding the `jsonapi_class` setting (or by supplying
a `class` renderer option). Either set it to an explicit hash, or a hash with a dynamic
default value for inferrence.

### Pagination

TODO