oat 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 265248fecbfa3adf9fae15b6c9124a452fe8f285
-  data.tar.gz: aac3cc104b933d261d8f8ca858e038e5e7cef835
+  metadata.gz: 8bb1271b6a91bda9b273a02d29e48f999e240a35
+  data.tar.gz: 6ac4f8595d78f974ed688182ef021bc688958e65
 SHA512:
-  metadata.gz: 29f80fbffde75401c81cf69de1f59a5f1091d173abddf404c902ce90ada9c8060b950cfd56a3cc713daf5e961cac417376eb8e68d8ebeae169bfa5bfcbb9a2e9
-  data.tar.gz: fa5ecb844b738eed0344bc513ae083f2928e40eef0099c3e8bd282d0b466e1727cd23598577eb080977a06050e3d6c58764b387d2b5be0565683fea9d51a9985
+  metadata.gz: 5a4d8281a3a0a38e6a21556388df68c43c20dcd41c2e8df4cbd57e695a2d43d966361e3475b58a233f055d4afd1f433b9e73b571d3cad1f1638da73745505296
+  data.tar.gz: df432c06d285565c54a7102d96cb48cd13c4470bf283f23d94b91d2b809c900611140b139a299bc8cfd884a429702cf7d3fed43916313ee7b52db9eb1b0c9b7e

data/README.md

@@ -1,10 +1,10 @@
 # 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.
+Adapters-based API serializers with Hypermedia support for Ruby apps. Read [the blog post](http://new-bamboo.co.uk/blog/2013/11/21/oat-explicit-media-type-serializers-in-ruby) for context and motivation.
 
 ## What
 
-Oat lets you design your API payloads succinctly while conforming to your *media type* of choice (hypermedia or not). 
+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.
@@ -23,6 +23,7 @@ class ProductSerializer < Oat::Serializer
   schema do
     type "product"
     link :self, href: product_url(item)
+
     properties do |props|
       props.title item.title
       props.price item.price
@@ -48,6 +49,68 @@ The full serializer signature is `item`, `context`, `adapter_class`.
 * `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.
 
+### Defining Properties
+
+There are a few different ways of defining properties on a serializer.
+
+Properties can be added explicitly using `property`. In this case, you can map an arbitrary value to an arbitrary key:
+
+```ruby
+require 'oat/adapters/hal'
+class ProductSerializer < Oat::Serializer
+  adapter Oat::Adapters::HAL
+
+  schema do
+    type "product"
+    link :self, href: product_url(item)
+
+    property :title, item.title
+    property :price, item.price
+    property :description, item.blurb
+    property :the_number_one, 1
+  end
+end
+```
+
+Similarly, properties can be added within a block using `properties` to be more concise or make the code more readable. Again, these will set arbitrary values for arbitrary keys:
+
+```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 |p|
+      p.title           item.title
+      p.price           item.price
+      p.description     item.blurb
+      p.the_number_one  1
+    end
+  end
+end
+```
+
+In many cases, you will want to simply map the properties of `item` to a property in the serializer. This can be easily done using `map_properties`. This method takes a list of method or attribute names to which `item` will respond. Note that you cannot assign arbitrary values and keys using `map_properties` - the serializer will simply add a key and call that method on `item` to assign the value.
+
+```ruby
+require 'oat/adapters/hal'
+class ProductSerializer < Oat::Serializer
+  adapter Oat::Adapters::HAL
+
+  schema do
+    type "product"
+    link :self, href: product_url(item)
+
+    map_properties :title, :price
+    property :description, item.blurb
+    property :the_number_one, 1
+  end
+end
+```
+
 ## Adapters
 
 Using the included [HAL](http://stateless.co/hal_specification.html) adapter, the `ProductSerializer` above would render the following JSON:
@@ -264,7 +327,7 @@ 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.
+Hypermedia is all about the URLs linking your resources together. Oat adapters can have methods to declare links in your entity schema but it's up to your code/framework how to create those links.
 A simple stand-alone implementation could be:
 
 ```ruby
@@ -277,7 +340,7 @@ class ProductSerializer < Oat::Serializer
   end
 
   protected
-  
+
   # helper URL method
   def product_url(id)
     "https://api.com/products/#{id}"
@@ -355,7 +418,7 @@ NOTE: Rails URL helpers could be handled by a separate oat-rails gem.
 
 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. 
+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.

data/lib/oat/adapter.rb

@@ -22,6 +22,8 @@ module Oat
     end
 
     def serializer_from_block_or_class(obj, serializer_class = nil, &block)
+      return nil if obj.nil?
+
       if block_given?
         serializer_class = Class.new(serializer.class)
         serializer_class.adapter self.class
@@ -33,4 +35,4 @@ module Oat
       end
     end
   end
-end
+end

data/lib/oat/adapters/hal.rb

@@ -26,4 +26,4 @@ module Oat
 
     end
   end
-end
+end

data/lib/oat/adapters/json_api.rb

@@ -26,9 +26,12 @@ module Oat
       end
 
       def entity(name, obj, serializer_class = nil, &block)
+        @entities[name.to_s.pluralize.to_sym] ||= []
         ent = entity_without_root(obj, serializer_class, &block)
-        link name, href: ent[:id]
-        (@entities[name.to_s.pluralize.to_sym] ||= []) << ent
+        if ent
+          link name, href: ent[:id]
+          @entities[name.to_s.pluralize.to_sym] << ent
+        end
       end
 
       def entities(name, collection, serializer_class = nil, &block)
@@ -36,9 +39,12 @@ module Oat
         data[:links][link_name] = []
 
         collection.each do |obj|
+          @entities[link_name] ||= []
           ent = entity_without_root(obj, serializer_class, &block)
-          data[:links][link_name] << ent[:id]
-          (@entities[link_name] ||= []) << ent
+          if ent
+            data[:links][link_name] << ent[:id]
+            @entities[link_name] << ent
+          end
         end
       end
 
@@ -54,9 +60,10 @@ module Oat
       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
+        ent = serializer_from_block_or_class(obj, serializer_class, &block)
+        ent.values.first.first if ent
       end
 
     end
   end
-end
+end

data/lib/oat/adapters/siren.rb

@@ -7,6 +7,7 @@ module Oat
         super
         data[:links] = []
         data[:entities] = []
+        data[:actions] = []
       end
 
       def type(*types)
@@ -26,7 +27,8 @@ module Oat
       end
 
       def entity(name, obj, serializer_class = nil, &block)
-        data[:entities] << serializer_from_block_or_class(obj, serializer_class, &block)
+        ent = serializer_from_block_or_class(obj, serializer_class, &block)
+        data[:entities] << ent if ent
       end
 
       def entities(name, collection, serializer_class = nil, &block)
@@ -35,6 +37,52 @@ module Oat
         end
       end
 
+      def action(name, &block)
+        action = Action.new(name)
+        block.call(action)
+
+        data[:actions] << action.data
+      end
+
+      class Action
+        attr_reader :data
+
+        def initialize(name)
+          @data = { name: name, class: [], fields: [] }
+        end
+
+        def class(value)
+          data[:class] << value
+        end
+
+        def field(name, &block)
+          field = Field.new(name)
+          block.call(field)
+
+          data[:fields] << field.data
+        end
+
+        %w(href method title).each do |attribute|
+          define_method(attribute) do |value|
+            data[attribute.to_sym] = value
+          end
+        end
+
+        class Field
+          attr_reader :data
+
+          def initialize(name)
+            @data = { name: name }
+          end
+
+          %w(type value).each do |attribute|
+            define_method(attribute) do |value|
+              data[attribute.to_sym] = value
+            end
+          end
+        end
+      end
+
     end
   end
-end
+end

data/lib/oat/serializer.rb

@@ -39,6 +39,10 @@ module Oat
       end
     end
 
+    def respond_to_missing?(method_name, include_private = false)
+      adapter.respond_to? method_name
+    end
+
     def to_hash
       @to_hash ||= (
         self.instance_eval &self.class.schema
@@ -46,5 +50,14 @@ module Oat
       )
     end
 
+    def map_properties(*args)
+      args.each { |name| map_property name }
+    end
+
+    def map_property(name)
+      value = item.send(name)
+      property name, value
+    end
+
   end
-end
+end

data/lib/oat/version.rb

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

data/oat.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   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.homepage      = "https://github.com/ismasan/oat"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)

