Resource-Oriented Architectures in Ruby.

Gitter Chat TRB Newsletter Build Status Gem Version

Roar JSON API provides support for JSON API, a specification for building APIs in JSON. It can render and parse singular and collection documents.


A minimal representation of a Resource can be defined as follows:

“by require ‘roar/json/json_api’

class SongsRepresenter < Roar::Decorator include Roar::JSON::JSONAPI type :songs

attributes do property :title end end

Properties (or attributes) of the represented model are defined within an attributes block.

An id property will automatically defined when using Roar JSON API.


To define relationships, use ::has_one or ::has_many with either an inline or a standalone representer (specified with the extend: or decorates: option).

“by class SongsRepresenter < Roar::Decorator has_one :album do property :title end

has_many :musicians, extend: MusicianRepresenter end

Meta information

Meta information can be included into rendered singular and collection documents in two ways.

You can define meta information on your collection object and then let Roar compile it.

“by class SongsRepresenter < Roar::Decorator # ..

meta toplevel: true do property :page property :total end

Your collection object must expose the respective methods.

“by #=> 1 #=> 12

This will render the {"meta": {"page": 1, "total": 12}} hash into the JSON API document.

Alternatively, you can provide meta information as a hash when rendering. Any values also defined on your object will be overriden.

“by collection.to_json(“meta” => params[page], total: collection.size)

Both methods work for singular documents too.

“by class SongsRepresenter < Roar::Decorator # ..

meta do property :label property :format end end

“by song.to_json(“meta” => { label: ‘EMI’ })

If you need more functionality (and parsing), please let us know.


As JSON API per definition can represent singular models and collections you have two entry points.

“by SongsRepresenter.prepare(Song.find(1)).to_json SongsRepresenter.prepare(“..”)

Singular models can use the representer module directly.

“by SongsRepresenter.for_collection.prepare([Song.find(1), Song.find(2)]).to_json SongsRepresenter.for_collection.prepare([,]).from_json(“..”)

Parsing currently works great with singular documents - for collections, we are still working out how to encode the application semantics. Feel free to help.


Questions? Need help? Free 1st Level Support on ! We also have a mailing list, yiha!


Roar is released under the MIT License.