shapeable 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f6950ec9d5f7b64533f0f5eb8a6b0cc8b9f20bd3
-  data.tar.gz: edc0ef5b43d1a8e3ddd1277ae000bfff82cb9407
+  metadata.gz: a7d39aa43ffe8a1b7c7aa7dfe557982057468b14
+  data.tar.gz: 54dd027ea85753aac5541856fcce80455aa5828a
 SHA512:
-  metadata.gz: d5330318952bc212e50be07ac8a31defb8362b54dc595ba9f89bf5854444d473bfb79ba981680990c525af0394752f6eb5ebf12052132370988abbef5224f8da
-  data.tar.gz: 2532a733031bfe3f58c77a85bc761fe8fed6a961c2affeecc5a2bc4e681df830d89469cb15db6b853701c6c3fde58893580e00f2e917663c900b8a2682687071
+  metadata.gz: c68b5fcb8fedd59d00150e174277025fc6b40c5fa62663530cd504a70989e0250f4cda480451924cc2d7106acbb5cf1e5062f8434dc42d229be596bce2c7f1ae
+  data.tar.gz: bb086e17c28795076e00d7b00d343b85bafccf747e4426e21ba46835371dca87f941780e18c61507f277a131706ea4b0a4d169ccbb63d0f65d6d5517fde2bc18

data/.gitignore

@@ -7,4 +7,5 @@
 /doc/
 /pkg/
 /spec/reports/
-/tmp/
+/tmp/
+*.swp

data/.pryrc

@@ -0,0 +1,6 @@
+if defined?(PryDebugger)
+  Pry.commands.alias_command 'c', 'continue'
+  Pry.commands.alias_command 's', 'step'
+  Pry.commands.alias_command 'n', 'next'
+  Pry.commands.alias_command 'f', 'finish'
+end

data/README.md

@@ -2,7 +2,7 @@
 
 API versioning that promotes convention over configuration.
 
-The premise of this gem is that consumers of your API need versioning and different shapes of your resources. Without proper thought into versioning and shaping, your codebase can quickly resolve into a redundant and confusing state. This gem tries to solve that problem by allowing the API owner to use simple conventions -- Accept headers and ActiveModelSerializer namespacing -- to achieve controller reuse by controllers delegating resource versioning and shaping to the serializer level.
+The premise of this gem is that consumers of your API need versioning and different shapes of your resources. Without proper thought into versioning and shaping, your codebase can quickly resolve into a redundant and confusing state. This gem tries to solve that problem by allowing the API owner to use simple conventions -- Accept headers and ActiveModelSerializer namespacing -- to achieve controller reuse by controllers delegating resource versioning and shaping to the consumer.
 
 
 ## Example
@@ -39,37 +39,59 @@ Inside our controller we can reference the `shape` method, which returns the ser
 
 Now say we have several clients, each expecting a different serialized response.
 
+---
+
 A client on v1 would like a list of `foos` in short form:
-`curl http://localhost:3000/foos -H 'Accept: application/javascript; version=1 shape=short'`
+
+`curl http://localhost:3000/foos -H 'Accept: application/json; version=1 shape=short'`
+
+OR
+
+`curl http://localhost:3000/foos?version=1&shape=short`
 
 When we reference `shape` inside the controller, it returns the following constant: `Serializers::Foo::V1::FooShortSerializer`
 
+---
 
 A client on v2 would like a list of `foos` in short form:
-`curl http://localhost:3000/foos -H 'Accept: application/javascript; version=2 shape=short'`
+
+`curl http://localhost:3000/foos -H 'Accept: application/json; version=2 shape=short'`
+
+OR
+
+`curl http://localhost:3000/foos?version=2&shape=short`
 
 When we reference `shape` inside the controller, it returns the following constant: `Serializers::Foo::V2::FooShortSerializer`
 
+---
 
 A client on v1 would like a list of `foos` in full form:
-`curl http://localhost:3000/foos -H 'Accept: application/javascript; version=1 shape=full'`
+
+`curl http://localhost:3000/foos -H 'Accept: application/json; version=1 shape=full'`
+
+OR
+
+`curl http://localhost:3000/foos?version=1&shape=full`
 
 When we reference `shape` inside the controller, it returns the following constant: `Serializers::Foo::V1::FooFullSerializer`
 
+---
+
+Note: headers take precedence over query parameters if both are sent
 
 ## Configuring Defaults
 
 Both `acts_as_shapeable` and `shape` accept the following arguments:
 
-* `default_version`: The default version in cases where the header is not specified.
+* `default_version`: The default version in cases where the version is not specified.
 * `default_shape`: The deafault shape in cases where the shape is not specified.
 
 The options defined on `shape` have greater precedence over those defined on `acts_as_shapeable`.
 
-In cases where the version and/or the shape is not specified in the Accept Header Shapeable will instead use the provided defaults. If no default is provided, and nothing is specified in the header, Shapeable will raise an `UnresolvedShapeError`.
+In cases where the version and/or the shape is not specified in the Accept Header Shapeable will instead use the provided defaults. If no default is provided, and nothing is specified in the header or query params, Shapeable will raise an `UnresolvedShapeError`.
 
 Using the same example controller and directory structure from above, a client sends no headers:
