darstellung 0.0.0 → 0.0.1

data/README.md

@@ -1,6 +1,185 @@
 Darstellung [![Build Status](https://secure.travis-ci.org/durran/darstellung.png?branch=master&.png)](http://travis-ci.org/durran/darstellung) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/durran/darstellung)
 ========
 
+Darstellung is a simple DSL for defining what should be displayed in
+resource representations most of the time in API consumption. The
+library is currently in an experimental phase (pre 1.0.0).
+
+Usage
+-----
+
+Say we have a `UserResource` that is responsible for returning
+representations of `User` models. With Darstellung, we tell it what
+fields to display in a "detail" representation and in a "summary"
+representation:
+
+```ruby
+class UserResource
+  include Darstellung::Representable
+
+  summary :username
+
+  detail :first_name
+  detail :last_name
+end
+```
+
+Then we can initialize a new `UserResource` with a single `User` and ask for
+the hash representation back:
+
+```ruby
+resource = UserResource.new(user)
+resource.detail #=> { version: "none", resource: { first_name: "john", last_name: "doe" }}
+resource.summary #=> { version: "none", resource: { username: "john" }}
+```
+
+If we provide the `UserResource` with an `Enumerable` of `User`s, we can ask
+for a collection, which returns an array of summary representations for each
+user in the list.
+
+```ruby
+resource = UserResource.new([ user_one, user_two ])
+resource.collection #=> { version: "none", resource: [{ username: "john" }, { username: "joe" }]}
+```
+
+Versioning
+----------
+
+Just like any other piece of software, your application's API is a contract
+for others to use, and changes to this contract should follow a sane and
+predictable pattern. Darstellung handles this by allowing you to specify versions
+in which various attributes are displayed in the detail and summary views.
+Clients can request a specific version of the API and get the expected results
+back at all times. It is expected that the version numbers follow the
+Semantic Versioning Specification in order to maintain some consistency.
+
+Here is a `UserResource` with versioning:
+
+```ruby
+class UserResource
+  include Darstellung::Representable
+
+  summary :username
+  summary :created_at, from: "1.0.1"
+
+  detail :first_name
+  detail :last_name, from: "1.0.5", to: "2.0.0"
+end
+```
+
+If we pass a version to the `detail`, `summary`, and `collection` methods on
+the resource, we will only get back attributes that fall in line with the
+version specified:
+
+```ruby
+resource = UserResource.new(user)
+resource.detail("1.0.0")
+  #=> { version: "1.0.0", resource: { first_name: "john" }}
+resource.detail("1.0.5")
+  #=> { version: "1.0.5", resource: { first_name: "john", last_name: "doe" }}
+
+resource.summary("1.0.0")
+  #=> { version: "1.0.0", resource: { username: "john" }}
+resource.summary("2.0.0")
+  #=> { version: "2.0.0", resource: { username: "john", created_at: "2012-1-1" }}
+
+resource = UserResource.new([ user_one, user_two ])
+resource.collection("2.0.0")
+  # => {
+  #   version: "2.0.0",
+  #   resource: [
+  #     { username: "john", created_at: "2012-1-1" },
+  #     { username: "joe", created_at: "2012-1-2" }
+  #   ]
+  # }
+```
+
+Reasoning
+---------
+
+This is simply a case of SRP and maintainability. While some may argue against
+SRP in Rails being overkill, I disagree and will simply show examples showing
+the choices and the developer can decide for themselves. Although my personal
+preference would be to use Sinatra or Webmachine in these API cases, there's a good
+[blog post](http://blog.gomiso.com/2011/05/16/if-youre-using-to_json-youre-doing-it-wrong)
+from the authors of RABL discussing how this gets out of hand quickly in Rails.
+
+Speed
+-----
+
+Bypassing Active Model's serialization is going to provide you with a huge
+performance benefit. Let's look at a basic Mongoid model:
+
+```ruby
+class Band
+  include Mongoid::Document
+  field :description, type: String
+  field :formed_on, type: Date
+  field :location, type: String
+  field :genres, type: Array, default: []
+  field :name, type: String
+  field :similarities, type: Array, default: []
+  field :sounds, type: Array, default: []
+  field :website, type: String
+end
+```
+
+Now let's serialize the model to json (using YAJL), 100,000 times:
+
+```ruby
+bench.report do
+  100_000.times do
+    band.to_json
+  end
+end
+```
+```
+     user     system      total        real
+37.150000   0.100000  37.250000 ( 37.250232)
+```
+
+When we create a resource for the `Band` with Darstellung and serialize it
+that way, we get some serious improvement (over 6x faster).
+
+```ruby
+class BandResource
+  include Darstellung::Representable
+  detail :description
+  detail :formed_on
+  detail :location
+  detail :genres
+  detail :name
+  detail :similarities
+  detail :sounds
+  detail :website
+end
+
+bench.report do
+  100_000.times do
+    BandResource.new(band).detail.to_json
+  end
+end
+```
+
+```
+    user     system      total        real
+6.270000   0.010000   6.280000 (  6.277472)
+```
+
+The results are drastically different in the simplest of examples, and expect
+another order of magnitude gain when including relations.
+
+Serialization
+-------------
+
+Darstellung does not deal in serialization at all. It's only purpose is to
+provide hash representations of your API resources for specific versions. It's
+up to you to call `to_json` or `to_xml` on them, using whatever serialization
+library you want.
+
+License
+-------
+
 Copyright (c) 2012 Durran Jordan
 
 Permission is hereby granted, free of charge, to any person obtaining

data/lib/darstellung.rb

@@ -0,0 +1,3 @@
+# encoding: utf-8
+require "darstellung/representable"
+require "darstellung/version"

data/lib/darstellung/attribute.rb

@@ -0,0 +1,79 @@
+# encoding: utf-8
+module Darstellung
+
+  # An attribute is any field that can be represented. This class provides
+  # extra behavior around when and how these fields get represented.
+  #
+  # @since 0.0.0
+  class Attribute
+
+    # @attribute [r] name The name of the attribute.
+    # @attribute [r] options The attribute options.
+    # @attribute [r] block The block to call to get the value.
+    attr_reader :name, :options, :block
+
+    # Determines if the attribute is displayable in the representation given
+    # the provided version.
+    #
+    # @example Is the attribute displayable?
+    #   attribute.displayable?("1.0.0")
+    #
+    # @note This method assumes that API versions are following the Semantic
+    #   Versioning Specificaion, and does its comparison of version strings
+    #   with this in mind.
+    #
+    # @param [ String ] version The version number.
+    #
+    # @return [ true, false ] If the attribute is displayable.
+    #
+    # @see http://semver.org/
+    #
+    # @since 0.0.0
+    def displayable?(version)
+      return true unless version
+      from <= version && version <= to(version)
+    end
+
+    # Initialize the new attribute.
+    #
+    # @example Initialize the new attribute.
+    #   Darstellung::Attribute.new(:name, version: "1.0.1")
+    #
+    # @param [ Symbol ] name The name of the attribute.
+    # @param [ Hash ] options The attribute options.
+    #
+    # @option options [ String ] :from The version the attribute is available
+    #   from.
+    # @option options [ String ] :to The version the attribute is available
+    #   to.
+    #
+    # @since 0.0.0
+    def initialize(name, options = {}, &block)
+      @name, @options, @block = name, options, block
+    end
+
+    # Get the value for the attribute from the provided resource.
+    #
+    # @example Get the value for the attribute.
+    #   attribute.value(user)
+    #
+    # @param [ Object ] resource The resource to execute on.
+    #
+    # @return [ Object ] The value of the resource.
+    #
+    # @since 0.0.0
+    def value(resource)
+      block ? block.call(resource) : resource.__send__(name)
+    end
+
+    private
+
+    def from
+      options[:from] || "0.0.0"
+    end
+
+    def to(version)
+      options[:to] || "#{version}+"
+    end
+  end
+end

data/lib/darstellung/definable.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+module Darstellung
+
+  # This module contains access from the instance level to the attribute
+  # definitions provided by the macros.
+  #
+  # @since 0.0.0
+  module Definable
+
+    # Get all the attributes that are used in the detail representation.
+    #
+    # @example Get all the detail attributes fields.
+    #   user_resource.detail_attributes
+    #
+    # @return [ Hash ] The name/attribute pairs.
+    #
+    # @since 0.0.0
+    def detail_attributes
+      self.class.detail_attributes
+    end
+
+    # Get all the attributes that are used in the summary representation.
+    #
+    # @example Get all the summary attributes fields.
+    #   user_resource.summary_attributes
+    #
+    # @return [ Hash ] The name/attribute pairs.
+    #
+    # @since 0.0.0
+    def summary_attributes
+      self.class.summary_attributes
+    end
+  end
+end

data/lib/darstellung/macros.rb

@@ -0,0 +1,138 @@
+# encoding: utf-8
+require "darstellung/registry"
+
+module Darstellung
+
+  # This module provides all the class level macros for defining
+  # representations.
+  #
+  # @since 0.0.0
+  module Macros
+
+    # Defines an attribute to be displayed in the detail representation of the
+    # resource.
+    #
+    # @example Display the name field in the detail display.
+    #   class UserResource
+    #     include Darstellung::Representable
+    #     detail :name
+    #   end
+    #
+    # @example Display the name field only from version 1.0.0
+    #   class UserResource
+    #     include Darstellung::Representable
+    #     detail :name, from: "1.0.0"
+    #   end
+    #
+    # @example Display the name field only from version 1.0.0 - 1.1.0
+    #   class UserResource
+    #     include Darstellung::Representable
+    #     detail :name, from: "1.0.0", to: "1.1.0"
+    #   end
+    #
+    # @example Display the name field as a custom representation.
+    #   class UserResource
+    #     include Darstellung::Representable
+    #
+    #     detail :name do |user|
+    #       user.full_name
+    #     end
+    #   end
+    #
+    # @param [ Symbol ] name The name of the attribute.
+    # @param [ Hash ] options The attribute options.
+    #
+    # @option options [ String ] :from The version the field is available from.
+    # @option options [ String ] :to The version the field is available to.
+    #
+    # @return [ Attribute ] The attribute object for the field.
+    #
+    # @since 0.0.0
+    def detail(name, options = {}, &block)
+      create_attribute(name, detail_attributes, options, &block)
+    end
+
+    # Get all the attributes that are used in the detail representation.
+    #
+    # @example Get all the detail attributes fields.
+    #   class UserResource
+    #     include Darstellung::Representable
+    #   end
+    #
+    #   UserResource.detail_attributes
+    #
+    # @return [ Hash ] The name/attribute pairs.
+    #
+    # @since 0.0.0
+    def detail_attributes
+      @detail_attributes ||= {}
+    end
+
+    # Defines an attribute to be displayed in the summary representation of the
+    # resource.
+    #
+    # @example Display the name field in the summary display.
+    #   class UserResource
+    #     include Darstellung::Representable
+    #     summary :name
+    #   end
+    #
+    # @example Display the name field only from version 1.0.0
+    #   class UserResource
+    #     include Darstellung::Representable
+    #     summary :name, from: "1.0.0"
+    #   end
+    #
+    # @example Display the name field only from version 1.0.0 - 1.1.0
+    #   class UserResource
+    #     include Darstellung::Representable
+    #     summary :name, from: "1.0.0", to: "1.1.0"
+    #   end
+    #
+    # @example Display the name field as a custom representation.
+    #   class UserResource
+    #     include Darstellung::Representable
+    #
+    #     summary :name do |user|
+    #       user.full_name
+    #     end
+    #   end
+    #
+    # @param [ Symbol ] name The name of the attribute.
+    # @param [ Hash ] options The attribute options.
+    #
+    # @option options [ String ] :from The version the field is available from.
+    # @option options [ String ] :to The version the field is available to.
+    #
+    # @return [ Attribute ] The attribute object for the field.
+    #
+    # @since 0.0.0
+    def summary(name, options = {}, &block)
+      create_attribute(name, summary_attributes, options, &block)
+    end
+
+    # Get all the attributes that are used in the summary representation.
+    #
+    # @example Get all the summary attributes fields.
+    #   class UserResource
+    #     include Darstellung::Representable
+    #   end
+    #
+    #   UserResource.summary_attributes
+    #
+    # @return [ Hash ] The name/attribute pairs.
+    #
+    # @since 0.0.0
+    def summary_attributes
+      @summary_attributes ||= {}
+    end
+
+    private
+
+    def create_attribute(name, attributes, options = {}, &block)
+      normalized = name.to_sym
+      attributes[normalized] = Attribute.new(normalized, options, &block)
+      Registry.register(options)
+    end
+  end
+end

data/lib/darstellung/registry.rb

@@ -0,0 +1,85 @@
+# encoding: utf-8
+module Darstellung
+
+  # Contains information on all versions in the API that have been registered.
+  # This is determined from the various "from" and "to" options provided to the
+  # macros.
+  #
+  # @since 0.0.0
+  module Registry
+    extend self
+
+    # Register a set of options provided to a representation macro.
+    #
+    # @example Register the options.
+    #   Dartellung::Registry.register(from: "1.0.0", to: "2.0.0")
+    #
+    # @note This takes the "from" and "to" options and registers them as
+    #   official API versions.
+    #
+    # @param [ Hash ] options The macro options.
+    #
+    # @return [ Array<String> ] All the registered versions.
+    #
+    # @since 0.0.0
+    def register(options)
+      from, to = options[:from], options[:to]
+      registered_versions[from] = true if from
+      registered_versions[to] = true if to
+      versions
+    end
+
+    # Is a particular version registered with the API?
+    #
+    # @example Check if the version is registered.
+    #   Darstellung::Registry.registered?("2.1.5")
+    #
+    # @param [ String ] version The version to check.
+    #
+    # @return [ true, false ] If the version is registered.
+    #
+    # @since 0.0.0
+    def registered?(version)
+      registered_versions[version]
+    end
+
+    # Validate that the provided version is registered.
+    #
+    # @example Validate the version.
+    #   Darstellung::Registry.validate!("1.0.5")
+    #
+    # @param [ String ] version The version to validate.
+    #
+    # @raise [ NotRegistered ] If the version is not registered.
+    #
+    # @since 0.0.0
+    def validate!(version)
+      unless version.nil? || registered?(version)
+        raise NotRegistered.new("#{version} is not a valid API version.")
+      end
+    end
+
+    # Provides a list of all registered versions in the API.
+    #
+    # @example List all versions.
+    #   Darstellung::Registry.versions
+    #
+    # @return [ Array<String> ] All the registered versions.
+    #
+    # @since 0.0.0
+    def versions
+      registered_versions.keys
+    end
+
+    # Raised when validating a version that does not exist in the registry.
+    #
+    # @since 0.0.0
+    class NotRegistered < Exception; end
+
+    private
+
+    def registered_versions
+      @registered_versions ||= {}
+    end
+  end
+end

data/lib/darstellung/representable.rb

@@ -0,0 +1,126 @@
+# encoding: utf-8
+require "darstellung/attribute"
+require "darstellung/definable"
+require "darstellung/macros"
+
+module Darstellung
+
+  # This module is included into resources that need a summary and detail view
+  # for display in APIs. Summary views are for display in lists, detail views
+  # are generally show actions.
+  #
+  # @since 0.0.0
+  module Representable
+    include Definable
+
+    # @attribute [r] resource The resource being represented.
+    attr_reader :resource
+
+    # Gets the collection view for a specific version of the resource. If no
+    # version is provided then we assume from "0.0.0" which will render
+    # attributes available in all versions of the API.
+    #
+    # @example Get the collection representation.
+    #   user_resource.collection("1.0.1")
+    #
+    # @note The collection representation is a list of summary representations.
+    #
+    # @param [ String ] version The version to get of the resource.
+    #
+    # @return [ Hash ] The collection representation of the resource.
+    #
+    # @since 0.0.0
+    def collection(version = nil)
+      representation(version, multiple(summary_attributes, version))
+    end
+
+    # Gets the detail view for a specific version of the resource. If no
+    # version is provided then we assume from "0.0.0" which will render
+    # attributes available in all versions of the API.
+    #
+    # @example Get the detail representation.
+    #   user_resource.detail("1.0.1")
+    #
+    # @param [ String ] version The version to get of the resource.
+    #
+    # @return [ Hash ] The detail representation of the resource.
+    #
+    # @since 0.0.0
+    def detail(version = nil)
+      representation(version, single(detail_attributes, resource, version))
+    end
+
+    # Initialize the new representation with the provided resource.
+    #
+    # @example Initialize the representation.
+    #   class UserResource
+    #     include Darstellung::Representable
+    #   end
+    #
+    #   UserResource.new(user)
+    #
+    # @param [ Object ] resource The resource to be represented.
+    #
+    # @since 0.0.0
+    def initialize(resource)
+      @resource = resource
+    end
+
+    # Gets the summary view for a specific version of the resource. If no
+    # version is provided then we assume from "0.0.0" which will render
+    # attributes available in all versions of the API.
+    #
+    # @example Get the summary representation.
+    #   user_resource.summary("1.0.1")
+    #
+    # @param [ String ] version The version to get of the resource.
+    #
+    # @return [ Hash ] The summary representation of the resource.
+    #
+    # @since 0.0.0
+    def summary(version = nil)
+      representation(version, single(summary_attributes, resource, version))
+    end
+
+    private
+
+    def multiple(attributes, version, representation = [])
+      resource.each do |object|
+        representation.push(single(attributes, object, version))
+      end
+      representation
+    end
+
+    def representation(version, resource)
+      Registry.validate!(version)
+      Hash[ version: version || "none", resource: resource ]
+    end
+
+    def single(attributes, object, version, representation = {})
+      attributes.each do |name, attribute|
+        if attribute.displayable?(version)
+          representation[name] = attribute.value(object)
+        end
+      end
+      representation
+    end
+
+    class << self
+
+      # Including the module will inject the necessary macros into the base
+      # class.
+      #
+      # @exampe Include the Representable module.
+      #   class UserResource
+      #     include Darstellung::Representable
+      #   end
+      #
+      # @param [ Class ] klass The class including the module.
+      #
+      # @since 0.0.0
+      def included(klass)
+        klass.extend(Macros)
+      end
+    end
+  end
+end

data/lib/darstellung/version.rb

@@ -1,4 +1,4 @@
 # encoding: utf-8
 module Darstellung
-  VERSION = "0.0.0"
+  VERSION = "0.0.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: darstellung
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,16 +9,22 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-24 00:00:00.000000000 Z
+date: 2012-12-25 00:00:00.000000000 Z
 dependencies: []
-description: Create API representations in Ruby
+description: Simple and fast representations for APIs in Ruby
 email:
 - durran@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/darstellung/attribute.rb
+- lib/darstellung/definable.rb
+- lib/darstellung/macros.rb
+- lib/darstellung/registry.rb
+- lib/darstellung/representable.rb
 - lib/darstellung/version.rb
+- lib/darstellung.rb
 - README.md
 - LICENSE
 - Rakefile
@@ -36,7 +42,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1882674926009562910
+      hash: 220129650249248843
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -45,11 +51,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1882674926009562910
+      hash: 220129650249248843
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: Create API representations in Ruby
+summary: Simple and fast representations for APIs in Ruby
 test_files: []