roar 1.0.2 → 1.1.1

data/README.markdown

@@ -1,8 +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)
+[![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
 
@@ -10,21 +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.
-
-<a href="https://leanpub.com/trailblazer">
-![](https://raw.githubusercontent.com/apotonick/trailblazer/master/doc/trb.jpg)
-</a>
-
-Roar is part of the [Trailblazer project](https://github.com/apotonick/trailblazer). Please [buy the book](https://leanpub.com/trailblazer) to support the development. Several chapters will be dedicated to Roar, its integration into operations, hypermedia formats and client-side usage.
+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,17 +67,23 @@ The roar gem runs with all Ruby versions >= 1.9.3.
 gem 'roar'
 ```
 
+To use roar with Ruby versions < 2.2.0, add a version pin to your Gemfile:
+
+```ruby
+gem 'sinatra', '~> 1.4'
+```
+
 ### Dependencies
 
 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'
@@ -56,21 +95,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
 ```
 
@@ -79,66 +119,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
+## Module Representers
 
-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 are deprecated in Roar 1.1 and will be removed in Roar 2.0.**
 
-```ruby
-require 'roar/decorator'
+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.
 
-class SongRepresenter < Roar::Decorator
-  include Roar::JSON
-
-  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.
+
+```ruby
+song = Song.new
+song.extend(SongRepresenter)
+
+song.from_json('{"title":"Fate"}')
+song #=> {"title":"Fate"}
+```
 
-However, in this README we'll use modules to illustrate this framework.
+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
@@ -150,9 +186,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.
@@ -163,7 +198,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
 ```
@@ -171,7 +206,7 @@ end
 Another representer to represent.
 
 ```ruby
-module AlbumRepresenter
+class AlbumRepresenter < Roar::Decorator
   include Roar::JSON
 
   property :title
@@ -188,38 +223,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
@@ -238,7 +270,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
@@ -252,14 +284,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
@@ -268,8 +300,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
 
@@ -282,9 +315,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
 ```
@@ -292,7 +324,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
@@ -300,7 +332,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
 
@@ -328,8 +360,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`).
@@ -342,7 +373,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
@@ -356,20 +387,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.
@@ -379,7 +426,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.
 
@@ -390,7 +437,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
@@ -401,7 +448,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.
 
@@ -410,7 +457,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"}}}
 ```
 
@@ -423,7 +470,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
@@ -437,187 +484,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).
+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).
 
+## JSON API
 
-## 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.
-
-```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.
-
+Roar also supports [JSON API](http://jsonapi.org/) via the [Roar JSON API gem](https://github.com/trailblazer/roar-jsonapi).
 
 ## Client-Side Support
 
@@ -626,7 +504,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
 
@@ -643,6 +521,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
@@ -738,7 +617,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
 
@@ -755,9 +634,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`.
@@ -770,7 +648,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