hypermodel 0.0.1 → 0.1.0

data/README.md

@@ -40,6 +40,50 @@ Now if you ask your API for a Post:
         [{"_id"=>"4fb648996b98c9091900000d", "body"=>"Comment 1"},
          {"_id"=>"4fb648996b98c9091900000e", "body"=>"Comment 2"}]}}
 
+## Gotchas
+
+These are some implementation gotchas which are welcome to be fixed if you can
+think of workarounds :)
+
+### Routes should reflect data model
+
+For Hypermodel to generate `_links` correctly, the relationship/embedding
+structure of the model must match exactly that of the app routing. That means,
+that if you have `Blogs` that have many `Posts` which have many `Comments`,
+the routes.rb file should reflect it:
+
+````ruby
+# config/routes.rb
+resources :blogs do
+  resources :posts do
+    resources :comments
+  end
+end
+````
+
+### Every resource controller must implement the :show action at least
+
+Each resource and subresource must respond to the `show` action (so they can be
+linked from anywhere, in the `_links` section).
+
+### The first belongs_to decides the hierarchy chain
+
+So if a `Post` belongs to an author and to a blog, and you want to access
+posts through blogs, not authors, you have to put the `belongs_to :blog`
+**before** `belongs_to :author`:
+
+````ruby
+# app/models/post.rb
+class Post
+  include Mongoid::Document
+
+  belongs_to :blog
+  belongs_to :author
+end
+````
+
+I know, lame.
+
 ## Contributing
 
 * [List of hypermodel contributors][contributors]

data/Rakefile

@@ -4,25 +4,15 @@ begin
 rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
-begin
-  require 'rdoc/task'
-rescue LoadError
-  require 'rdoc/rdoc'
-  require 'rake/rdoctask'
-  RDoc::Task = Rake::RDocTask
-end
 
-RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'Hypermodel'
-  rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.rdoc')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+require 'yard'
+YARD::Config.load_plugin('yard-tomdoc') 
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+  t.options = %w(-r README.md)
 end
 
 
-
-
 Bundler::GemHelper.install_tasks
 
 require 'rake/testtask'

data/lib/hypermodel/resource.rb

@@ -0,0 +1,99 @@
+require 'hypermodel/serializers/mongoid'
+
+module Hypermodel
+  # Public: Responsible for building the response in JSON-HAL format. It is
+  # meant to be used by Hypermodel::Responder.
+  #
+  # In future versions one will be able to subclass it and personalize a
+  # Resource for each diffent model, i.e. creating a PostResource.
+  class Resource
+    extend Forwardable
+
+    def_delegators :@serializer, :attributes, :record, :resources,
+                                 :sub_resources, :embedded_resources,
+                                 :embedding_resources
+
+    # Public: Recursive functino that traverses a record's referential
+    # hierarchy upwards.
+    #
+    # Returns a flattened Array with the hierarchy of records.
+    TraverseUpwards = lambda do |record|
+      serializer = Serializers::Mongoid.new(record)
+
+      parent_name, parent_resource = (
+        serializer.embedding_resources.first || serializer.resources.first
+      )
+
+      # If we have a parent
+      if parent_resource
+        # Recurse over parent hierarchies
+        [TraverseUpwards[parent_resource], record].flatten
+      else
+        # Final case, we are the topmost parent: return ourselves
+        [record]
+      end
+    end
+
+    # Public: Initializes a Resource.
+    #
+    # record     - A Mongoid instance of a model.
+    # controller - An ActionController instance.
+    #
+    # TODO: Detect record type (ActiveRecord, DataMapper, Mongoid, etc..) and
+    # choose the corresponding serializer.
+    def initialize(record, controller)
+      @record     = record
+      @serializer = Serializers::Mongoid.new(record)
+      @controller = controller
+    end
+
+    # Public: Returns a Hash of the resource in JSON-HAL.
+    #
+    # opts - Options to pass to the resource to_json.
+    def to_json(*opts)
+      attributes.update(links).update(embedded).to_json(*opts)
+    end
+
+    # Internal: Constructs the _links section of the response.
+    #
+    # Returns a Hash of the links of the resource. It will include, at least,
+    # a link to itself.
+    def links
+      _links = { self: polymorphic_url(record_with_ancestor_chain(@record)) }
+
+      resources.each do |name, resource|
+        _links.update(name => polymorphic_url(record_with_ancestor_chain(resource)))
+      end
+
+      sub_resources.each do |sub_resource|
+        _links.update(sub_resource => polymorphic_url(record_with_ancestor_chain(@record) << sub_resource))
+      end
+
+      { _links: _links }
+    end
+
+    # Internal: Constructs the _embedded section of the response.
+    #
+    # Returns a Hash of the embedded resources of the resource.
+    def embedded
+      { _embedded: embedded_resources }
+    end
+
+    # Internal: Returns the url wrapped in a Hash in HAL format.
+    def polymorphic_url(record_or_hash_or_array, options = {})
+      { href: @controller.polymorphic_url(record_or_hash_or_array, options = {}) }
+    end
+
+    private
+
+    # Internal: Returns a flattened array of records representing the ancestor
+    # chain of a given record, including itself at the end.
+    #
+    # It is used to generate correct polymorphic URLs.
+    #
+    # record - the record whose ancestor chain we'd like to retrieve.
+    def record_with_ancestor_chain(record)
+      TraverseUpwards[record]
+    end
+  end
+end

