roar 0.12.1 → 0.12.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 29d7b45c0c70d694a009c07d504cdb64527a67dd
-  data.tar.gz: 3b4e5c1d025541be5de8e5b0df42cf01052f843a
+  metadata.gz: 04161ea9b3e943c2369825c6a3c426cfae97550d
+  data.tar.gz: f7a7a96c45646273d7355938becde08c0549d8b1
 SHA512:
-  metadata.gz: b9e45c7ec240bce207c05a8165fd03d8a35c770ee60a643c5fe07a5feff5e99ab646b3873efa619e3d732cb9aec9a079d7aa843ac685de3ec75cd50c0f20dca5
-  data.tar.gz: cfde908ba1165bb30fa43dc8a22b8d5de7bff6092ccf38d0eb906bd4ff04ca170a44726a9a3ff597e91c8a41deea83cd29d4eac6edcc8b48c509d6cce8b7dba5
+  metadata.gz: 766eddbf40e6931caaf003a895598799c1d40efea0ba4854a1938995c0a7c0a41b96cfe1e69593c9a89538b9426305aff2f34dcd617a60a95f14840398296e54
+  data.tar.gz: ec8585e4bc27fb429895db8d2026c70aade0b360d5b6d741d4d67c7eddc0306194947514061f8f1fe6361822ddceb5e1370b6ff671430c9628b5af5781c791e4

data/CHANGES.markdown

@@ -1,3 +1,7 @@
+# 0.12.2
+
+* Fix a bug where hyperlinks from nested objects weren't rendered in XML.
+
 # 0.12.1
 
 Allow representable >= 1.6.

data/README.markdown

@@ -0,0 +1,559 @@
+# 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](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.
+
+If in need for a feature, make sure to check the [representable API docs](https://github.com/apotonick/representable) first.
+
+
+## Defining Representers
+
+Let's see how representers work. They're fun to use.
+
+```ruby
+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.
+
+```ruby
+class Song < ActiveRecord
+end
+```
+
+## Rendering
+
+To render a document, you apply the representer to your model.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+module SongRepresenter
+  include Roar::Representer::JSON
+
+  property :title
+  collection :composers
+end
+```
+
+Where `::property` knows how to handle plain attributes, `::collection` does lists.
+
+```ruby
+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.
+
+```ruby
+class Album < ActiveRecord
+  has_many :songs
+end
+```
+
+Another representer to represent.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+album.extend(AlbumRepresenter)
+
+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"}]}')
+
+puts album.songs[1] #=> #<Song title="Roadblock">
+```
+
+The nesting of two representers can map composed object as you find them in many many APIs.
+
+
+## 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
+  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:`.
+
+```ruby
+module AlbumRepresenter
+  include Roar::Representer::JSON
+
+  property :title
+
+  collection :songs, extend: SongRepresenter, parse_strategy: :sync
+end
+```
+
+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"}]}')
+
+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.
+
+
+## Coercion
+
+Roar provides coercion with the [virtus](https://github.com/solnic/virtus) gem.
+
+```ruby
+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.
+
+```ruby
+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](https://github.com/apotonick/representable/#aliasing), [wrapping](https://github.com/apotonick/representable/#wrapping), [passing options](https://github.com/apotonick/representable/#passing-options), etc.
+
+
+## Hypermedia
+
+Roar comes with built-in support for embedding and processing hypermedia in your documents.
+
+```ruby
+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.
+
+```ruby
+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](https://github.com/apotonick/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.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+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](http://stateless.co/hal_specification.html) format is a simple media type that defines embedded resources and hypermedia.
+
+```ruby
+require 'roar/representer/json/hal'
+
+module SongRepresenter
+  include Roar::Representer::JSON::HAL
+
+  property :title
+
+  link :self do
+    "http://songs/#{title}"
+  end
+end
+```
+
+### 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.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+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/Representer/JSON/HAL), including [array links](https://github.com/apotonick/roar/blob/master/lib/roar/representer/json/hal.rb#L176).
+
+
+## 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::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.
+
+```ruby
+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.
+
+```ruby
+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
+
+```ruby
+song = Song.new(title: "Roxanne")
+song.post("http://localhost:4567/songs", "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 included `SongRepresenter` 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`.
+
+```ruby
+song = Client::Song.new
+song.get("http://localhost:4567/songs/1", "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.
+
+
+## XML
+
+Roar also comes with XML support.
+
+```ruby
+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.
+
+```ruby
+song = Song.new(title: "Roxanne", id: 42)
+song.extend(XML::SongRepresenter)
+
+song.to_xml
+```
+
+Note that you now use `#to_xml` and `#from_xml`.
+
+```xml
+<song>
+  <title>Roxanne</title>
+  <id>42</id>
+  <link rel="self" href="http://songs/Roxanne"/>
+</song>
+```
+
+Please consult the [representable XML documentation](https://github.com/apotonick/representable/#more-on-xml) for all its great features.
+
+
+## Support
+
+Questions? Need help? Free 1st Level Support on irc.freenode.org#roar !
+We also have a [mailing list](https://groups.google.com/forum/?fromgroups#!forum/roar-talk), yiha!
+
+## License
+
+Roar is released under the [MIT License](http://www.opensource.org/licenses/MIT).