-`curl http://localhost:3000/foos -H 'Accept: application/javascript;`
+`curl http://localhost:3000/foos -H 'Accept: application/json;`
 Shapeable uses the defaults provided, and resolves `shape` to the following constant: `Serializers::Foo::V1::FooShortSerializer`
 
 
@@ -94,13 +116,13 @@ There are a few additional options which allow you to decide whether you want to
 
 When `enforce_versioning` is set to false, version will be ignored, and the version module will not be prepended. So the following request
 
-`curl http://localhost:3000/foos -H 'Accept: application/javascript; shape=default'`
+`curl http://localhost:3000/foos -H 'Accept: application/json; shape=default'`
 
 Will be constructed as `Serializers::Foo::FooDefaultSerializer` without the version module prepended.
 
 When `enforce_shape` is set to false, shape will be optional. When shape is not specified, the constant will be constructed with no shape. So the following request:
 
-`curl http://localhost:3000/foos -H 'Accept: application/javascript; version=1'`
+`curl http://localhost:3000/foos -H 'Accept: application/json; version=1'`
 
 Will be constructed as `Serializers::Foo::V1::FooSerializer`.
 

data/lib/shapeable/configuration.rb

@@ -1,7 +1,13 @@
 module Shapeable
   class Configuration
 
-    attr_accessor :path, :default_version, :default_shape, :enforce_versioning, :enforce_shape
+    attr_accessor :path,
+      :default_version,
+      :default_shape,
+      :enforce_versioning,
+      :enforce_shape,
+      :shape_attr_override,
+      :version_attr_override
 
     def initialize
       @path = nil
@@ -9,6 +15,8 @@ module Shapeable
       @default_shape = nil
       @enforce_versioning = true
       @enforce_shape = true
+      @shape_attr_override = nil
+      @version_attr_override = nil
     end
 
     def as_json
@@ -17,7 +25,9 @@ module Shapeable
         default_version: default_version,
         default_shape: default_shape,
         enforce_versioning: enforce_versioning,
-        enforce_shape: enforce_shape
+        enforce_shape: enforce_shape,
+        shape_attr_override: shape_attr_override,
+        version_attr_override: version_attr_override
       }
     end
   end

data/lib/shapeable/errors.rb

@@ -12,9 +12,19 @@ module Shapeable
     end
 
     class UnresolvedShapeError < Exception
-      def initialize(msg = 'Unable to resolve shape.' \
-                     ' Try specifying a default version and shape.'
-                    )
+      def initialize(msg = 'Unable to resolve shape. Try specifying a default shape.')
+        super
+      end
+    end
+
+    class UnresolvedVersionError < Exception
+      def initialize(msg = 'Unable to resolve version. Try specifying a default version.')
+        super
+      end
+    end
+
+    class UnresolvedPathError < Exception
+      def initialize(msg = 'Unable to resolve path. Try specifying a path.')
         super
       end
     end

data/lib/shapeable/extenders.rb

@@ -2,13 +2,8 @@ module Shapeable
   module Extenders
 
     def acts_as_shapeable(**opts)
-      require_relative 'shape'
-      include Shapeable::Shape
-
-      class_eval do
-        define_method(:acts_as_shapeable_opts) do
-          opts
-        end
+      define_method(:acts_as_shapeable_opts) do
+        opts
       end
     end
 

data/lib/shapeable/shape.rb

@@ -2,59 +2,100 @@ require_relative 'errors'
 module Shapeable
   module Shape
 
-    def self.included base
-      base.class_eval do
-        def shape(shape_opts = {})
-          return unless request.accept
-          opts = merge_shapeable_options(
-            Shapeable.configuration.as_json, acts_as_shapeable_opts, shape_opts
-          )
-          normalize_shapeable_options(opts)
-          raise ArgumentError, 'Specify a path' unless opts[:path]
-          shape = resolve_shape(request.accept, opts[:default_shape])
-          if opts[:enforce_versioning]
-            version = resolve_version(request.accept, opts[:default_version])
-            raise Shapeable::Errors::UnresolvedShapeError unless version && shape if opts[:enforce_shape]
-            constant = construct_constant(opts[:path], shape: shape, version: version)
-          else
-            raise Shapeable::Errors::UnresolvedShapeError unless shape if opts[:enforce_shape]
-            constant = construct_constant(opts[:path], shape: shape)
-          end
-          constant
-        end
+    def self.included(klass)
+      klass.extend Shapeable::Extenders
+    end
+
+    def shape(default_shape_opts = {})
+      opts = merge_shapeable_options(
+        Shapeable.configuration.as_json,
+        acts_as_shapeable_opts,
+        default_shape_opts,
+        request_shape_options(
+          request,
+          Shapeable.configuration.as_json[:shape_attr_override] || 'shape',
+          Shapeable.configuration.as_json[:version_attr_override] || 'version',
+        )
+      )
+      normalize_shapeable_options!(opts)
+      validate_and_resolve_shape(opts)
+    end
+
+    def merge_shapeable_options(*opts)
+      opts.each_with_object({}) do |val, obj|
+        obj.merge!(val)
       end
     end
 
