Skip to content
JSON API support for Roar.
Ruby
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib/roar/json Merge pull request #38 from acidtangodev/master Feb 7, 2019
test Merge pull request #38 from acidtangodev/master Feb 7, 2019
.gitignore Initial commit: extracted from roar gem Dec 10, 2016
.rubocop.yml
.travis.yml
.yardopts Add initial public API Yardocs Jan 11, 2017
CHANGELOG.md rename changes to changelog and update [ci-skip] Aug 2, 2018
CONTRIBUTING.md Add CONTRIBUTING AND ISSUE_TEMPLATE Dec 14, 2016
Gemfile
ISSUE_TEMPLATE.md Add CONTRIBUTING AND ISSUE_TEMPLATE Dec 14, 2016
LICENSE Update copyright year Jan 1, 2017
README.markdown Update meta: option information in README Jan 12, 2017
Rakefile Initial commit: extracted from roar gem Dec 10, 2016
roar-jsonapi.gemspec

README.markdown

Roar JSON API

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.

Resource

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

require 'roar/json/json_api'

class SongsRepresenter < Roar::Decorator
  include Roar::JSON::JSONAPI.resource :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.

Relationships

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

class SongsRepresenter < Roar::Decorator
  include Roar::JSON::JSONAPI.resource :songs

  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.

class SongsRepresenter < Roar::Decorator
  include Roar::JSON::JSONAPI.resource :songs

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

Your collection object must expose the respective methods.

collection.page  #=> 1
collection.total #=> 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.

collection.to_json(meta: {page: params["page"], total: collection.size})

Both methods work for singular documents too.

class SongsRepresenter < Roar::Decorator
  include Roar::JSON::JSONAPI.resource :songs

  meta do
    property :label
    property :format
  end
end
song.to_json(meta: { label: 'EMI' })

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

Usage

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

SongsRepresenter.prepare(Song.find(1)).to_json
SongsRepresenter.prepare(Song.new).from_json("..")

Singular models can use the representer module directly.

SongsRepresenter.for_collection.prepare([Song.find(1), Song.find(2)]).to_json
SongsRepresenter.for_collection.prepare([Song.new, Song.new]).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.

Support

Questions? Need help? Free 1st Level Support on irc.freenode.org#roar ! We also have a mailing list, yiha!

License

Roar is released under the MIT License.

You can’t perform that action at this time.