oat 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 265248fecbfa3adf9fae15b6c9124a452fe8f285
+  data.tar.gz: aac3cc104b933d261d8f8ca858e038e5e7cef835
+SHA512:
+  metadata.gz: 29f80fbffde75401c81cf69de1f59a5f1091d173abddf404c902ce90ada9c8060b950cfd56a3cc713daf5e961cac417376eb8e68d8ebeae169bfa5bfcbb9a2e9
+  data.tar.gz: fa5ecb844b738eed0344bc513ae083f2928e40eef0099c3e8bd282d0b466e1727cd23598577eb080977a06050e3d6c58764b387d2b5be0565683fea9d51a9985

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.0.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in oat.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Ismael Celis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Ismael Celis
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,510 @@
+# Oat [![Build Status](https://travis-ci.org/ismasan/oat.png)](https://travis-ci.org/ismasan/oat)
+
+Adapters-based API serializers with Hypermedia support for Ruby apps.
+
+## What
+
+Oat lets you design your API payloads succinctly while conforming to your *media type* of choice (hypermedia or not). 
+The details of the media type are dealt with by pluggable adapters.
+
+Oat ships with adapters for HAL, Siren and JsonAPI, and it's easy to write your own.
+
+## Serializers
+
+A serializer describes one or more of your API's *entities*.
+
+You extend from [Oat::Serializer](https://github.com/ismasan/oat/blob/master/lib/oat/serializer.rb) to define your own serializers.
+
+```ruby
+require 'oat/adapters/hal'
+class ProductSerializer < Oat::Serializer
+  adapter Oat::Adapters::HAL
+
+  schema do
+    type "product"
+    link :self, href: product_url(item)
+    properties do |props|
+      props.title item.title
+      props.price item.price
+      props.description item.blurb
+    end
+  end
+
+end
+```
+
+Then in your app (for example a Rails controller)
+
+```ruby
+product = Product.find(params[:id])
+render json: ProductSerializer.new(product)
+```
+
+Serializers require a single object as argument, which can be a model instance, a presenter or any other domain object.
+
+The full serializer signature is `item`, `context`, `adapter_class`.
+
+* `item` a model or presenter instance. It is available in your serializer's schema as `item`.
+* `context` (optional) a context object or hash that is passed to the serializer and sub-serializers as the `context` variable. Useful if you need to pass request-specific data.
+* `adapter_class` (optional) A serializer's adapter can be configured at class-level or passed here to the initializer. Useful if you want to switch adapters based on request data. More on this below.
+
+## Adapters
+
+Using the included [HAL](http://stateless.co/hal_specification.html) adapter, the `ProductSerializer` above would render the following JSON:
+
+```json
+{
+    "_links": {
+        "self": {"href": "http://example.com/products/1"}
+    },
+    "title": "Some product",
+    "price": 1000,
+    "description": "..."
+}
+```
+
+You can easily swap adapters. The same `ProductSerializer`, this time using the [Siren](https://github.com/kevinswiber/siren) adapter:
+
+```ruby
+adapter Oat::Adapters::Siren
+```
+
+... Renders this JSON:
+
+```json
+{
+    "class": ["product"],
+    "links": [
+        { "rel": [ "self" ], "href": "http://example.com/products/1" }
+    ],
+    "properties": {
+        "title": "Some product",
+        "price": 1000,
+        "description": "..."
+    }
+}
+```
+At the moment Oat ships with adapters for [HAL](http://stateless.co/hal_specification.html), [Siren](https://github.com/kevinswiber/siren) and [JsonAPI](http://jsonapi.org/), but it's easy to write your own.
+
+Note: Oat adapters are not *required* by default. Your code should explicitely require the ones it needs:
+
+```ruby
+# HAL
+require 'oat/adapters/hal'
+# Siren
+require 'oat/adapters/siren'
+# JsonAPI
+require 'oat/adapters/json_api'
+```
+
+## Switching adapters dynamically
+
+Adapters can also be passed as an argument to serializer instances.
+
+```ruby
+ProductSerializer.new(product, nil, Oat::Adapters::HAL)
+```
+
+That means that your app could switch adapters on run time depending, for example, on the request's `Accept` header or anything you need.
+
+Note: a different library could be written to make adapter-switching auto-magical for different frameworks, for example using [Responders](http://api.rubyonrails.org/classes/ActionController/Responder.html) in Rails.
+
+## Nested serializers
+
+It's common for a media type to include "embedded" entities within a payload. For example an `account` entity may have many `users`. An Oat serializer can inline such relationships:
+
+```ruby
+class AccountSerializer < Oat::Serializer
+  adapter Oat::Adapters::HAL
+
+  schema do
+    property :id, item.id
+    property :status, item.status
+    # user entities
+    entities :users, item.users do |user, user_serializer|
+      user_serializer.name user.name
+      user_serializer.email user.email
+    end
+  end
+end
+```
+
+Another, more reusable option is to use a nested serializer. Instead of a block, you pass another serializer class that will handle serializing `user` entities.
+
+```ruby
+class AccountSerializer < Oat::Serializer
+  adapter Oat::Adapters::HAL
+
+  schema do
+    property :id, item.id
+    property :status, item.status
+    # user entities
+    entities :users, item.users, UserSerializer
+  end
+end
+```
+
+And the `UserSerializer` may look like this:
+
+```ruby
+class UserSerializer < Oat::Serializer
+  adapter Oat::Adapters::HAL
+
+  schema do
+    property :name, item.name
+    property :email, item.name
+  end
+end
+```
+
+In the user serializer, `item` refers to the user instance being wrapped by the serializer.
+
+The bundled hypermedia adapters ship with an `entities` method to add arrays of entities, and an `entity` method to add a single entity.
+
+```ruby
+# single entity
+entity :child, item.child do |child, s|
+  s.name child.name
+  s.id child.id
+end
+
+# list of entities
+entities :children, item.children do |child, s|
+  s.name child.name
+  s.id child.id
+end
+```
+
+Both can be expressed using a separate serializer:
+
+```ruby
+# single entity
+entity :child, item.child, ChildSerializer
+
+# list of entities
+entities :children, item.children, ChildSerializer
+```
+
+The way sub-entities are rendered in the final payload is up to the adapter. In HAL the example above would be:
+
+```json
+{
+  ...,
+  "_embedded": {
+    "child": {"name": "child's name", "id": 1},
+    "children": [
+      {"name": "child 2 name", "id": 2},
+      {"name": "child 3 name", "id": 3},
+      ...
+    ]
+  }
+}
+```
+
+## Subclassing
+
+Serializers can be subclassed, for example if you want all your serializers to share the same adapter or add shared helper methods.
+
+```ruby
+class MyAppSerializer < Oat::Serializer
+  adapter Oat::Adapters::HAL
+
+  protected
+
+  def format_price(price)
+    Money.new(price, 'GBP').format
+  end
+end
+```
+
+```ruby
+class ProductSerializer < MyAppSerializer
+  schema do
+    property :title, item.title
+    property :price, format_price(item.price)
+  end
+end
+```
+
+This is useful if you want your serializers to better express your app's domain. For example, a serializer for a social app:
+
+```ruby
+class UserSerializer < SocialSerializer
+  schema do
+    name item.name
+    email item.email
+    # friend entities
+    friends item.friends
+  end
+end
+```
+
+The superclass defines the methods `name`, `email` and `friends`, which in turn delegate to the adapter's setters.
+
+```ruby
+class SocialSerializer < Oat::Serializer
+  adapter Oat::Adapters::HAL # or whatever
+
+  # friendly setters
+  protected
+
+  def name(value)
+    property :name, value
+  end
+
+  def email(value)
+    property :email, value
+  end
+
+  def friends(objects)
+    entities :friends, objects, FriendSerializer
+  end
+end
+```
+
+## URLs
+
+Hypermedia is all about the URLs linking your resources together. Oat adapters can have methods to declare links in your entity schemae but it's up to your code/framework how to create those links.
+A simple stand-alone implementation could be:
+
+```ruby
+class ProductSerializer < Oat::Serializer
+  adapter Oat::Adapters::HAL
+
+  schema do
+    link :self, href: product_url(item.id)
+    ...
+  end
+
+  protected
+  
+  # helper URL method
+  def product_url(id)
+    "https://api.com/products/#{id}"
+  end
+end
+```
+
+In frameworks like Rails, you'll probably want to use the URL helpers created by the `routes.rb` file. Two options:
+
+### Pass a context object to serializers
+
+You can pass a context object as second argument to serializers. This object will be passed to nested serializers too. For example, you can pass the controller instance itself.
+
+```ruby
+# users_controller.rb
+
+def show
+  user = User.find(params[:id])
+  render json: UserSerializer.new(user, self)
+end
+```
+
+Then, in the `UserSerializer`:
+```ruby
+class ProductSerializer < Oat::Serializer
+  adapter Oat::Adapters::HAL
+
+  schema do
+    # `context` is the controller, which responds to URL helpers.
+    link :self, href: context.product_url(item)
+    ...
+  end
+end
+```
+
+### Mixin Rails' routing module
+
+Alternatively, you can mix in Rails routing helpers directly into your serializers.
+
+```ruby
+class MyAppParentSerializer < Oat::Serializer
+  include ActionDispatch::Routing::UrlFor
+  include Rails.application.routes.url_helpers
+  def self.default_url_options
+    Rails.application.routes.default_url_options
+  end
+
+  adapter Oat::Adapters::HAL
+end
+```
+
+Then your serializer sub-classes can just use the URL helpers
+
+```ruby
+class ProductSerializer < MyAppParentSerializer
+  schema do
+    # `product_url` is mixed in from Rails' routing system.
+    link :self, href: product_url(item)
+    ...
+  end
+end
+```
+
+However, since serializers don't have access to the current request, for this to work you must configure each environment's base host. In `config/environments/production.rb`:
+
+```ruby
+config.after_initialize do
+  Rails.application.routes.default_url_options[:host] = 'api.com'
+end
+```
+
+NOTE: Rails URL helpers could be handled by a separate oat-rails gem.
+
+## Custom adapters.
+
+An adapter's primary concern is to abstract away the details of specific media types.
+
+Methods defined in an adapter are exposed as `schema` setters in your serializers. 
+Ideally different adapters should expose the same methods so your serializers can switch adapters without loosing compatibility. For example all bundled adapters expose the following methods:
+
+* `type` The type of the entity. Renders as "class" in Siren, root node name in JsonAPI, not used in HAL.
+* `link` Add a link with `rel` and `href`. Renders inside "_links" in HAL, "links" in Siren and JsonAP.
+* `property` Add a property to the entity. Top level attributes in HAL and JsonAPI, "properties" node in Siren.
+* `properties` Yield a properties object to set many properties at once.
+* `entity` Add a single sub-entity. "_embedded" node in HAL, "entities" in Siren, "linked" in JsonAPI.
+* `entities` Add a collection of sub-entities.
+
+You can define these in your own custom adapters if you're using your own media type or need to implement a different spec.
+
+```ruby
+class CustomAdapter < Oat::Adapter
+
+  def type(*types)
+    data[:rel] = types
+  end
+
+  def property(name, value)
+    data[:attr][name] = value
+  end
+
+  def entity(name, obj, serializer_class = nil, &block)
+    data[:nested_documents] = serializer_from_block_or_class(obj, serializer_class, &block)
+  end
+
+  ... etc
+end
+```
+
+An adapter class provides a `data` object (just a Hash) that stores your data in the structure you want. An adapter's public methods are exposed to your serializers.
+
+## Unconventional or domain specific adapters
+
+Although adapters should in general comply with a common interface, you can still create your own domain-specific adapters if you need to.
+
+Let's say you're working on a media-type specification specializing in describing social networks and want your payload definitions to express the concept of "friendship". You want your serializers to look like:
+
+```ruby
+class UserSerializer < Oat::Serializer
+  adapter SocialAdapter
+
+  schema do
+    name item.name
+    email item.email
+
+    # Friend entity
+    friends item.friends do |friend, friend_serializer|
+      friend_serializer.name friend.name
+      friend_serializer.email friend.email
+    end
+  end
+end
+```
+
+A custom media type could return JSON looking looking like this:
+
+```json
+{
+    "name": "Joe",
+    "email": "joe@email.com",
+    "friends": [
+        {"name": "Jane", "email":"jane@email.com"},
+        ...
+    ]
+}
+```
+
+The adapter for that would be:
+
+```ruby
+class SocialAdapter < Oat::Adapter
+
+  def name(value)
+    data[:name] = value
+  end
+
+  def email(value)
+    data[:email] = value
+  end
+
+  def friends(friend_list, serializer_class = nil, &block)
+    data[:friends] = friend_list.map do |obj|
+      serializer_from_block_or_class(obj, serializer_class, &block)
+    end
+  end
+end
+```
+
+But you can easily write an adapter that turns your domain-specific serializers into HAL-compliant JSON.
+
+```ruby
+class SocialHalAdapter < Oat::Adapters::HAL
+
+  def name(value)
+    property :name, value
+  end
+
+  def email(value)
+    property :email, value
+  end
+
+  def friends(friend_list, serializer_class = nil, &block)
+    entities :friends, friend_list, serializer_class, &block
+  end
+end
+```
+
+The result for the SocialHalAdapter is:
+
+```json
+{
+    "name": "Joe",
+    "email": "joe@email.com",
+    "_embedded": {
+        "friends": [
+            {"name": "Jane", "email":"jane@email.com"},
+            ...
+        ]
+    }
+}
+```
+
+You can take a look at [the built-in Hypermedia adapters](https://github.com/ismasan/oat/tree/master/lib/oat/adapters) for guidance.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'oat'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install oat
+
+## TODO / contributions welcome
+
+* Siren actions.
+* JsonAPI URL and ID modes, top-level links
+* testing module that can be used for testing spec-compliance in user apps?
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/oat/adapter.rb

@@ -0,0 +1,36 @@
+require 'oat/props'
+module Oat
+  class Adapter
+
+    def initialize(serializer)
+      @serializer = serializer
+      @data = Hash.new{|h,k| h[k] = {}}
+    end
+
+    def to_hash
+      data
+    end
+
+    protected
+
+    attr_reader :data, :serializer
+
+    def yield_props(&block)
+      props = Props.new
+      serializer.instance_exec(props, &block)
+      props.to_hash
+    end
+
+    def serializer_from_block_or_class(obj, serializer_class = nil, &block)
+      if block_given?
+        serializer_class = Class.new(serializer.class)
+        serializer_class.adapter self.class
+        s = serializer_class.new(obj, serializer.context, serializer.adapter_class, serializer.top)
+        serializer.top.instance_exec(obj, s, &block)
+        s.to_hash
+      else
+        serializer_class.new(obj, serializer.context, serializer.adapter_class).to_hash
+      end
+    end
+  end
+end

data/lib/oat/adapters/hal.rb

@@ -0,0 +1,29 @@
+# http://stateless.co/hal_specification.html
+module Oat
+  module Adapters
+    class HAL < Oat::Adapter
+      def link(rel, opts = {})
+        data[:_links][rel] = opts
+      end
+
+      def properties(&block)
+        data.merge! yield_props(&block)
+      end
+
+      def property(key, value)
+        data[key] = value
+      end
+
+      def entity(name, obj, serializer_class = nil, &block)
+        data[:_embedded][name] = serializer_from_block_or_class(obj, serializer_class, &block)
+      end
+
+      def entities(name, collection, serializer_class = nil, &block)
+        data[:_embedded][name] = collection.map do |obj|
+          serializer_from_block_or_class(obj, serializer_class, &block)
+        end
+      end
+
+    end
+  end
+end

data/lib/oat/adapters/json_api.rb

@@ -0,0 +1,62 @@
+# http://jsonapi.org/format/#url-based-json-api
+require 'active_support/core_ext/string/inflections'
+module Oat
+  module Adapters
+    class JsonAPI < Oat::Adapter
+
+      def initialize(*args)
+        super
+        @entities = {}
+      end
+
+      def type(*types)
+        @root_name = types.first.to_s
+      end
+
+      def link(rel, opts = {})
+        data[:links][rel] = opts[:href]
+      end
+
+      def properties(&block)
+        data.merge! yield_props(&block)
+      end
+
+      def property(key, value)
+        data[key] = value
+      end
+
+      def entity(name, obj, serializer_class = nil, &block)
+        ent = entity_without_root(obj, serializer_class, &block)
+        link name, href: ent[:id]
+        (@entities[name.to_s.pluralize.to_sym] ||= []) << ent
+      end
+
+      def entities(name, collection, serializer_class = nil, &block)
+        link_name = name.to_s.pluralize.to_sym
+        data[:links][link_name] = []
+
+        collection.each do |obj|
+          ent = entity_without_root(obj, serializer_class, &block)
+          data[:links][link_name] << ent[:id]
+          (@entities[link_name] ||= []) << ent
+        end
+      end
+
+      def to_hash
+        raise "JSON API entities MUST define a type. Use type 'user' in your serializers" unless root_name
+        h = {root_name.pluralize.to_sym => [data]}
+        h[:linked] = @entities if @entities.keys.any?
+        h
+      end
+
+      protected
+
+      attr_reader :root_name
+
+      def entity_without_root(obj, serializer_class = nil, &block)
+        serializer_from_block_or_class(obj, serializer_class, &block).values.first.first
+      end
+
+    end
+  end
+end

data/lib/oat/adapters/siren.rb

@@ -0,0 +1,40 @@
+# https://github.com/kevinswiber/siren
+module Oat
+  module Adapters
+    class Siren < Oat::Adapter
+
+      def initialize(*args)
+        super
+        data[:links] = []
+        data[:entities] = []
+      end
+
+      def type(*types)
+        data[:class] = types
+      end
+
+      def link(rel, opts = {})
+        data[:links] << {rel: [rel]}.merge(opts)
+      end
+
+      def properties(&block)
+        data[:properties].merge! yield_props(&block)
+      end
+
+      def property(key, value)
+        data[:properties][key] = value
+      end
+
+      def entity(name, obj, serializer_class = nil, &block)
+        data[:entities] << serializer_from_block_or_class(obj, serializer_class, &block)
+      end
+
+      def entities(name, collection, serializer_class = nil, &block)
+        collection.each do |obj|
+          entity name, obj, serializer_class, &block
+        end
+      end
+
+    end
+  end
+end

data/lib/oat/props.rb

@@ -0,0 +1,21 @@
+module Oat
+  class Props < BasicObject
+
+    def initialize
+      @attributes = {}
+    end
+
+    def _from(data)
+      @attributes = data.to_hash
+    end
+
+    def method_missing(name, value)
+      @attributes[name] = value
+    end
+
+    def to_hash
+      @attributes
+    end
+
+  end
+end

data/lib/oat/serializer.rb

@@ -0,0 +1,50 @@
+require 'active_support/core_ext/class/attribute'
+module Oat
+  class Serializer
+
+    class_attribute :_adapter, :logger
+
+    def self.schema(&block)
+      @schema = block if block_given?
+      @schema || Proc.new{}
+    end
+
+    def self.adapter(adapter_class = nil)
+      self._adapter = adapter_class if adapter_class
+      self._adapter
+    end
+
+    def self.warn(msg)
+      logger ? logger.warning(msg) : puts(msg)
+    end
+
+    attr_reader :item, :context, :adapter_class, :adapter
+
+    def initialize(item, context = nil, _adapter_class = nil, parent_serializer = nil)
+      @item, @context = item, context
+      @parent_serializer = parent_serializer
+      @adapter_class = _adapter_class || self.class.adapter
+      @adapter = @adapter_class.new(self)
+    end
+
+    def top
+      @top ||= @parent_serializer || self
+    end
+
+    def method_missing(name, *args, &block)
+      if adapter.respond_to?(name)
+        adapter.send(name, *args, &block)
+      else
+        self.class.warn "[#{adapter.class}] does not implement ##{name}. Called with #{args}"
+      end
+    end
+
+    def to_hash
+      @to_hash ||= (
+        self.instance_eval &self.class.schema
+        adapter.to_hash
+      )
+    end
+
+  end
+end

data/lib/oat/version.rb

@@ -0,0 +1,3 @@
+module Oat
+  VERSION = "0.0.1"
+end

data/lib/oat.rb

@@ -0,0 +1,6 @@
+require "oat/version"
+
+module Oat
+  require 'oat/serializer'
+  require 'oat/adapter'
+end

data/oat.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'oat/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "oat"
+  spec.version       = Oat::VERSION
+  spec.authors       = ["Ismael Celis"]
+  spec.email         = ["ismaelct@gmail.com"]
+  spec.description   = %q{Oat helps you separate your API schema definitions from the underlying media type. Media types can be plugged or swapped on demand globally or on the content-negotiation phase}
+  spec.summary       = %q{Adapters-based serializers with Hypermedia support}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport", ">= 4.0"
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/spec/adapters/hal_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+require 'oat/adapters/hal'
+
+describe Oat::Adapters::HAL do
+
+  include Fixtures
+
+  subject{ serializer_class.new(user, {name: 'some_controller'}, Oat::Adapters::HAL) }
+
+  describe '#to_hash' do
+    it 'produces a HAL-compliant hash' do
+      subject.to_hash.tap do |h|
+        # properties
+        h[:id].should == user.id
+        h[:name].should == user.name
+        h[:age].should == user.age
+        h[:controller_name].should == 'some_controller'
+        # links
+        h[:_links][:self][:href].should == "http://foo.bar.com/#{user.id}"
+        # embedded manager
+        h[:_embedded][:manager].tap do |m|
+          m[:id].should == manager.id
+          m[:name].should == manager.name
+          m[:age].should  == manager.age
+          m[:_links][:self][:href].should == "http://foo.bar.com/#{manager.id}"
+        end
+        # embedded friends
+        h[:_embedded][:friends].size.should == 1
+        h[:_embedded][:friends][0].tap do |f|
+          f[:id].should == friend.id
+          f[:name].should == friend.name
+          f[:age].should == friend.age
+          f[:controller_name].should == 'some_controller'
+          f[:_links][:self][:href].should == "http://foo.bar.com/#{friend.id}"
+        end
+      end
+    end
+  end
+end

data/spec/adapters/json_api_spec.rb

@@ -0,0 +1,43 @@
+require 'spec_helper'
+require 'oat/adapters/json_api'
+
+describe Oat::Adapters::JsonAPI do
+
+  include Fixtures
+
+  subject{ serializer_class.new(user, {name: 'some_controller'}, Oat::Adapters::JsonAPI) }
+
+  describe '#to_hash' do
+    it 'produces a JSON-API compliant hash' do
+      payload = subject.to_hash
+      # embedded friends
+      payload[:linked][:friends][0].tap do |f|
+        f[:id].should == friend.id
+        f[:name].should == friend.name
+        f[:age].should == friend.age
+        f[:controller_name].should == 'some_controller'
+        f[:links][:self].should == "http://foo.bar.com/#{friend.id}"
+      end
+
+      # embedded manager
+      payload[:linked][:managers][0].tap do |m|
+        m[:id].should == manager.id
+        m[:name].should == manager.name
+        m[:age].should  == manager.age
+        m[:links][:self].should == "http://foo.bar.com/#{manager.id}"
+      end
+
+      payload[:users][0].tap do |h|
+        h[:id].should == user.id
+        h[:name].should == user.name
+        h[:age].should == user.age
+        h[:controller_name].should == 'some_controller'
+        # links
+        h[:links][:self].should == "http://foo.bar.com/#{user.id}"
+        # these links are added by embedding entities
+        h[:links][:manager].should == manager.id
+        h[:links][:friends].should == [friend.id]
+      end
+    end
+  end
+end

data/spec/adapters/siren_spec.rb

@@ -0,0 +1,45 @@
+require 'spec_helper'
+require 'oat/adapters/siren'
+
+describe Oat::Adapters::Siren do
+
+  include Fixtures
+
+  subject{ serializer_class.new(user, {name: 'some_controller'}, Oat::Adapters::Siren) }
+
+  describe '#to_hash' do
+    it 'produces a Siren-compliant hash' do
+      subject.to_hash.tap do |h|
+        #siren class
+        h[:class].should == ['user']
+        # properties
+        h[:properties][:id].should == user.id
+        h[:properties][:name].should == user.name
+        h[:properties][:age].should == user.age
+        h[:properties][:controller_name].should == 'some_controller'
+        # links
+        h[:links][0][:rel].should == [:self]
+        h[:links][0][:href].should == "http://foo.bar.com/#{user.id}"
+        # embedded manager
+        h[:entities][1].tap do |m|
+          m[:class].should == ['manager']
+          m[:properties][:id].should == manager.id
+          m[:properties][:name].should == manager.name
+          m[:properties][:age].should  == manager.age
+          m[:links][0][:rel].should == [:self]
+          m[:links][0][:href].should == "http://foo.bar.com/#{manager.id}"
+        end
+        # embedded friends
+        h[:entities][0].tap do |f|
+          f[:class].should == ['user']
+          f[:properties][:id].should == friend.id
+          f[:properties][:name].should == friend.name
+          f[:properties][:age].should == friend.age
+          f[:properties][:controller_name].should == 'some_controller'
+          f[:links][0][:rel].should == [:self]
+          f[:links][0][:href].should == "http://foo.bar.com/#{friend.id}"
+        end
+      end
+    end
+  end
+end

data/spec/fixtures.rb

@@ -0,0 +1,42 @@
+module Fixtures
+  
+  def self.included(base)
+    base.let(:user_class) { Struct.new(:name, :age, :id, :friends, :manager) }
+    base.let(:friend) { user_class.new('Joe', 33, 2, []) }
+    base.let(:manager) { user_class.new('Jane', 29, 3, []) }
+    base.let(:user) { user_class.new('Ismael', 35, 1, [friend], manager) }
+    base.let(:serializer_class) do
+      Class.new(Oat::Serializer) do
+        klass = self
+
+        schema do
+          type 'user'
+          link :self, href: url_for(item.id)
+
+          property :id, item.id
+          properties do |attrs|
+            attrs.name item.name
+            attrs.age item.age
+            attrs.controller_name context[:name]
+          end
+
+          entities :friends, item.friends, klass
+
+          entity :manager, item.manager do |manager, s|
+            s.type 'manager'
+            s.link :self, href: url_for(manager.id)
+            s.properties do |attrs|
+              attrs.id manager.id
+              attrs.name manager.name
+              attrs.age manager.age
+            end
+          end if item.manager
+        end
+
+        def url_for(id)
+          "http://foo.bar.com/#{id}"
+        end
+      end
+    end
+  end
+end

data/spec/serializer_spec.rb

@@ -0,0 +1,69 @@
+require 'spec_helper'
+
+describe Oat::Serializer do
+
+  before do
+    @adapter_class = Class.new(Oat::Adapter) do
+      def attributes(&block)
+        data[:attributes].merge!(yield_props(&block))
+      end
+
+      def attribute(key, value)
+        data[:attributes][key] = value
+      end
+
+      def link(rel, url)
+        data[:links][rel] = url
+      end
+    end
+
+    @sc = Class.new(Oat::Serializer) do
+
+      schema do
+        my_attribute 'Hello'
+        attribute :id, item.id
+        attributes do |attrs|
+          attrs.name item.name
+          attrs.age item.age
+          attrs.controller_name context[:name]
+        end
+        link :self, url_for(item.id)
+      end
+
+      def url_for(id)
+        "http://foo.bar.com/#{id}"
+      end
+
+      def my_attribute(value)
+        attribute :special, value
+      end
+    end
+
+    @sc.adapter @adapter_class
+  end
+
+  let(:user_class) do
+    Struct.new(:name, :age, :id, :friends)
+  end
+
+  let(:user1) { user_class.new('Ismael', 35, 1, []) }
+
+  it 'should have a version number' do
+    Oat::VERSION.should_not be_nil
+  end
+
+  describe '#to_hash' do
+    it 'builds Hash from item and context with attributes as defined in adapter' do
+      serializer = @sc.new(user1, name: 'some_controller')
+      serializer.to_hash.tap do |h|
+        h[:attributes][:special].should == 'Hello'
+        h[:attributes][:id].should == user1.id
+        h[:attributes][:name].should == user1.name
+        h[:attributes][:age].should == user1.age
+        h[:attributes][:controller_name].should == 'some_controller'
+        h[:links][:self].should == "http://foo.bar.com/#{user1.id}"
+      end
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'oat'
+require 'fixtures'

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: oat
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Ismael Celis
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-11-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Oat helps you separate your API schema definitions from the underlying
+  media type. Media types can be plugged or swapped on demand globally or on the content-negotiation
+  phase
+email:
+- ismaelct@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- LICENSE
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/oat.rb
+- lib/oat/adapter.rb
+- lib/oat/adapters/hal.rb
+- lib/oat/adapters/json_api.rb
+- lib/oat/adapters/siren.rb
+- lib/oat/props.rb
+- lib/oat/serializer.rb
+- lib/oat/version.rb
+- oat.gemspec
+- spec/adapters/hal_spec.rb
+- spec/adapters/json_api_spec.rb
+- spec/adapters/siren_spec.rb
+- spec/fixtures.rb
+- spec/serializer_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Adapters-based serializers with Hypermedia support
+test_files:
+- spec/adapters/hal_spec.rb
+- spec/adapters/json_api_spec.rb
+- spec/adapters/siren_spec.rb
+- spec/fixtures.rb
+- spec/serializer_spec.rb
+- spec/spec_helper.rb