-    def normalize_shapeable_options(opts)
-      opts.keep_if do |k, _v|
-        [:path, :default_shape, :default_version, :enforce_versioning, :enforce_shape].include?(k)
+    def normalize_shapeable_options!(opts)
+      opts.keep_if do |k, _|
+        [
+          :path,
+          :default_shape,
+          :default_version,
+          :shape,
+          :version,
+          :enforce_versioning,
+          :enforce_shape
+        ].include?(k)
       end
     end
 
-    def merge_shapeable_options(*opts_array)
-      opts_array.each_with_object({}) do |val, obj|
-        obj.merge!(val)
+    def validate_and_resolve_shape(opts)
+      version = opts[:version] || opts[:default_version]
+      shape = opts[:shape] || opts[:default_shape]
+
+      if opts[:path].blank?
+        raise Shapeable::Errors::UnresolvedPathError
+      elsif opts[:enforce_versioning] && version.blank?
+        raise Shapeable::Errors::UnresolvedVersionError
+      elsif opts[:enforce_shape] && shape.blank?
+        raise Shapeable::Errors::UnresolvedShapeError
       end
+
+      if opts[:enforce_versioning]
+        construct_constant(opts[:path], shape: shape, version: version)
+      else
+        construct_constant(opts[:path], shape: shape)
+      end
+    end
+
+    def request_shape_options(request, shape_attr_name, version_attr_name)
+      {
+        version: resolve_header_version(request.accept, version_attr_name) || resolve_params_version(request.params, version_attr_name),
+        shape: resolve_header_shape(request.accept, shape_attr_name) || resolve_params_shape(request.params, shape_attr_name)
+      }.delete_if { |_, v| v.blank? }
+    end
+
+    def resolve_header_version(accept_header, version_attr_name)
+      if accept_header
+        version_str = accept_header[/#{version_attr_name}\s?=\s?(\d+)/, 1]
+        version_str.nil? ? nil : version_str.to_i
+      end
+    end
+
+    def resolve_header_shape(accept_header, shape_attr_name)
+      accept_header[/#{shape_attr_name}\s?=\s?(\w+)/, 1] if accept_header
     end
 
-    def resolve_version(accept_header, default)
-      version_str = accept_header[/version\s?=\s?(\d+)/, 1]
-      version_str.nil? ? default : version_str.to_i
+    def resolve_params_version(params, version_attr_name)
+      params[version_attr_name]
     end
 
-    def resolve_shape(accept_header, default)
-      accept_header[/shape\s?=\s?(\w+)/, 1] || default
+    def resolve_params_shape(params, shape_attr_name)
+      params[shape_attr_name]
     end
 
     def construct_constant(path, shape: nil, version: nil)
       resource = infer_resource_name(path)
-      if shape
-        return path.const_get("#{resource}#{shape.camelize}Serializer") unless version
-        path_with_version = path.const_get("V#{version}")
-        return path_with_version.const_get("#{resource}#{shape.camelize}Serializer")
+      if shape && version
+        path.const_get("V#{version}::#{resource}#{shape.camelize}Serializer")
+      elsif shape
+        path.const_get("#{resource}#{shape.camelize}Serializer")
+      elsif version
+        path.const_get("V#{version}::#{resource}Serializer")
       else
-        return path.const_get("#{resource}Serializer") unless version
-        return path_with_version.const_get("#{resource}Serializer")
+        path.const_get("#{resource}Serializer")
       end
     rescue NameError
       raise Shapeable::Errors::InvalidShapeError.new(path, shape, version: version)

data/lib/shapeable/version.rb

@@ -1,3 +1,3 @@
 module Shapeable
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

data/lib/shapeable.rb

@@ -30,8 +30,4 @@ module Shapeable
   end
 end
 
-if defined? ActionController::Base
-  ActionController::Base.class_eval do
-    extend Shapeable::Extenders
-  end
-end
+ActionController::Base.include Shapeable::Shape if defined? ActionController::Base

data/shapeable.gemspec

@@ -29,4 +29,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'activesupport'
   spec.add_development_dependency 'active_model_serializers'
   spec.add_development_dependency 'rspec-rails'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'pry-byebug'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shapeable
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Shawn O'Mara
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-29 00:00:00.000000000 Z
+date: 2017-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -67,6 +67,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  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: pry-byebug
+  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: |-
   The premise of this gem is that consumers of your API need versioning
                           and different shapes of your resources. Without proper thought into versioning
@@ -82,6 +110,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".pryrc"
 - Gemfile
 - LICENSE.md
 - README.md
@@ -113,7 +142,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
 summary: API versioning that promotes convention over configuration