data/spec/adapters/hal_spec.rb

@@ -35,5 +35,32 @@ describe Oat::Adapters::HAL do
         end
       end
     end
+
+    context 'with a nil entity relationship' do
+      let(:manager) { nil }
+
+      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].fetch(:manager).should be_nil
+          # 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
-end
+end

data/spec/adapters/json_api_spec.rb

@@ -39,5 +39,36 @@ describe Oat::Adapters::JsonAPI do
         h[:links][:friends].should == [friend.id]
       end
     end
+
+    context 'with a nil entity relationship' do
+      let(:manager) { nil }
+
+      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].fetch(:managers).should be_empty
+
+        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].should_not include(:manager)
+          h[:links][:friends].should == [friend.id]
+        end
+      end
+    end
   end
-end
+end

data/spec/adapters/siren_spec.rb

@@ -39,7 +39,49 @@ describe Oat::Adapters::Siren do
           f[:links][0][:rel].should == [:self]
           f[:links][0][:href].should == "http://foo.bar.com/#{friend.id}"
         end
+        # action close_account
+        h[:actions][0].tap do |a|
+          a[:name].should == :close_account
+          a[:href].should == "http://foo.bar.com/#{user.id}/close_account"
+          a[:class].should == ['danger', 'irreversible']
+          a[:method].should == 'DELETE'
+          a[:fields][0].tap do |f|
+            f[:name].should == :current_password
+            f[:type].should == :password
+          end
+        end
+      end
+    end
+
+    context 'with a nil entity relationship' do
+      let(:manager) { nil }
+
+      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].any?{|o| o[:class].include?("manager")}.should be_false
+          # 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
-end
+end

data/spec/fixtures.rb

@@ -1,5 +1,5 @@
 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, []) }
@@ -14,9 +14,8 @@ module Fixtures
           link :self, href: url_for(item.id)
 
           property :id, item.id
+          map_properties :name, :age
           properties do |attrs|
-            attrs.name item.name
-            attrs.age item.age
             attrs.controller_name context[:name]
           end
 
@@ -30,7 +29,17 @@ module Fixtures
               attrs.name manager.name
               attrs.age manager.age
             end
-          end if item.manager
+          end
+
+          action :close_account do |action|
+            action.href "http://foo.bar.com/#{item.id}/close_account"
+            action.class 'danger'
+            action.class 'irreversible'
+            action.method 'DELETE'
+            action.field :current_password do |field|
+              field.type :password
+            end
+          end
         end
 
         def url_for(id)
@@ -39,4 +48,4 @@ module Fixtures
       end
     end
   end
-end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oat
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Ismael Celis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-18 00:00:00.000000000 Z
+date: 2014-01-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -98,7 +98,7 @@ files:
 - spec/fixtures.rb
 - spec/serializer_spec.rb
 - spec/spec_helper.rb
-homepage: ''
+homepage: https://github.com/ismasan/oat
 licenses:
 - MIT
 metadata: {}