Readme Driven Development for Hypermodel

hypermodel.rb

module Hypermodel
  module ClassMethods
    # Public: Adds a new link to the _links section of the representation.
    #
    # relation - A String or Symbol with the name of the relation. It will
    #            also be used as a method name to call in the Hypermodel
    #            class or in the resource (as a second option) to get the href
    #            if no href provided.
    # href     - An optional String with the href of the link.
    # options  - An optional hash to add to the link (like tempalted: true).
    #
    # Returns nothing.
    def link(relation, href = nil, options = {})
    end

    # Public: Adds properties to the resource representation with its values.
    #
    # properties - An Array of symbols representing each property. Each property
    #              will be send to the Hypermodel class or to the resource if 
    #              the method is not found.
    #
    # Returns nothing.
    def properties(properties)
    end

    # Public: Adds a resource or a collection of resources to the _embedded
    #         section of the representation.
    #
    # resource_name - A String or Symbol with the name of the resource. It will
    #                 also be used as a method name to call in the Hypermodel
    #                 class or in the resource (as a second option) to get the
    #                 resource(s) to embed.
    #
    # representation_class_name - A String with the name of the class to use in
    #                             order to represent the embedded resource(s).
    def embed(resource_name, representation_class_name)
    end
  end

  # Public: Returns the JSON HAL representation of the resource.
  def to_json
  end

  # Public: Returns the resource that is being represented as JSON HAL.
  attr_accessor :resource

  # Public: Returns the context: an object where the resource was created and 
  # can be helpful to build urls, get permissions, etc.
  attr_accessor :context

  # Public: Initializes an Hypermodel object.
  #
  # resource - The object to represent as JSON HAL.
  # context  - An optional object to get the context where the resource was 
  #            created.
  def initialize(resource, context = nil)
  end
end

hypermodel_usage.rb

class PostResource
  include Hypermodel

  link :self, '/link/to/self'
  link :author
  properties :id, :title, :body, :tags
  embed :comments, 'CommentResource' # Will try post_resource.comments first and resource.comments next

  def author
     context.author_path(resource.author)
  end

  def tags
    resource.tags.join(', ')
  end
end

my_post = Post.new(title: 'Hello world', body: 'Lorem ipsum')
PostResouce.new(my_post, context).to_json
# => JSON HAL representation of the post

class PostCollectionResource
  include Hypermodel

  link :self, '/posts'
  link :search, '/posts?q={q}', templated: true

  embed :posts, 'PostResource'

  # Since we're initializing the PostCollectionResource with a collection of
  # posts, we just embed the collection.
  def posts
    resource
  end
end

posts = Post.recent_posts
PostCollectionResource.new(posts).to_json
# => JSON HAL representation of the collection

What do you think of HyperSerializer or HyperPresenter?

Even HyperBuilder