roar 1.0.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f01bf5404137ba89f28ddcdbeb0f2248933321dc
-  data.tar.gz: 3ddf4943609d770657728bb85e213c66244b039e
+  metadata.gz: a9315b89b6aa93848741828ab6a94e338677e397
+  data.tar.gz: c373cdb3f85a40560502cd9ef09ad88363499394
 SHA512:
-  metadata.gz: 232903cf0f2a85f71105a2342dad1d226524c4f31d1a724dd7aaa3ad46cbffe4632f78e0967f6e4defb47d1bd6c7175c99ff14e51d1baa023d02cd404dc6812b
-  data.tar.gz: 52c7b7189448a074580cdd1a3f7ac0cb192ea6c3a19eed5c32ac55fb496206b3d8d8008a95600b9c409df77f4e52bb5c4c602aef53e34250915297647bac53c1
+  metadata.gz: 059ab5ab647e9ec273976d485715dfed04895dc1538e8331025cea005995a1b9cf9cdb16c7e0ed34441f338594976e09c9ba48ccd071a2846aed5697a81f742c
+  data.tar.gz: 93101c0816d59b8ffe8465eddb7d5882f132322b1c00f4e44dd960c4b840ac0ce52f4d647245ebdec52682fccfb88c0716ee1c1b4d998c46e5edc6d92753cd4a

data/.travis.yml

@@ -1,9 +1,17 @@
+sudo: false
 rvm:
-  - 1.9
-  - 2.0
+  - 1.9.3
   - 2.1
-  - 2.2
-  - rbx-2
+  - 2.2.6
+  - 2.3.1
+  - 2.4.0
+  - jruby-9.1.6.0
+  - ruby-head
 gemfile:
-  - gemfiles/Gemfile.representable-2.0
-  - gemfiles/Gemfile.representable-2.1
+  - Gemfile
+  # - gemfiles/Gemfile.representable-2.4
+before_install:
+  - gem install bundler
+matrix:
+  allow_failures:
+    - rvm: ruby-head

data/CHANGES.markdown

