roar 0.12.9 → 1.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bcbcc9501060b58047a296ceab9a48a3dd235251
-  data.tar.gz: 45ada5410ffee101229c7f07edf8bf33f80e5c45
+  metadata.gz: 52b7f8314b58e3ebc06ca5dde920c82d8584b16b
+  data.tar.gz: 005bfc57c05c3a67ed3d7f1a778f1052c5d087c7
 SHA512:
-  metadata.gz: 18f9be695ec8707c8bf5591aa669d6dcc38cc65c0b41eba490f54146298d9284eb7be8afd1dffcd6f121f862b230bce1cd14459d224b4f2ac62003122f7a3bca
-  data.tar.gz: 2d47ba5c28f74c6cc4952db4a298b90ad618a7b6730cfac6286c43773d1a05284fac56bea603f1b310f7752c1b888a7f5a9de12d08bf5d503e25866e186b530a
+  metadata.gz: 9c06fc967e1c3f389e4ad87a144c78b516fc32267dea3bd0d5bacd99b7cc3e102faadeaec32c06dc4887526e74b95b745452210d13042aff727bd238f127f8f4
+  data.tar.gz: 497ac335d8ad6d65df546e8bff9e3c148fd204872d608a48580dce62334f082838f9e213cbaec7dd2c38b2c822073a661796e0c1eae3ebb04206a5a1778262c8

data/.gitignore