data/lib/hypermodel/responder.rb

@@ -1,8 +1,18 @@
-require 'hypermodel/serializers/mongoid'
+require 'hypermodel/resource'
 
 module Hypermodel
-  Serializer = Serializers::Mongoid
-
+  # Public: Responsible for exposing a resource in JSON-HAL format.
+  #
+  # Examples
+  #
+  # class PostsController < ApplicationController
+  #   respond_to :json
+  #
+  #   def show
+  #     @post = Post.find params[:id]
+  #     respond_with(@post, responder: Hypermodel::Responder)
+  #   end
+  # end
   class Responder
     def self.call(*args)
       controller    = args[0]
@@ -15,10 +25,10 @@ module Hypermodel
       controller.render json: responder
     end
 
-    def initialize(resource_name, action, resource, controller)
+    def initialize(resource_name, action, record, controller)
       @resource_name = resource_name
       @action        = action
-      @resource      = Serializer.new(resource, controller)
+      @resource      = Resource.new(record, controller)
     end
 
     def to_json(*opts)

data/lib/hypermodel/serializers/mongoid.rb

@@ -1,73 +1,130 @@
 module Hypermodel
   module Serializers
+    # Internal: A Mongoid serializer that complies with the Hypermodel
+    # Serializer API.
+    #
+    # It is used by Hypermodel::Resource to extract the attributes and
+    # resources of a given record.
     class Mongoid
-      def initialize(resource, controller)
-        @resource   = resource
-        @attributes = resource.attributes.dup
-        @controller = controller
-      end
 
-      def to_json(*opts)
-        attrs = @attributes.update(links).update(embedded)
-        attrs.to_json(*opts)
+      # Public: Returns the Mongoid instance
+      attr_reader :record
+
+      # Public: Returns the attributes of the Mongoid instance
+      attr_reader :attributes
+
+      # Public: Initializes a Serializer::Mongoid.
+      #
+      # record - A Mongoid instance of a model.
+      def initialize(record)
+        @record     = record
+        @attributes = record.attributes.dup
       end
 
-      def links
-        hash = { self: { href: @controller.polymorphic_url(@resource) } }
-
-        referenced_relations.each do |name, metadata|
-          related = @resource.send(name)
-          relation = metadata.relation
-
-          if relation == ::Mongoid::Relations::Referenced::In
-            unless related.nil? || (related.respond_to?(:empty?) && related.empty?)
-              hash.update(name => { href: @controller.polymorphic_url(related) })
-            end
-          elsif relation == ::Mongoid::Relations::Referenced::Many
-            hash.update(name => { href: @controller.polymorphic_url([@resource, name]) })
-          else
-            raise "Referenced relation type not implemented: #{relation}"
-          end
+      # Public: Returns a Hash with the resources that are linked to the
+      # record. It will be used by Hypermodel::Resource.
+      #
+      # An example of a linked resource could be the author of a post. Think
+      # of `/authors/:author_id`
+      #
+      # The format of the returned Hash must be the following:
+      #
+      #   {resource_name: resource_instance}
+      #
+      # `resource_name` can be either a Symbol or a String.
+      def resources
+        relations = select_relations_by_type(::Mongoid::Relations::Referenced::In)
 
+        relations.inject({}) do |acc, (name, _)|
+          acc.update(name => @record.send(name))
         end
+      end
 
-        { _links: hash }
+      # Public: Returns a Hash with the sub resources that are linked to the
+      # record. It will be used by Hypermodel::Resource. These resources need
+      # to be differentiated so Hypermodel::Resource can build the url.
+      #
+      # An example of a linked sub resource could be comments of a post.
+      # Think of `/posts/:id/comments`
+      #
+      # The format of the returned Hash must be the following:
+      #
+      #   {:sub_resource, :another_subresource}
+      def sub_resources
+        select_relations_by_type(::Mongoid::Relations::Referenced::Many).keys
       end
 