@@ -1,6 +1,16 @@
+# 1.1.0
+
+* Require Representable 3.0.x
+* Remove CollectionJSON support until we get more feedback.
+* Move JSON API support (`Roar::JSON::JSONAPI`) to the separate [roar-jsonapi](https://github.com/trailblazer/roar-jsonapi) gem.
+* When using `links[]`, you now need to provide the string name, as in `decorator.links["self"]`. Symbols are not supported, anymore.
+* `::links` now accepts a String or Symbol as its first argument, enabling more straight-forward definition of CURIE links: e.g. `links 'doc:link_collection' do; end` (@edejong).
+* Clients can now parse lonely collections. (@hilary)
+
+
 # 1.0.4
 
-* Representable < 2.4.
+* Require Representable < 2.4.
 
 # 1.0.3
 
@@ -17,7 +27,7 @@
 
 # 1.0.1
 
-* Allow calling `::has_one`, `::links` and `::has_many` in any order in JSON-API. This requires representable >= 2.1.4.
+* Allow calling `::has_one`, `::links` and `::has_many` in any order in JSON API. This requires Representable >= 2.1.4.
 
 # 1.0.0
 
@@ -31,25 +41,24 @@
 
 ## Added
 
-* `Roar::JSON::JSONAPI` supports JSON-API. A big thanks to @oliverbarnes for his continous help, support and research on how to implement this standard.
-
+* `Roar::JSON::JSONAPI` supports JSON API. A big thanks to @oliverbarnes for his continuous help, support and research on how to implement this standard.
 
 ## Relevant
 
 * `Hyperlink#to_hash` now returns stringified keys.
 * Removed `Representer#before_serialize` hook. Override `#serialize` yourself.
-* Represented#links now returns `nil` when no parsing has happened.
+* `Represented#links` now returns `nil` when no parsing has happened.
 * Removed class methods `::from_json`, `::from_hash`, `::from_xml` and `::deserialize`. Please build the instance yourself and use something along `Song.new.from_json`.
 
 ## Internals
 
-* Remove the concept of ´links_array`. `Hyperlink` instances for rendering or that have been parsed are always stored in a `LinkCollection` that is available via `#links`.
+* Remove the concept of `links_array`. `Hyperlink` instances for rendering or that have been parsed are always stored in a `LinkCollection` that is available via `#links`.
 * `Hypermedia` is now 43% simpler.
 * `HyperlinkCollection#each` now has different semantics for 1- or 2-arity.
 
 # 0.12.8
 
-* Last release to support representable < 2.0.
+* Last release to support Representable < 2.0.
 
 # 0.12.7
 
@@ -57,11 +66,11 @@
 
 # 0.12.6
 
-* Remove deprecations (most of 'em) from representable-1.8. Sorry for that.
+* Remove deprecations (most of 'em) from Representable 1.8. Sorry for that.
 
 # 0.12.5
 
-* Roar runs with representable <= 1.8.
+* Roar runs with Representable <= 1.8.
 
 # 0.12.4
 
@@ -79,23 +88,22 @@
 * They now yield the request object to add headers etc before request is sent.
 * They NO LONGER support positional arguments but one hash with `uri: "https://roar.de", body:, .. as: ..` and so on.
 
-
 # 0.12.2
 
 * Fix a bug where hyperlinks from nested objects weren't rendered in XML.
 
 # 0.12.1
 
-Allow representable >= 1.6.
+Allow Representable >= 1.6.
 
 # 0.11.18
 
-* Updating to representable-1.5.2.
+* Updating to Representable 1.5.2.
 
 # 0.11.17
 
 * Fixing HAL + Decorator.
-* Requiring representable-1.5.0.
+* Requiring Representable 1.5.0.
 
 # 0.11.16
 
@@ -103,15 +111,15 @@ Allow representable >= 1.6.
 
 # 0.11.15
 
-* Fixing [#66](https://github.com/apotonick/roar/issues/66).
+* Fixing [#66](https://github.com/trailblazer/roar/issues/66).
 
 # 0.11.14
 
-* Fixing Gemfile.
+* Fixing `Gemfile`.
 
 # 0.11.13
 
-* Adding `Roar::Decorator`, see [representable docs](https://github.com/apotonick/representable#decorator-vs-extend) for now.
+* Adding `Roar::Decorator`, see [Representable docs](https://github.com/apotonick/Representable#decorator-vs-extend) for now.
 
 # 0.11.12
 
@@ -121,104 +129,113 @@ Allow representable >= 1.6.
 
 * Allow use of `::link(string)`.
 
-## 0.11.10
+# 0.11.10
 
 * Fix a syntax error for Ruby 1.8.
-* Store link definitions in `representable_attrs(:links)` now and no longer in the `LinksDefinition` instance itself. removing `#links_definition` in favor of `#link_configs`.
+* Store link definitions in `Representable_attrs(:links)` now and no longer in the `LinksDefinition` instance itself. removing `#links_definition` in favor of `#link_configs`.
 
-## 0.11.9
+# 0.11.9
 
 * When using `Feature::Client` hyperlinks are no longer rendered in POST and PUT since we pass `links: false`.
 * `Transport::NetHttp` now sets both `Accept:` and `Content-type:` header since Rails services seems to get confused.
 
-## 0.11.8
+# 0.11.8
 
 * Fixed `JSON::HAL::Links` so that it keys links with `links` and not `_links`. The latter is still done by `JSON::HAL`.
 
-## 0.11.7
+# 0.11.7
 
 * Maintenance release: Fixing the horrible bug fix from 0.11.6 and make it a bit less horrible.
 
-## 0.11.6
+# 0.11.6
 
 * "Fixing" a bug where `links_definition_option` was missing when no link was set in a representer. Note that this is a quick and horrible bugfix and will soon be cleaned up.
 
-## 0.11.5
+# 0.11.5
 
-* Introducing HAL::links method to map arrays of link objects in the HAL format. This completes the HAL/JSON specification.
+* Introducing `HAL::links` method to map arrays of link objects in the HAL format. This completes the HAL/JSON specification.
 
-## 0.11.4
+# 0.11.4
 
 * Links can now return a hash of attributes as `link :self do {:href => fruit_path(self), :title => "Yummy stuff"} end`.
 
-## 0.11.3
+# 0.11.3
 
 * Fixed an installation issue under Windows.
 
-## 0.11.2
+# 0.11.2
 
 * The request body in POST, PUT and PATCH is now actually sent in HttpVerbs. Thanks to @nleguen for finding this embarrassing bug. That's what happens when you don't have proper tests, kids!
 
-## 0.11.1
+# 0.11.1
+
+* Since some users don't have access to my local hard-drive we now really require Representable 1.2.2.
 
-* Since some users don't have access to my local hard-drive we now really require representable-1.2.2.
+# 0.11.0
 
-## 0.11.0
+* Using Representable 1.2.2 now. Be warned that in 1.2 parsing and rendering slightly changed. When a property is not found in the incoming document, it is ignored and thus might not be initialised in your represented model (empty collections are still set to an empty array). Also, the way `false` and `nil` values are rendered changed.
 
-* Using representable-1.2.2 now. Be warned that in 1.2 parsing and rendering slightly changed. When a property is not found in the incoming document, it is ignored and thus might not be initialised in your represented model (empty collections are still set to an empty array). Also, the way `false` and `nil` values are rendered changed. Quoted from the representable CHANGES file:
-* A property with false value will now be included in the rendered representation. Same applies to parsing, false values will now be included. That particularly means properties that used to be unset (i.e. nil) after parsing might be false now.
-* You can include nil values now in your representations since #property respects :represent_nil => true.
+  Quoted from the Representable CHANGES file:
 
-* The `:except` option got deprecated in favor of `:exclude`.
-* Hyperlinks can now have arbitrary attributes. To render, just provide `#link` with the options
-<code>link :self, :title => "Mee!", "data-remote" => true</code>
-When parsing, the options are avaible via `OpenStruct` compliant readers.
-<code>link = Hyperlink.from_json({\"rel\":\"self\",\"data-url\":\"http://self\"} )
-link.rel #=> "self"
-link.send("data-url") #=> "http://self"
-</code>
+  * A property with false value will now be included in the rendered representation. Same applies to parsing, false values will now be included. That particularly means properties that used to be unset (i.e. nil) after parsing might be false now.
+  * You can include nil values now in your representations since #property respects `:represent_nil => true`.
 
-## 0.10.2
+* The `:except` option was deprecated in favor of `:exclude`.
+* Hyperlinks can now have arbitrary attributes.
+  To render, just provide `#link` with the options
+
+  ```ruby
+  link :self, :title => "Mee!", "data-remote" => true
+  ```
+
+  When parsing, the options are available via `OpenStruct` compliant readers.
+
+  ```ruby
+  link = Hyperlink.from_json('{"rel":"self","data-url":"http://self"'})
+  link.rel #=> "self"
+  link.send("data-url") #=> "http://self"
+  ```
+
+# 0.10.2
 
 * You can now pass values from outside to the render method (e.g. `#to_json`), they will be available as block parameters inside `#link`.
 
-## 0.10.1
+# 0.10.1
 
 * Adding the Coercion feature.
 
-## 0.10.0
+# 0.10.0
 
-* Requiring representable-0.1.3.
+* Requiring Representable 0.1.3.
 * Added JSON-HAL support.
 * Links are no longer rendered when `href` is `nil` or `false`.
 * `Representer.link` class method now accepts either the `rel` value, only, or a hash of link attributes (defined in `Hypermedia::Hyperlink.params`), like `link :rel => :self, :title => "You're good" do..`
 * API CHANGE: `Representer#links` no longer returns the `href` value but the link object. Use it like `object.links[:self].href` to retrieve the URL.
 * `#from_json` won't throw an exception anymore when passed an empty json document.
 
-## 0.9.2
+# 0.9.2
 
-* Using representable-1.1.
+* Using Representable 1.1.
 
-## 0.9.1
+# 0.9.1
 
-* Removed @Representer#to_attributes@ and @#from_attributes@.
-* Using representable-1.0.1 now.
+* Removed `Representer#to_attributes` and `#from_attributes`.
+* Using Representable 1.0.1 now.
 
-## 0.9.0
+# 0.9.0
 
-* Using representable-0.12.x.
+* Using Representable 0.12.x.
 * `Representer::Base` is now simply `Representer`.
 * Removed all the class methods from `HttpVerbs` except for `get`.
 
+# 0.8.3
 
-## 0.8.3
-
-* Maintenance release for representable compat.
+* Maintenance release for Representable compat.
 
-## 0.8.2
+# 0.8.2
 
 * Removing `restfulie` dependency - we now use `Net::HTTP`.
 
-## 0.8.1
+# 0.8.1
 
-* Added the :except and :include options to `#from_*`.
+* Added the `:except` and `:include` options to `#from_*`.

data/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+## How to contribute to Roar
+
+#### **Did you find a bug?**
+
+* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/trailblazer/roar/issues).
+
+* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/trailblazer/roar/issues/new). Be sure to follow the issue template.
+
+#### **Did you write a patch that fixes a bug?**
+
+* Open a new GitHub pull request with the patch.
+
+* Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
+
+* All code in pull requests is assumed to be MIT licensed.  Do not submit a pull request if that isn't the case.
+
+#### **Do you intend to add a new feature or change an existing one?**
+
+* Suggest your change in the [Trailblazer Gitter Room](https://gitter.im/trailblazer/chat) and start writing code.
+
+* Do not open an issue on GitHub until you have collected positive feedback about the change. GitHub issues are primarily intended for bug reports and fixes.
+
+#### **Do you have questions using Roar?**
+
+* Ask any questions about how to use Roar in the [Trailblazer Gitter Room](https://gitter.im/trailblazer/chat). Github issues are restricted to bug reports and fixes.
+
+* GitHub Issues should not be used as a help forum and any such issues will be closed.
+
+#### **Do you want to contribute to the Roar documentation?**
+
+* Roar documentation is provided via the [Trailblazer site](http://trailblazer.to/gems/roar/) and not the repository readme. Please add your contributions to the [Trailblazer site repository](https://github.com/trailblazer/trailblazer.github.io)

data/Gemfile

@@ -3,5 +3,15 @@ source "http://rubygems.org"
 # Specify your gem's dependencies in roar.gemspec
 gemspec
 
-# as long as this is not merged, i'll vendor the runner file.
-# gem "sinatra-contrib", :git => "git@github.com:apotonick/sinatra-contrib.git", :branch => "runner"
+install_if -> { RUBY_VERSION > '2.2.2' } do
+  gem 'sinatra',          '~> 2.0.0.beta2'
+  gem 'sinatra-contrib',  github: 'sinatra/sinatra'
+end
+
+gem 'nokogiri', '~> 1.6.8'
+
+# gem "representable", path: "../representable"
+# gem "representable", github: "apotonick/representable"
+# gem "declarative", path: "../declarative"
+gem "minitest-line"
+gem "pry"

data/ISSUE_TEMPLATE.md

@@ -0,0 +1,20 @@
+Note: If you have a question about Roar, would like help using
+Roar, want to request a feature, or do anything else other than
+submit a bug report, please use the Trailblazer gitter channel.
+
+### Complete Description of Issue
+
+
+### Steps to reproduce
+
+
+### Expected behavior
+Tell us what should happen
+
+### Actual behavior
+Tell us what happens instead
+
+### System configuration
+**Roar version**:
+
+### Full Backtrace of Exception (if any)

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011 - 2013 Nick Sutterer and the roar contributors
+Copyright (c) 2011 - 2017 Nick Sutterer and the roar contributors
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.markdown

@@ -1,10 +1,47 @@
-# ROAR
+# Roar
 
 _Resource-Oriented Architectures in Ruby._
 
-[![Build Status](https://travis-ci.org/apotonick/roar.svg?branch=master)](https://travis-ci.org/apotonick/roar)
-[![Gem Version](https://badge.fury.io/rb/roar.svg)](http://badge.fury.io/rb/roar)
 [![Gitter Chat](https://badges.gitter.im/trailblazer/chat.svg)](https://gitter.im/trailblazer/chat)
+[![TRB Newsletter](https://img.shields.io/badge/TRB-newsletter-lightgrey.svg)](http://trailblazer.to/newsletter/)
+[![Build Status](https://travis-ci.org/trailblazer/roar.svg?branch=master)](https://travis-ci.org/trailblazer/roar)
+[![Gem Version](https://badge.fury.io/rb/roar.svg)](http://badge.fury.io/rb/roar)
+
+## Table of Contents
+
+  * [Introduction](#introduction)
+  * [Representable](#representable)
+  * [Installation](#installation)
+    * [Dependencies](#dependencies)
+  * [Defining Representers](#defining-representers)
+  * [Rendering](#rendering)
+  * [Parsing](#parsing)
+  * [Module Representers](#module-representers)
+  * [Collections](#collections)
+  * [Nesting](#nesting)
+  * [Inline Representer](#inline-representer)
+  * [Syncing Objects](#syncing-objects)
+  * [Coercion](#coercion)
+  * [More Features](#more-features)
+  * [Hypermedia](#hypermedia)
+  * [Passing Options](#passing-options)
+  * [Specify Decorator](#specify-decorator)
+  * [Consuming Hypermedia](#consuming-hypermedia)
+  * [Media Formats](#media-formats)
+  * [HAL\-JSON](#hal-json)
+    * [Hypermedia](#hypermedia-1)
+    * [Nesting](#nesting-1)
+  * [JSON API](#json-api)
+  * [Client\-Side Support](#client-side-support)
+  * [HTTP Support](#http-support)
+    * [HTTPS](#https)
+    * [Basic Authentication](#basic-authentication)
+    * [Client SSL certificates](#client-ssl-certificates)
+    * [Request customization](#request-customization)
+    * [Error handling](#error-handling)
+  * [XML](#xml)
+  * [Support](#support)
+  * [License](#license)
 
 ## Introduction
 
@@ -12,15 +49,15 @@ 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, JSON-API and XML support. Its highly modular architecture provides features like coercion, hypermedia, HTTP transport, client caching and more.
+Roar comes with built-in JSON, JSON-HAL and XML support. JSON API support is available via the [JSON API](https://github.com/trailblazer/roar-jsonapi) gem. Its highly modular 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](https://github.com/apotonick/roar-rails) for an enjoyable integration.
+Roar is completely framework-agnostic and loves being used in web kits like Rails, Hanami, Sinatra, Roda, etc. If you use Rails, consider [roar-rails](https://github.com/apotonick/roar-rails) for an enjoyable integration.
 
 ## Representable
 
-Roar is just a thin layer on top of the [representable](https://github.com/apotonick/representable) gem. While Roar gives you a DSL and behaviour for creating hypermedia APIs, representable implements all the mapping functionality.
+Roar is just a thin layer on top of the [representable](https://github.com/trailblazer/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](https://github.com/apotonick/representable) first.
+If in need for a feature, make sure to check the [representable API docs](https://github.com/trailblazer/representable) first.
 
 ## Installation
 
@@ -34,13 +71,13 @@ gem 'roar'
 
 Roar does not bundle dependencies for JSON and XML.
 
-If you want to use JSON, add the following to your Gemfile:
+If you want to use JSON, add the following to your `Gemfile`:
 
 ```ruby
 gem 'multi_json'
 ```
 
-If you want to use XML, add the following to your Gemfile:
+If you want to use XML, add the following to your `Gemfile`:
 
 ```ruby
 gem 'nokogiri'
@@ -52,21 +89,22 @@ gem 'nokogiri'
 Let's see how representers work. They're fun to use.
 
 ```ruby
+require 'roar/decorator'
 require 'roar/json'
 
-module SongRepresenter
+class SongRepresenter < Roar::Decorator
   include Roar::JSON
 
   property :title
 end
 ```
 
-API documents are defined using a representer module or decorator class. You can define plain attributes using the `::property` method.
+API documents are defined using a 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.
+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, `Sequel::Model` or just an OpenStruct instance.
 
 ```ruby
-class Song < ActiveRecord
+class Song < ActiveRecord::Base
 end
 ```
 
@@ -75,66 +113,62 @@ end
 To render a document, you apply the representer to your model.
 
 ```ruby
-song = Song.new(title: "Fate")
-song.extend(SongRepresenter)
+song = Song.new(title: "Medicine Balls")
 
-song.to_json #=> {"title":"Fate"}
+SongRepresenter.new(song).to_json #=> {"title":"Medicine Balls"}
 ```
 
-Here, the representer is injected into the actual model and gives us a new `#to_json` method.
+Here, the `song` objects gets wrapped (or "decorated") by the decorator. It is treated as immutable - Roar won't mix in any behaviour.
 
 ## 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.
 
 ```ruby
-song = Song.new
-song.extend(SongRepresenter)
-
-song.from_json('{"title":"Linoleum"}')
+song = Song.new(title: "Medicine Balls")
 
+SongRepresenter.new(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.
+## Module Representers
 
-```ruby
-require 'roar/decorator'
+**Module Representers are deprecated in Roar 1.1 and will be removed in Roar 2.0.**
 
-class SongRepresenter < Roar::Decorator
-  include Roar::JSON
+In place of inheriting from `Roar::Decorator`, you can also extend a singleton object with a representer module. Decorators and module representers actually have identical features. You can parse, render, nest, go nuts with both of them.
 
-  property :title
-end
-```
-In place of a module you use a class, the DSL inside is the same you already know.
 
 ```ruby
-song = Song.new(title: "Medicine Balls")
+song = Song.new(title: "Fate")
+song.extend(SongRepresenter)
 
-SongRepresenter.new(song).to_json #=> {"title":"Medicine Balls"}
+song.to_json #=> {"title":"Fate"}
 ```
 
-Here, the `song` objects gets wrapped (or "decorated") by the decorator. It is treated as immutuable - Roar won't mix in any behaviour.
+Here, the representer is injected into the actual model and gives us a new `#to_json` method.
 
-Note that decorators and representer modules have identical features. You can parse, render, nest, go nuts with both of them.
+This also works both ways.
 
-However, in this README we'll use modules to illustrate this framework.
+```ruby
+song = Song.new
+song.extend(SongRepresenter)
+
+song.from_json('{"title":"Fate"}')
+song #=> {"title":"Fate"}
+```
+
+It's worth noting though that many people dislike `#extend` due to well-known performance issues and object pollution. As such this approach is no longer recommended. In this README we'll use decorators to illustrate this library.
 
 
 ## Collections
 
-Roar (or rather representable) also allows to map collections in documents.
+Roar (or rather representable) also allows mapping collections in documents.
 
 ```ruby
-module SongRepresenter
+class SongRepresenter < Roar::Decorator
   include Roar::JSON
 
   property :title
@@ -146,9 +180,8 @@ Where `::property` knows how to handle plain attributes, `::collection` does lis
 
 ```ruby
 song = Song.new(title: "Roxanne", composers: ["Sting", "Stu Copeland"])
-song.extend(SongRepresenter)
 
-song.to_json #=> {"title":"Roxanne","composers":["Sting","Stu Copeland"]}
+SongRepresenter.new(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.
@@ -159,7 +192,7 @@ And, yes, this also works for parsing: `from_json` will create and populate the
 Now what if we need to tackle with collections of `Song`s? We need to implement an `Album` class.
 
 ```ruby
-class Album < ActiveRecord
+class Album < ActiveRecord::Base
   has_many :songs
 end
 ```
@@ -167,7 +200,7 @@ end
 Another representer to represent.
 
 ```ruby
-module AlbumRepresenter
+class AlbumRepresenter < Roar::Decorator
   include Roar::JSON
 
   property :title
@@ -184,38 +217,35 @@ Consider the following object setup.
 ```ruby
 album = Album.new(title: "True North")
 album.songs << Song.new(title: "The Island")
-album.songs << Song.new(:title => "Changing Tide")
+album.songs << Song.new(title: "Changing Tide")
 ```
 
 You apply the `AlbumRepresenter` and you get a nested document.
 
 ```ruby
-album.extend(AlbumRepresenter)
-
-album.to_json #=> {"title":"True North","songs":[{"title":"The Island"},{"title":"Changing Tide"}]}
+AlbumRepresenter.new(album).to_json #=> {"title":"True North","songs":[{"title":"The Island"},{"title":"Changing Tide"}]}
 ```
 
 This works vice-versa.
 
 ```ruby
 album = Album.new
-album.extend(AlbumRepresenter)
 
-album.from_json('{"title":"Indestructible","songs":[{"title":"Tropical London"},{"title":"Roadblock"}]}')
+AlbumRepresenter.new(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](https://github.com/apotonick/representable#document-nesting).
+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](https://github.com/trailblazer/representable#document-nesting).
 
 ## 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.
 
 ```ruby
-module AlbumRepresenter
+class AlbumRepresenter < Roar::Decorator
   include Roar::JSON
 
   property :title
@@ -234,7 +264,7 @@ This will give you the same rendering and parsing behaviour as in the previous e
 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:`.
 
 ```ruby
-module AlbumRepresenter
+class AlbumRepresenter < Roar::Decorator
   include Roar::JSON
 
   property :title
@@ -248,14 +278,14 @@ This will advise Roar to update existing `songs`.
 ```ruby
 album.songs[0].object_id #=> 81431220
 
-album.from_json('{"title":"True North","songs":[{"title":"Secret Society"},{"title":"Changing Tide"}]}')
+AlbumRepresenter.new(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](https://github.com/apotonick/roar/issues/85) better strategies to easily implement `POST` and `PUT` semantics in your APIs without having to worry about the nitty-gritties.
+We're currently [working on](https://github.com/trailblazer/roar/issues/85) better strategies to easily implement `POST` and `PUT` semantics in your APIs without having to worry about the nitty-gritties.
 
 
 ## Coercion
@@ -264,8 +294,9 @@ Roar provides coercion with the [virtus](https://github.com/solnic/virtus) gem.
 
 ```ruby
 require 'roar/coercion'
+require 'roar/json'
 
-module SongRepresenter
+class SongRepresenter < Roar::Decorator
   include Roar::JSON
   include Roar::Coercion
 
@@ -278,9 +309,8 @@ The `:type` option allows to set a virtus-compatible type.
 
 ```ruby
 song = Song.new
-song.extend(SongRepresenter)
 
-song.from_json('{"released_at":"1981/03/31"}')
+SongRepresenter.new(song).from_json('{"released_at":"1981/03/31"}')
 
 song.released_at #=> 1981-03-31T00:00:00+00:00
 ```
@@ -288,7 +318,7 @@ song.released_at #=> 1981-03-31T00:00:00+00:00
 
 ## More Features
 
-Roar/representable gives you many more mapping features like [renaming attributes](https://github.com/apotonick/representable/#aliasing), [wrapping](https://github.com/apotonick/representable/#wrapping), [passing options](https://github.com/apotonick/representable/#passing-options), etc.
+Roar/representable gives you many more mapping features like renaming attributes, wrapping, passing options, etc. See the [representable documentation](http://trailblazer.to/gems/representable/3.0/api.html) for a detailed explanation.
 
 
 ## Hypermedia
@@ -296,7 +326,7 @@ Roar/representable gives you many more mapping features like [renaming attribute
 Roar comes with built-in support for embedding and processing hypermedia in your documents.
 
 ```ruby
-module SongRepresenter
+class SongRepresenter < Roar::Decorator
   include Roar::JSON
   include Roar::Hypermedia
 
@@ -324,8 +354,7 @@ end
 This will render links into your representation.
 
 ```ruby
-song.extend(SongRepresenter)
-song.to_json #=> {"title":"Roxanne","links":[{"rel":"self","href":"http://songs/Roxanne"}]}
+SongRepresenter.new(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`).
@@ -338,7 +367,7 @@ Also, note that [roar-rails](https://github.com/apotonick/roar-rails) allows usi
 Sometimes you need more data in the link block. Data that's not available from the represented model.
 
 ```ruby
-module SongRepresenter
+class SongRepresenter < Roar::Decorator
   include Roar::JSON
 
   property :title
@@ -352,20 +381,36 @@ end
 Pass this data to the rendering method.
 
 ```ruby
-song.to_json(base_url: "localhost:3001/")
+representer = SongRepresenter.new(song)
+representer.to_json(base_url: "localhost:3001/")
 ```
 
 Any options passed to `#to_json` will be available as block arguments in the link blocks.
 
 
+## Specify Decorator
+
+If you have a property that is a separate class or model, you can specify a decorator for that property. Suppose there is a separate `Artist` model for an album. When the album is eagerly loaded, the artist model could be represented along with it.
+
+```ruby
+class ArtistRepresenter < Roar::Decorator
+  property :name
+end
+
+class AlbumRepresenter < Roar::Decorator
+  # ..
+  property :artist, decorator: ArtistRepresenter
+end
+```
+
 ## Consuming Hypermedia
 
 Since we defined hypermedia attributes in the representer we can also consume this hypermedia when we parse documents.
 
 ```ruby
-song.from_json('{"title":"Roxanne","links":[{"rel":"self","href":"http://songs/Roxanne"}]}')
+representer.from_json('{"title":"Roxanne","links":[{"rel":"self","href":"http://songs/Roxanne"}]}')
 
-song.links[:self].href #=> "http://songs/Roxanne"
+representer.links[:self].href #=> "http://songs/Roxanne"
 ```
 
 Reading link attributes works by using `#links[]` on the consuming instance.
@@ -375,7 +420,7 @@ This allows an easy way to discover hypermedia and build navigational logic on t
 
 ## 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.
+While Roar comes with a built-in hypermedia format, there's official media types that are widely recognized. Roar currently supports HAL and JSON API.
 
 Simply by including a module you make your representer understand the media type. This makes it easy to change formats during evaluation.
 
@@ -386,7 +431,7 @@ The [HAL](http://stateless.co/hal_specification.html) format is a simple media t
 ```ruby
 require 'roar/json/hal'
 
-module SongRepresenter
+class SongRepresenter < Roar::Decorator
   include Roar::JSON::HAL
 
   property :title
@@ -397,7 +442,7 @@ module SongRepresenter
 end
 ```
 
-Documentation for HAL can be found in the [API docs](http://rdoc.info/github/apotonick/roar/Roar/JSON/HAL).
+Documentation for HAL can be found in the [API docs](http://rdoc.info/github/trailblazer/roar/Roar/JSON/HAL).
 
 Make sure you [understand the different contexts](#hypermedia) for links when using decorators.
 
@@ -406,7 +451,7 @@ Make sure you [understand the different contexts](#hypermedia) for links when us
 Including the `Roar::JSON::HAL` module adds some more DSL methods to your module. It still allows using `::link` but treats them slightly different.
 
 ```ruby
-song.to_json
+representer.to_json
 #=> {"title":"Roxanne","_links":{"self":{"href":"http://songs/Roxanne"}}}
 ```
 
@@ -419,7 +464,7 @@ Parsing works like-wise: Roar will use the same setters as before but it knows h
 Nested, or embedded, resources can be defined using the `:embedded` option.
 
 ```ruby
-module AlbumRepresenter
+class AlbumRepresenter < Roar::Decorator
   include Roar::JSON::HAL
 
   property :title
@@ -433,187 +478,18 @@ end
 To embed a resource, you can use an inline representer or use `:extend` to specify the representer name.
 
 ```ruby
-album.to_json
+AlbumRepresenter.new(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](http://rdoc.info/github/apotonick/roar/Roar/JSON/HAL), including [array links](https://github.com/apotonick/roar/blob/master/lib/roar/json/hal.rb#L196).
-
-
-## JSON-API
-
-Roar also supports [JSON-API](http://jsonapi.org/) - yay! It can render _and_ parse singular and collection documents.
-
-Note that you need representable >= 2.1.4 in your `Gemfile`.
-
-### Resource
-
-A minimal representation can be defined as follows.
-
-```ruby
-require 'roar/json/json_api'
-
-module SongsRepresenter
-  include Roar::JSON::JSONAPI
-  type :songs
-
-  property :id
-  property :title
-end
-```
-
-Properties of the represented model are defined in the root level.
-
-### Hypermedia
-
-You can add links to `linked` models within the resource section.
-
-```ruby
-module SongsRepresenter
-  # ...
-
-  has_one :composer
-  has_many :listeners
-end
-```
-
-Global `links` can be added using the familiar `::link` method (this is still WIP as the DSL is not final).
-
-```ruby
-module SongsRepresenter
-  # ...
-
-  link "songs.album" do
-    {
-      type: "album",
-      href: "http://example.com/albums/{songs.album}"
-    }
-  end
-end
-```
-
-### Compounds
-
-To add compound models into the document, use `::compound`.
-
-```ruby
-module SongsRepresenter
-  # ...
-
-compound do
-  property :album do
-    property :id
-    property :title
-  end
-
-  collection :musicians do
-    property :name
-  end
-end
-```
-
-### Meta Data
-
-Meta data can be included into the rendered collection document in two ways. Please note that parsing the `meta` field is not implemented, yet, as I wasn't sure if people need it.
-
-You can define meta data on your collection object and then let Roar compile it.
+All HAL features in Roar are discussed in the [API docs](http://rdoc.info/github/trailblazer/roar/Roar/JSON/HAL), including [array links](https://github.com/trailblazer/roar/blob/master/lib/roar/json/hal.rb#L196).
 
-```ruby
-module SongsRepresenter
-  # ..
-
-  meta do
-    property :page
-    property :total
-  end
-```
-
-Your collection object has to expose those methods.
-
-```ruby
-collection.page  #=> 1
-collection.total #=> 12
-```
-
-This will render the `{"meta": {"page": 1, "total": 12}}` hash into the JSON-API document.
-
-Another way is to provide the _complete_ meta data hash when rendering. You must not define any `meta` properties in the representer when using this approach.
-
-```ruby
-collection.to_json("meta" => {page: params["page"], total: collection.size})
-```
-
-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.
-
-```ruby
-SongsRepresenter.prepare(Song.find(1)).to_json
-SongsRepresenter.prepare(Song.new).from_json("..")
-```
-
-Singular models can use the representer module directly.
-
-```ruby
-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.
-
-
-## Collection+JSON
-
-The [Collection+JSON media format](http://amundsen.com/media-types/collection/) 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.
-
-```ruby
-module SongRepresenter
-  include Roar::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.
+## JSON API
 
+Roar also supports [JSON API](http://jsonapi.org/) via the [Roar JSON API gem](https://github.com/trailblazer/roar-jsonapi).
 
 ## Client-Side Support
 
@@ -622,7 +498,7 @@ Being a bi-directional mapper that does rendering _and_ parsing, Roar represente
 Consider the following shared representer.
 
 ```ruby
-module SongRepresenter
+class SongRepresenter < Roar::Decorator
   include Roar::JSON
   include Roar::Hypermedia
 
@@ -639,6 +515,7 @@ In a client where you don't have access to the database it is common to use `Ope
 
 ```ruby
 require 'roar/client'
+require 'roar/json'
 
 class Song < OpenStruct
   include Roar::JSON
@@ -734,7 +611,7 @@ rescue Roar::Transport::Error => exception
 Roar also comes with XML support.
 
 ```ruby
-module SongRepresenter
+class SongRepresenter < Roar::Decorator
   include Roar::XML
   include Roar::Hypermedia
 
@@ -751,9 +628,8 @@ Include the `Roar::XML` engine and get bi-directional XML for your objects.
 
 ```ruby
 song = Song.new(title: "Roxanne", id: 42)
-song.extend(XML::SongRepresenter)
 
-song.to_xml
+SongRepresenter.new(song).to_xml
 ```
 
 Note that you now use `#to_xml` and `#from_xml`.
@@ -766,7 +642,7 @@ Note that you now use `#to_xml` and `#from_xml`.
 </song>
 ```
 
-Please consult the [representable XML documentation](https://github.com/apotonick/representable/#more-on-xml) for all its great features.
+Please consult the [representable XML documentation](https://github.com/trailblazer/representable/#more-on-xml) for all its great features.
 
 
 ## Support