@@ -2,3 +2,4 @@ pkg/*
 *.gem
 .bundle
 Gemfile*.lock
+.idea

data/.travis.yml

@@ -1,12 +1,10 @@
-matrix:
-  include:
-    - rvm: 1.9.3
-      gemfile: gemfiles/Gemfile.representable-1.7
-    - rvm: 2.0.0
-      gemfile: gemfiles/Gemfile.representable-1.7
-    - rvm: 1.9.3
-      gemfile: gemfiles/Gemfile.representable-1.8
-    - rvm: 2.0.0
-      gemfile: gemfiles/Gemfile.representable-1.8
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1
+  - 2.2
+gemfiles:
+  - gemfiles/Gemfile.representable-2.0
+  - gemfiles/Gemfile.representable-2.1
 notifications:
   irc: "irc.freenode.org#cells"

data/CHANGES.markdown

@@ -1,6 +1,28 @@
-# 0.12.9
+# 1.0.0
 
-* Very last release in 0.12. Adding support for SSL certs.
+## Breakage
+
+* Removed `Representer` and `Feature` namespace. That means changes along the following.
+    * `Roar::Representer::Feature::Hypermedia` --> `Roar::Hypermedia`
+    * `Roar::Representer::JSON` --> `Roar::JSON`
+* Removed positional arguments for `HttpVerbs#get` and friends.
+
+## 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.
+
+
+## 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.
+* 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`.
+* `Hypermedia` is now 43% simpler.
 
 # 0.12.8
 

data/Gemfile

@@ -3,5 +3,8 @@ source "http://rubygems.org"
 # Specify your gem's dependencies in roar.gemspec
 gemspec
 
-#gem "representable", :path => "../representable"
-gem "sinatra-contrib", :git => "git@github.com:apotonick/sinatra-contrib.git", :branch => "runner"
+gem "representable", "~> 2.1.0"
+# gem "representable", :path => "../representable"
+
+# 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"

data/README.markdown

@@ -8,7 +8,7 @@ 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 comes with built-in JSON, JSON-HAL, JSON-API 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.
 
@@ -24,10 +24,10 @@ If in need for a feature, make sure to check the [representable API docs](https:
 Let's see how representers work. They're fun to use.
 
 ```ruby
-require 'roar/representer/json'
+require 'roar/json'
 
 module SongRepresenter
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   property :title
 end
@@ -81,7 +81,7 @@ Many people dislike `#extend` due to eventual performance issue or object pollut
 require 'roar/decorator'
 
 class SongRepresenter < Roar::Decorator
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   property :title
 end
@@ -107,7 +107,7 @@ Roar (or rather representable) also allows to map collections in documents.
 
 ```ruby
 module SongRepresenter
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   property :title
   collection :composers
@@ -140,7 +140,7 @@ Another representer to represent.
 
 ```ruby
 module AlbumRepresenter
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   property :title
   collection :songs, extend: SongRepresenter, class: Song
@@ -188,7 +188,7 @@ Sometimes you don't wanna create two separate representers - although it makes t
 
 ```ruby
 module AlbumRepresenter
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   property :title
 
@@ -207,7 +207,7 @@ Usually, when parsing, nested objects are created from scratch. If you want nest
 
 ```ruby
 module AlbumRepresenter
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   property :title
 
@@ -235,11 +235,11 @@ We're currently [working on](https://github.com/apotonick/roar/issues/85) better
 Roar provides coercion with the [virtus](https://github.com/solnic/virtus) gem.
 
 ```ruby
-require 'roar/representer/feature/coercion'
+require 'roar/feature/coercion'
 
 module SongRepresenter
-  include Roar::Representer::JSON
-  include Roar::Representer::Feature::Coercion
+  include Roar::JSON
+  include Roar::Coercion
 
   property :title
   property :released_at, type: DateTime
@@ -269,8 +269,8 @@ Roar comes with built-in support for embedding and processing hypermedia in your
 
 ```ruby
 module SongRepresenter
-  include Roar::Representer::JSON
-  include Roar::Representer::Feature::Hypermedia
+  include Roar::JSON
+  include Roar::Hypermedia
 
   property :title
 
@@ -298,7 +298,7 @@ Sometimes you need more data in the link block. Data that's not available from t
 
 ```ruby
 module SongRepresenter
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   property :title
 
@@ -343,10 +343,10 @@ Simply by including a module you make your representer understand the media type
 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'
+require 'roar/json/hal'
 
 module SongRepresenter
-  include Roar::Representer::JSON::HAL
+  include Roar::JSON::HAL
 
   property :title
 
@@ -360,7 +360,7 @@ Documentation for HAL can be found in the [API docs](http://rdoc.info/github/apo
 
 ### 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.
+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
@@ -377,7 +377,7 @@ Nested, or embedded, resources can be defined using the `:embedded` option.
 
 ```ruby
 module AlbumRepresenter
-  include Roar::Representer::JSON::HAL
+  include Roar::JSON::HAL
 
   property :title
 
@@ -397,7 +397,97 @@ album.to_json
 
 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).
+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/json/hal.rb#L176).
+
+
+## JSON-API
+
+Roar also supports [JSON-API](http://jsonapi.org/) - yay! It can render _and_ parse singular and collection documents.
+
+### 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
+```
+
+### 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
@@ -406,7 +496,7 @@ The [Collection+JSON media format](http://amundsen.com/media-types/collection/)
 
 ```ruby
 module SongRepresenter
-  include Roar::Representer::JSON::CollectionJSON
+  include Roar::JSON::CollectionJSON
   version "1.0"
   href { "http://localhost/songs/" }
 
@@ -455,8 +545,8 @@ Consider the following shared representer.
 
 ```ruby
 module SongRepresenter
-  include Roar::Representer::JSON
-  include Roar::Representer::Feature::Hypermedia
+  include Roar::JSON
+  include Roar::Hypermedia
 
   property :title
   property :id
@@ -470,18 +560,18 @@ 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'
+require 'roar/client'
 
 class Song < OpenStruct
-  include Roar::Representer::JSON
+  include Roar::JSON
   include SongRepresenter
-  include Roar::Representer::Feature::Client
+  include Roar::Client
 end
 ```
 
 ## HTTP Support
 
-The `Feature::Client` module mixes all necessary methods into the client class, e.g. it provides HTTP support
+The `Client` module mixes all necessary methods into the client class, e.g. it provides HTTP support
 
 ```ruby
 song = Song.new(title: "Roxanne")
@@ -525,8 +615,22 @@ The HTTP verbs allow you to specify credentials for HTTP basic auth.
 
 ```ruby
 song.get(uri: "http://localhost:4567/songs/1", basic_auth: ["username", "secret_password"])
+
 ```
 
+### Client SSL certificates
+
+(Only currently supported with Net:Http)
+
+```ruby
+song.get(uri: "http://localhost:4567/songs/1", pem_file: "/path/to/client/cert.pem", ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER)
+
+```
+
+Note: ssl_verify_mode is not required and will default to ```OpenSSL::SSL::VERIFY_PEER)```
+
+
+
 ### Request customization
 
 All verbs yield the request object before the request is sent, allowing to modify it. It is a `Net::HTTP::Request` instance (unless you use Faraday).
@@ -544,7 +648,7 @@ Roar also comes with XML support.
 ```ruby
 module SongRepresenter
   include Roar::Representer::XML
-  include Roar::Representer::Feature::Hypermedia
+  include Roar::Representer::Hypermedia
 
   property :title
   property :id
@@ -584,4 +688,4 @@ We also have a [mailing list](https://groups.google.com/forum/?fromgroups#!forum
 
 ## License
 
-Roar is released under the [MIT License](http://www.opensource.org/licenses/MIT).
+Roar is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/TODO.markdown

@@ -1,11 +1,13 @@
+# 1.0
+
+* merge client errors request
+* simpler link for JSON-API?
+* remove HttpVerbs deprecations
+
+* Hyperlink representers => decrators. test hash representer with decorator (rpr)
+
+
 * Add proxies, so nested models can be lazy-loaded.
 * move #prepare_links! call to #_links or something so it doesn't need to be called in #serialize.
-* alias Roar::Representer to Representer
-* remove #before_serialize and just overwrite #serialize
 * abstract ::links_definition_options and move them out of the generic representers (JSON, XML).
-* make 1.8 tests work, again (hash ordering!)
-
-* release 1.0
-* representable 1.8, only.
-* revise Hypermedia
 * work on HAL-Object

data/examples/example.rb

@@ -1,3 +1,5 @@
+#!/usr/bin/env ruby
+
 require 'bundler'
 Bundler.setup
 

data/examples/example_server.rb

@@ -1,3 +1,5 @@
+#!/usr/bin/env ruby
+
 require "bundler/setup"
 require "sinatra"
 require "ostruct"
@@ -9,10 +11,24 @@ get "/method" do
 end
 
 post "/songs" do
-'{"id":"1","title":"Roxanne","links":[{"rel":"self","href":"http://localhost/songs/1"}]}'
+  '{"id":"1","title":"Roxanne","links":[{"rel":"self","href":"http://localhost/songs/1"}]}'
 end
 
 
 get "/songs/1" do
-'{"id":"1","title":"Roxanne","links":[{"rel":"self","href":"http://localhost/songs/1"}]}'
-end
+  '{"id":"1","title":"Roxanne","links":[{"rel":"self","href":"http://localhost/songs/1"}]}'
+end
+
+post "/respond404" do
+  status 404
+  '{"id":"1","title":"Roxanne","links":[{"rel":"self","href":"http://localhost/songs/1"}],"revision":"2"}'
+end
+
+post "/respond407" do
+  status 407
+end
+
+get "/respond200" do
+  status 200
+  '{"id":"1","title":"Roxanne","links":[{"rel":"self","href":"http://localhost/songs/1"},"revision":"3"]}'
+end