-      def embedded
+      # Public: Returns a Hash with the embedded resources attributes. It will
+      # be used by Hypermodel::Resource.
+      #
+      # An example of an embedded resource could be the reviews of a post, or
+      # the addresses of a company. But you can really embed whatever you like.
+      #
+      # An example of the returning Hash could be the following:
+      #
+      #   {"comments"=>
+      #     [
+      #       {"_id"=>"4fb941cb82b4d46162000007", "body"=>"Comment 1"},
+      #       {"_id"=>"4fb941cb82b4d46162000008", "body"=>"Comment 2"}
+      #     ]
+      #   }
+      def embedded_resources
         return {} if embedded_relations.empty?
 
-        embedded_relations.inject({ _embedded: {} }) do |acc, (name, metadata)|
-          if attributes = extract_embedded_attributes(name, metadata)
+        embedded_relations.inject({}) do |acc, (name, metadata)|
+          if attributes = extract_embedded_attributes(name)
             @attributes.delete(name)
-            acc[:_embedded][name] = attributes
+            acc.update(name => attributes)
           end
           acc
         end
       end
 
+      # Public: Returns a Hash with the resources that are embedding us (our
+      # immediate ancestors).
+      def embedding_resources
+        return {} if embedded_relations.empty?
+
+        embedded = select_embedded_by_type(::Mongoid::Relations::Embedded::In)
+
+        embedded.inject({}) do |acc, (name, _)|
+          acc.update(name => @record.send(name))
+        end
+      end
+
+      #######
       private
+      #######
 
-      def extract_embedded_attributes(name, metadata)
-        relation = metadata.relation
+      def select_relations_by_type(type)
+        referenced_relations.select do |name, metadata|
+          metadata.relation == type
+        end
+      end
 
-        if relation == ::Mongoid::Relations::Embedded::Many
-          @resource.send(name).map { |embedded| embedded.attributes }
-        elsif relation == ::Mongoid::Relations::Embedded::One
-          (embedded = resource.send(name)) ? embedded.attributes : nil
-        else
-          raise "Embedded relation type not implemented: #{relation}"
+      def select_embedded_by_type(type)
+        embedded_relations.select do |name, metadata|
+          metadata.relation == type
         end
       end
 
+      def extract_embedded_attributes(name)
+        embedded = @record.send(name)
+
+        return {} unless embedded
+        return embedded.map(&:attributes) if embedded.respond_to?(:map)
+
+        embedded.attributes
+      end
+
       def embedded_relations
-        @embedded_relations ||= @resource.relations.select do |_, metadata|
+        @embedded_relations ||= @record.relations.select do |_, metadata|
           metadata.relation.name =~ /Embedded/
         end
       end
 
       def referenced_relations
-        @referenced_relations ||= @resource.relations.select do  |_, metadata|
+        @referenced_relations ||= @record.relations.select do  |_, metadata|
           metadata.relation.name =~ /Referenced/
         end
       end

data/lib/hypermodel/version.rb

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

data/lib/hypermodel.rb

@@ -1,5 +1,6 @@
+# Public: A Hypermodel is a representation of a resource in a JSON-HAL format.
+# To learn more about JSON HAL see http://stateless.co/hal_specification.html
 module Hypermodel
 end
 
 require 'hypermodel/responder'
-

data/test/dummy/app/controllers/posts_controller.rb

@@ -2,7 +2,8 @@ class PostsController < ApplicationController
   respond_to :json
 
   def show
-    @post = Post.find params[:id]
+    @blog = Blog.find params[:blog_id]
+    @post = @blog.posts.find params[:id]
     respond_with(@post, responder: Hypermodel::Responder)
   end
 end

data/test/dummy/app/models/blog.rb

@@ -0,0 +1,6 @@
+class Blog
+  include Mongoid::Document
+
+  field :title
+  has_many :posts
+end

data/test/dummy/app/models/post.rb

@@ -5,6 +5,7 @@ class Post
   field :title, type: String
   field :body, type: String
 
+  belongs_to :blog
   belongs_to :author
   has_many :reviews
   embeds_many :comments

data/test/dummy/config/routes.rb

@@ -1,6 +1,8 @@
 Dummy::Application.routes.draw do
-  resources :posts do
-    resources :reviews
+  resources :blogs do
+    resources :posts do
+      resources :reviews
+    end
   end
   resources :authors
 end