roar 0.12.1 → 0.12.2

data/test/test_helper.rb

@@ -42,6 +42,10 @@ MiniTest::Spec.class_eval do
       end
     end
   end
+
+  def self.representer!(*args)
+    representer_for(*args)
+  end
 end
 
 Roar::Representer::Feature::Hypermedia::Hyperlink.class_eval do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: roar
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.12.2
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-27 00:00:00.000000000 Z
+date: 2013-12-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: representable
@@ -135,9 +135,11 @@ files:
 - CHANGES.markdown
 - Gemfile
 - LICENSE
-- README.textile
+- README.markdown
 - Rakefile
 - TODO.markdown
+- examples/example.rb
+- examples/example_server.rb
 - gemfiles/Gemfile.representable-1.5.ruby-1.8
 - gemfiles/Gemfile.representable-1.5.ruby-1.9
 - gemfiles/Gemfile.representable-1.6.ruby-1.9

data/README.textile

@@ -1,331 +0,0 @@
-h1. ROAR
-
-_Resource-Oriented Architectures in Ruby._
-
-h2. Introduction
-
-Roar is a framework for parsing and rendering REST documents. Nothing more.
-
-
-
-coercion
-
-
-With Roar, REST documents - also known as representations - are defined using a new concept called representers. Both syntax and semantics are declared in Ruby modules that can be mixed into your domain models, following clean OOP patterns.
-
-Roar comes with built-in JSON, JSON::HAL and XML support. It exposes a highly modular architecture and makes it very simple to add new media types and functionality where needed. Additional features include client HTTP support, coercion, client-side caching, awesome hypermedia support and more. Representers fit pretty well in DCI environments, too.
-
-Roar is completely framework-agnostic and loves being used in web kits like Rails, Webmachine, Sinatra, Padrino, etc. Actually, Roar makes it fun designing real, hypermedia-driven, and resource-oriented systems that will even make Steve sleep happily at night so he finally gets some REST!
-
-Note: This README sucks and will be updated this week (April 10, 2013).
-
-h2. Example
-
-Say your webshop consists of two completely separated apps. The REST backend, a Sinatra app, serves articles and processes orders. The frontend, being browsed by your clients, is a rich Rails application. It queries the services for articles, renders them nicely and reads or writes orders with REST calls. That being said, the frontend turns out to be a pure REST client.
-
-
-h2. Representations
-
-Representations are the pivotal elements of REST. Work in a REST system means working with representations, which can be put down to parsing or extracting representations and rendering the like.
-
-Roar makes it easy to render and parse representations of resources after defining the formats.
-
-
-h3. Creating Representations
-
-Why not GET a particular article, what about a good beer?
-
-@GET http://articles/lonestarbeer@
-
-It's cheap and it's good. The response of a GET is a representation of the requested resource. A *representation* is always a *document*. In this example, it's a bit of JSON.
-
-pre. { "article": {
-  "title":  "Lonestar Beer",
-  "id":     4711,
-  "links":[
-    { "rel":  "self",
-      "href": "http://articles/lonestarbeer"}
-  ]}
-}
-
-p. In addition to boring article data, there's a _link_ embedded in the document. This is *hypermedia*, yeah! We will learn more about that shortly.
-
-So, how did the service render that JSON document? It could use an ERB template, @#to_json@, or maybe another gem. The document could also be created by a *representer*.
-
-Representers are the key ingredience in Roar, so let's check them out!
-
-
-h2. Representers
-
-Representers are most usable when defined in a module, and then mixed into a host class. In our example, the host class is the article.
-
-<pre>
-class Article
-  attr_accessor :title, :id
-end
-</pre>
-
-To render a representational document from the article, the backend service has to define a representer.
-
-<pre>
-require 'roar/representer/json'
-require 'roar/representer/feature/hypermedia'
-
-
-module ArticleRepresenter
-  include Roar::Representer::JSON
-  include Roar::Representer::Feature::Hypermedia
-
-  property :title
-  property :id
-
-  link :self do
-    article_url(self)
-  end
-end
-</pre>
-
-Hooray, we can define plain properties and embedd links easily - and we can even use URL helpers (in Rails, using the "roar-rails gem":https://github.com/apotonick/roar-rails). There's even more, nesting, collections, but more on that later!
-
-
-h3. Rendering Representations in the Service
-
-In order to *render* an actual document, the backend service would have to do a few steps: creating a representer, filling in data, and then serialize it.
-
-<pre>loney = Article.new.extend(ArticleRepresenter)
-  loney.title = "Lonestar"
-  loney.id    = 666
-  loney.to_json # => "{\"article\":{\"id\":666, ...
-</pre>
-
-Articles itself are useless, so they may be placed into orders. This is the next example.
-
-
-h3. Nesting Representations
-
-What if we wanted to check an existing order? We'd @GET http://orders/1@, right?
-
-<pre>{ "order": {
-  "id":         1,
-  "client_id":  "815",
-  "articles":   [
-    {"title": "Lonestar Beer",
-    "id":     666,
-    "links":[
-      { "rel":  "self",
-        "href": "http://articles/lonestarbeer"}
-    ]}
-  ],
-  "links":[
-    { "rel":  "self",
-      "href": "http://orders/1"},
-    { "rel":  "items",
-      "href": "http://orders/1/items"}
-  ]}
-}
-</pre>
-
-The order model is simple.
-
-<pre>
-class Order
-  attr_accessor :id, :client_id, :articles
-end
-</pre>
-
-Since orders may contain a composition of articles, how would the order service define its representer?
-
-<pre>
-module OrderRepresenter
-  include Roar::Representer::JSON
-  include Roar::Representer::Feature::Hypermedia
-
-  property :id
-  property :client_id
-
-  collection :articles, :class => Article
-
-  link :self do
-    order_url(represented)
-  end
-
-  link :items do
-    items_url
-  end
-end
-</pre>
-
-Representers don't have to be in modules, but can be
-
-The declarative @#collection@ method lets us define compositions of representers.
-
-
-h3. Parsing Documents in the Service
-
-Rendering stuff is easy: Representers allow defining the layout and serializing documents for us. However, representers can do more. They work _bi-directional_ in terms of rendering outgoing _and_ parsing incoming representation documents.
-
-If we were to implement an endpoint for creating new orders, we'd allow POST to @http://orders/@. Let's explore the service code for parsing and creation.
-
-<pre>
-  post "/orders" do
-    order = Order.new.extend(OrderRepresenter)
-    order.from_json(request.body.string)
-    order.to_json
-  end
-</pre>
-
-Look how the @#from_json@ method helps extracting data from the incoming document and, again, @#to_json@ returns the freshly created order's representation. Roar's representers are truely working in both directions, rendering and parsing and thus prevent you from redundant knowledge sharing.
-
-
-h2. Representers in the Client
-
-The new representer abstraction layer seems complex and irritating first, where you used @params[]@ and @#to_json@ is a new OOP instance now. But... the cool thing is: You can package representers in gems and distribute them to your client layer as well. In our example, the web frontend can take advantage of the representers, too.
-
-
-h3. Using HTTP
-
-Communication between REST clients and services happens via HTTP - clients request, services respond. There are plenty of great gems helping out, namely Restfulie, HTTParty, etc. Representers in Roar provide support for HTTP as well, given you mix in the @HTTPVerbs@ feature module!
-
-To create a new order, the frontend needs to POST to the REST backend. Here's how this could happen using a representer on HTTP.
-
-
-<pre>
-  order = Order.new(:client_id => current_user.id)
-  order.post("http://orders/")
-</pre>
-
-A couple of noteworthy steps happen here.
-
-# Using the constructor a blank order document is created.
-# Initial values like the client's id are passed as arguments and placed in the document.
-# The filled-out document is POSTed to the given URL.
-# The backend service creates an actual order record and sends back the representation.
-# In the @#post@ call, the returned document is parsed and attributes in the representer instance are updated accordingly,
-
-After the HTTP roundtrip, the order instance keeps all the information we need for proceeding the ordering workflow.
-
-<pre>
-  order.id #=> 42
-</pre>
-
-h3. Discovering Hypermedia
-
-Now that we got a fresh order, let's place some items! The system's API allows adding articles to an existing order by POSTing articles to a specific resource. This endpoint is propagated in the order document using *hypermedia*.
-
-Where and what is this hypermedia?
-
-First, check the JSON document we get back from the POST.
-
-<pre>{ "order": {
-  "id":         42,
-  "client_id":  1337,
-  "articles":   [],
-  "links":[
-    { "rel":  "self",
-      "href": "http://orders/42"},
-    { "rel":  "items",
-      "href": "http://orders/42/items"}
-  ]}
-}
-</pre>
-
-Two hypermedia links are embedded in this representation, both feature a @rel@ attribute for defining a link semantic - a "meaning" - and a @href@ attribute for a network address. Isn't that great?
-
-* The @self@ link refers to the actual resource. It's a REST best practice and representations should always refer to their resource address.
-* The @items@ link is what we want. The address @http://orders/42/items@ is what we have to refer to when adding articles to this order. Why? Cause we decided that!
-
-
-h3. Using Hypermedia
-
-Let the frontend add the delicious "Lonestar" beer to our order, now!
-
-<pre>
-beer = Article.new(:title => "Lonestar Beer")
-beer.post(order.links[:items])
-</pre>
-
-That's all we need to do.
-
-# First, we create an appropriate article representation.
-# Then, the @#links@ method helps extracting the @items@ link URL from the order document.
-# A simple POST to the respective address places the item in the order.
-
-The @order@ instance in the frontend is now stale - it doesn't contain articles, yet, since it is still the document from the first post to @http://orders/@.
-
-<pre>
-order.items #=> []
-</pre>
-
-To update attributes, a GET is needed.
-
-<pre>
-order.get!(order.links[:self])
-</pre>
-
-Again, we use hypermedia to retrieve the order's URL. And now, the added article is included in the order.
-
-[*Note:* If this looks clumsy - It's just the raw API for representers. You might be interested in the upcoming DSL that simplifys frequent workflows as updating a representer.]
-
-<pre>
-order.to_attributes #=> {:id => 42, :client_id => 1337,
-  :articles => [{:title => "Lonestar Beer", :id => 666}]}
-</pre>
-
-This is cool, we used REST representers and hypermedia to create an order and fill it with articles. It's time for a beer, isn't it?
-
-
-h3. Using Accessors
-
-What if the ordering API is going a different way? What if we had to place articles into the order document ourselves, and then PUT this representation to @http://orders/42@? No problem with representers!
-
-Here's what could happen in the frontend.
-
-<pre>
-beer = Article.new(:title => "Lonestar Beer")
-order.items << beer
-order.post(order.links[:self])
-</pre>
-
-This was dead simple since representations can be composed of different documents in Roar.
-
-h2. Decorators
-
-You can use `Roar::Decorator` as a representer. More docs coming soon. Note that if you want your represented object to save incoming hypermedia you need to do two things.
-
-<pre>
-class SongClient
-  # do whatever here
-
-  attr_accessor :links
-end
-
-class SongRepresenter < Roar::Decorator
-  include Roar::Representer::JSON
-  include Roar::Decorator::HypermediaConsumer
-end
-</pre>
-
-
-h2. More Features
-
-Be sure to check out the bundled features.
-
-# *Coercion* transforms values to typed objects when parsing a document. Uses virtus.
-# *Faraday* support, if you want to use it install the Faraday gem and require 'roar/representer/transport/faraday' and configure 'Roar::Representer::Feature::HttpVerbs.transport_engine = Roar::Representer::Transport::Faraday'
-
-h2. What is REST about?
-
-Making that system RESTful basically means
-
-# The frontend knows one _single entry point_ URL to the REST services. This is @http://orders@.
-# Do _not_ let the frontend compute any URLs to further actions.
-# Showing articles, creating a new order, adding articles to it and finally placing the order - this all requires further URLs. These URLs are embedded as _hypermedia_ in the representations sent by the REST backend.
-
-h2. 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!
-
-h2. License
-
-Roar is released under the "MIT License":http://www.opensource.org/licenses/MIT.