ROAR
Resource-Oriented Architectures in Ruby.
Introduction
Roar is a framework for parsing and rendering REST documents. Nothing more.
Representers let you define your API document structure and semantics. They allow both rendering representations from your models and parsing documents to update your Ruby objects. The bi-directional nature of representers make them interesting for both server and client usage.
Roar comes with built-in JSON, JSON-HAL and XML support. Its highly modulare architecture provides features like coercion, hypermedia, HTTP transport, client caching and more.
Roar is completely framework-agnostic and loves being used in web kits like Rails, Webmachine, Sinatra, Padrino, etc. If you use Rails, consider roar-rails for an enjoyable integration.
Representable
Roar is just a thin layer on top of the representable gem. While Roar gives you a DSL and behaviour for creating hypermedia APIs, representable implements all the mapping functionality.
If in need for a feature, make sure to check the representable API docs first.
Defining Representers
Let's see how representers work. They're fun to use.
require 'roar/representer/json'
module SongRepresenter
include Roar::Representer::JSON
property :title
end
API documents are defined using a representer module or decorator class. You can define plain attributes using the ::property
method.
Now let's assume we'd have Song
which is an ActiveRecord
class. Please note that Roar is not limited to ActiveRecord. In fact, it doesn't really care whether it's representing ActiveRecord, Datamapper or just an OpenStruct instance.
class Song < ActiveRecord
end
Rendering
To render a document, you apply the representer to your model.
song = Song.new(title: "Fate")
song.extend(SongRepresenter)
song.to_json #=> {"title":"Fate"}
Here, the representer is injected into the actual model and gives us a new #to_json
method.
Parsing
The cool thing about representers is: they can be used for rendering and parsing. See how easy updating your model from a document is.
song = Song.new
song.extend(SongRepresenter)
song.from_json('{"title":"Linoleum"}')
song.title #=> Linoleum
Again, #from_json
comes from the representer and just updates the known properties.
Unknown attributes in the parsed document are simply ignored, making half-baked solutions like strong_parameters
redundant.
Decorator
Many people dislike #extend
due to eventual performance issue or object pollution. If you're one of those, just go with a decorator representer. They almost work identical to the module approach we just discovered.
require 'roar/decorator'
class SongRepresenter < Roar::Decorator
include Roar::Representer::JSON
property :title
end
In place of a module you use a class, the DSL inside is the same you already know.
song = Song.new(title: "Medicine Balls")
SongRepresenter.new(song).to_json #=> {"title":"Medicine Balls"}
Here, the song
objects gets wrapped (or "decorated") by the decorator. It is treated as immutuable - Roar won't mix in any behaviour.
Note that decorators and representer modules have identical features. You can parse, render, nest, go nuts with both of them.
However, in this README we'll use modules to illustrate this framework.
Collections
Roar (or rather representable) also allows to map collections in documents.
module SongRepresenter
include Roar::Representer::JSON
property :title
collection :composers
end
Where ::property
knows how to handle plain attributes, ::collection
does lists.
song = Song.new(title: "Roxanne", composers: ["Sting", "Stu Copeland"])
song.extend(SongRepresenter)
song.to_json #=> {"title":"Roxanne","composers":["Sting","Stu Copeland"]}
And, yes, this also works for parsing: from_json
will create and populate the array of the composers
attribute.
Nesting
Now what if we need to tackle with collections of Song
s? We need to implement an Album
class.
class Album < ActiveRecord
has_many :songs
end
Another representer to represent.
module AlbumRepresenter
include Roar::Representer::JSON
property :title
collection :songs, extend: SongRepresenter, class: Song
end
Both ::property
and ::collection
accept options for nesting representers into representers.
The extend:
option tells Roar which representer to use for the nested objects (here, the array items of the album.songs
field). When parsing a document class:
defines the nested object type.
Consider the following object setup.
album = Album.new(title: "True North")
album.songs << Song.new(title: "The Island")
album.songs << Song.new(:title => "Changing Tide")
You apply the AlbumRepresenter
and you get a nested document.
album.extend(AlbumRepresenter)
album.to_json #=> {"title":"True North","songs":[{"title":"The Island"},{"title":"Changing Tide"}]}
This works vice-versa.
album = Album.new
album.extend(AlbumRepresenter)
album.from_json('{"title":"Indestructible","songs":[{"title":"Tropical London"},{"title":"Roadblock"}]}')
puts album.songs[1] #=> #<Song title="Roadblock">
The nesting of two representers can map composed object as you find them in many many APIs.
In case you're after virtual nesting, where a nested block in your document still maps to the same outer object, check out the ::nested
method.
Inline Representer
Sometimes you don't wanna create two separate representers - although it makes them reusable across your app. Use inline representers if you're not intending this.
module AlbumRepresenter
include Roar::Representer::JSON
property :title
collection :songs, class: Song do
property :title
end
end
This will give you the same rendering and parsing behaviour as in the previous example with just one module.
Syncing Objects
Usually, when parsing, nested objects are created from scratch. If you want nested objects to be updated instead of being newly created, use parse_strategy:
.
module AlbumRepresenter
include Roar::Representer::JSON
property :title
collection :songs, extend: SongRepresenter, parse_strategy: :sync
end
This will advise Roar to update existing songs
.
album.songs[0].object_id #=> 81431220
album.from_json('{"title":"True North","songs":[{"title":"Secret Society"},{"title":"Changing Tide"}]}')
album.songs[0].title #=> Secret Society
album.songs[0].object_id #=> 81431220
Roar didn't create a new Song
instance but updated its attributes, only.
We're currently working on better strategies to easily implement POST
and PUT
semantics in your APIs without having to worry about the nitty-gritties.
Coercion
Roar provides coercion with the virtus gem.
require 'roar/representer/feature/coercion'
module SongRepresenter
include Roar::Representer::JSON
include Roar::Representer::Feature::Coercion
property :title
property :released_at, type: DateTime
end
The :type
option allows to set a virtus-compatible type.
song = Song.new
song.extend(SongRepresenter)
song.from_json('{"released_at":"1981/03/31"}')
song.released_at #=> 1981-03-31T00:00:00+00:00
More Features
Roar/representable gives you many more mapping features like renaming attributes, wrapping, passing options, etc.
Hypermedia
Roar comes with built-in support for embedding and processing hypermedia in your documents.
module SongRepresenter
include Roar::Representer::JSON
include Roar::Representer::Feature::Hypermedia
property :title
link :self do
"http://songs/#{title}"
end
end
The Hypermedia
feature allows declaring links using the ::link
method.
song.extend(SongRepresenter)
song.to_json #=> {"title":"Roxanne","links":[{"rel":"self","href":"http://songs/Roxanne"}]}
Per default, links are pushed into the hash using the links
key. Link blocks are executed in represented context, allowing you to call any instance method of your model (here, we call #title
).
Also, note that roar-rails allows using URL helpers in link blocks.
Passing Options
Sometimes you need more data in the link block. Data that's not available from the represented model.
module SongRepresenter
include Roar::Representer::JSON
property :title
link :self do |opts|
"http://#{opts[:base_url]}songs/#{title}"
end
end
Pass this data to the rendering method.
song.to_json(base_url: "localhost:3001/")
Any options passed to #to_json
will be available as block arguments in the link blocks.
Consuming Hypermedia
Since we defined hypermedia attributes in the representer we can also consume this hypermedia when we parse documents.
song.from_json('{"title":"Roxanne","links":[{"rel":"self","href":"http://songs/Roxanne"}]}')
song.links[:self].href #=> "http://songs/Roxanne"
Reading link attributes works by using #links[]
on the consuming instance.
This allows an easy way to discover hypermedia and build navigational logic on top.
Media Formats
While Roar comes with a built-in hypermedia format, there's official media types that are widely recognized. Roar currently supports HAL and Collection+JSON. Support for Siren and JSON-API is planned when there's sponsors.
Simply by including a module you make your representer understand the media type. This makes it easy to change formats during evaluation.
HAL-JSON
The HAL format is a simple media type that defines embedded resources and hypermedia.
require 'roar/representer/json/hal'
module SongRepresenter
include Roar::Representer::JSON::HAL
property :title
link :self do
"http://songs/#{title}"
end
end
Documentation for HAL can be found in the API docs.
Hypermedia
Including the Roar::Representer::JSON::HAL
module adds some more DSL methods to your module. It still allows using ::link
but treats them slightly different.
song.to_json
#=> {"title":"Roxanne","_links":{"self":{"href":"http://songs/Roxanne"}}}
According to the HAL specification, links are now key with their rel
attribute under the _links
key.
Parsing works like-wise: Roar will use the same setters as before but it knows how to read HAL.
Nesting
Nested, or embedded, resources can be defined using the :embedded
option.
module AlbumRepresenter
include Roar::Representer::JSON::HAL
property :title
collection :songs, class: Song, embedded: true do
property :title
end
end
To embed a resource, you can use an inline representer or use :extend
to specify the representer name.
album.to_json
#=> {"title":"True North","_embedded":{"songs":[{"title":"The Island"},{"title":"Changing Tide"}]}}
HAL keys nested resources under the _embedded
key and then by their type.
All HAL features in Roar are discussed in the API docs, including array links.
Collection+JSON
The Collection+JSON media format defines document format and semantics for requests. It is currently experimental as we're still exploring how we optimize the support with Roar. Let us know if you're using it.
module SongRepresenter
include Roar::Representer::JSON::CollectionJSON
version "1.0"
href { "http://localhost/songs/" }
property :title
items(:class => Song) do
href { "//songs/#{title}" }
property :title, :prompt => "Song title"
link(:download) { "//songs/#{title}.mp3" }
end
template do
property :title, :prompt => "Song title"
end
queries do
link :search do
{:href => "//search", :data => [{:name => "q", :value => ""}]}
end
end
end
It renders a document following the Collection+JSON specs.
#=> {"collection":{
"template":{"data":[{"name":"title","value":null}]},
"queries":[{"rel":"search","href":"//search","data":[{"name":"q","value":""}]}],
"version":"1.0",
"href":"http://localhost/songs/",
"title":"Roxanne",
"items":null}}
We have big plans with this media format, as the object model in Roar plays nicely with Collection+JSON's API semantics.
Client-Side Support
Being a bi-directional mapper that does rendering and parsing, Roar representers are perfectly suitable for use in clients, too. In many projects, representers are shared as gems between server and client.
Consider the following shared representer.
module SongRepresenter
include Roar::Representer::JSON
include Roar::Representer::Feature::Hypermedia
property :title
property :id
link :self do
"http://songs/#{title}"
end
end
In a client where you don't have access to the database it is common to use OpenStruct
classes as domain objects.
require 'roar/representer/feature/client'
class Song < OpenStruct
include Roar::Representer::JSON
include SongRepresenter
include Roar::Representer::Feature::Client
end
HTTP Support
The Feature::Client
module mixes all necessary methods into the client class, e.g. it provides HTTP support
song = Song.new(title: "Roxanne")
song.post(uri: "http://localhost:4567/songs", as: "application/json")
song.id #=> 42
What happens here?
- You're responsible for initializing the client object with attributes. This can happen with in the constructor or using accessors.
post
will use the includedSongRepresenter
to compile the document using#to_json
.- The document gets
POST
ed to the passed URL. - If a document is returned, it is deserialized and the client's attributes are updated.
This is a very simple but efficient mechanism for working with representations in a client application.
Roar works with all HTTP request types, check out GET
.
song = Client::Song.new
song.get(uri: "http://localhost:4567/songs/1", as: "application/json")
song.title #=> "Roxanne"
song.links[:self].href #=> http://localhost/songs/1
As GET
is not supposed to send any data, you can use #get
on an empty object to populate it with the server data.
HTTPS
Roar supports SSL connections - they are automatically detected via the protocol.
song.get(uri: "https://localhost:4567/songs/1")`
Basic Authentication
The HTTP verbs allow you to specify credentials for HTTP basic auth.
song.get(uri: "http://localhost:4567/songs/1", basic_auth: ["username", "secret_password"])
Request customization
All verbs yield the request object before the request is sent, allowing to modify it. It is a Net::HTTP::Request
instance (unless you use Faraday).
song.get(uri: "http://localhost:4567/songs/1") do |req|
req.add_field("Cookie", "Yumyum")
end
XML
Roar also comes with XML support.
module SongRepresenter
include Roar::Representer::XML
include Roar::Representer::Feature::Hypermedia
property :title
property :id
link :self do
"http://songs/#{title}"
end
end
Include the Roar::Representer::XML
engine and get bi-directional XML for your objects.
song = Song.new(title: "Roxanne", id: 42)
song.extend(XML::SongRepresenter)
song.to_xml
Note that you now use #to_xml
and #from_xml
.
<song>
<title>Roxanne</title>
<id>42</id>
<link rel="self" href="http://songs/Roxanne"/>
</song>
Please consult the representable XML documentation for all its great features.
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.