sinatra-api 1.0.0 → 1.0.2

data/.yardopts

@@ -1 +1 @@
---protected -m markdown -r README.md
+--protected --private -m markdown -r README.md

data/lib/sinatra/api/callbacks.rb

@@ -22,18 +22,18 @@
 module Sinatra
   module API
     module Callbacks
-      attr_accessor :api_callbacks
+      attr_accessor :callbacks
 
       def self.extended(base)
-        base.api_callbacks = {}
+        base.callbacks = {}
       end
 
       def on(event, &callback)
-        (self.api_callbacks[event.to_sym] ||= []) << callback
+        (self.callbacks[event.to_sym] ||= []) << callback
       end
 
       def trigger(event, *args)
-        callbacks = self.api_callbacks[event.to_sym] || []
+        callbacks = self.callbacks[event.to_sym] || []
         callbacks.each do |callback|
           callback.call(*args)
         end

data/lib/sinatra/api/helpers.rb

@@ -19,217 +19,11 @@
 # SOFTWARE.
 #
 
-module Sinatra
-  # TODO: accept nested parameters
-  module API
-    public
-
-    # attr_accessor :resource_aliases
-
-    module Helpers
-      def api_call?
-        (request.accept || '').to_s.include?('json') ||
-        (request.content_type||'').to_s.include?('json')
-      end
-
-      # Define the required API arguments map. Any item defined
-      # not found in the supplied parameters of the API call will
-      # result in a 400 RC with a proper message marking the missing
-      # field.
-      #
-      # The map is a Hash of parameter keys and optional validator blocks.
-      #
-      # @example A map of required API call arguments
-      #   api_required!({ title: nil, user_id: nil })
-      #
-      # Each entry can be optionally mapped to a validation proc that will
-      # be invoked *if* the field was supplied. The proc will be passed
-      # the value of the field.
-      #
-      # If the value is invalid and you need to suspend the request, you
-      # must return a String object with an appropriate error message.
-      #
-      # @example Rejecting a title if it's rude
-      #   api_required!({
-      #     :title => lambda { |t| return "Don't be rude" if t && t =~ /rude/ }
-      #   })
-      #
-      # @note
-      #   The supplied value passed to validation blocks is not pre-processed,
-      #   so you must make sure that you check for nils or bad values in validator blocks!
-      def api_required!(args, h = params)
-        args.each_pair { |name, cnd|
-          if cnd.is_a?(Hash)
-            api_required!(cnd, h[name])
-            next
-          end
-
-          parse_api_argument(h, name, cnd, :required)
-        }
-      end
-
-      # Same as #api_required! except that fields defined in this map
-      # are optional and will be used only if they're supplied.
-      #
-      # @see #api_required!
-      def api_optional!(args, h = params)
-        args.each_pair { |name, cnd|
-          if cnd.is_a?(Hash)
-            api_optional!(cnd, h[name])
-            next
-          end
-
-          parse_api_argument(h, name, cnd, :optional)
-        }
-      end
-
-      # Consumes supplied parameters with the given keys from the API
-      # parameter map, and yields the consumed values for processing by
-      # the supplied block (if any).
-      #
-      # This is useful if:
-      #  1. a certain parameter does not correspond to a model attribute
-      #     and needs to be renamed, or is used in a validation context
-      #  2. the data needs special treatment
-      #  3. the data needs to be (re)formatted
-      #
-      def api_consume!(keys)
-        out  = nil
-
-        keys = [ keys ] unless keys.is_a?(Array)
-        keys.each do |k|
-          if val = @api[:required].delete(k.to_sym)
-            out = val
-            out = yield(val) if block_given?
-          end
-
-          if val = @api[:optional].delete(k.to_sym)
-            out = val
-            out = yield(val) if block_given?
-          end
-        end
-
-        out
-      end
-
-      def api_transform!(key, &handler)
-        if val = @api[:required][key.to_sym]
-          @api[:required][key.to_sym] = yield(val) if block_given?
-        end
-
-        if val = @api[:optional][key.to_sym]
-          @api[:optional][key.to_sym] = yield(val) if block_given?
-        end
-      end
-
-      def api_has_param?(key)
-        @api[:optional].has_key?(key)
-      end
-
-      def api_param(key)
-        @api[:optional][key.to_sym] || @api[:required][key.to_sym]
-      end
-
-      # Returns a Hash of the *supplied* request parameters. Rejects
-      # any parameter that was not defined in the REQUIRED or OPTIONAL
-      # maps (or was consumed).
-      #
-      # @param Hash q A Hash of attributes to merge with the parameters,
-      #               useful for defining defaults
-      def api_params(q = {})
-        @api[:optional].deep_merge(@api[:required]).deep_merge(q)
-      end
-
-      def api_clear!()
-        @api = { required: {}, optional: {} }
-      end
-
-      alias_method :api_reset!, :api_clear!
-
-      # Attempt to locate a resource based on an ID supplied in a request parameter.
-      #
-      # If the param map contains a resource id (ie, :folder_id),
-      # we attempt to locate and expose it to the route.
-      #
-      # A 404 is raised if:
-      #   1. the scope is missing (@space for folder, @space or @folder for page)
-      #   2. the resource couldn't be identified in its scope (@space or @folder)
-      #
-      # If the resources were located, they're accessible using @folder or @page.
-      #
-      # The route can be halted using the :requires => [] condition when it expects
-      # a resource.
-      #
-      # @example using :requires to reject a request with an invalid @page
-      #   get '/folders/:folder_id/pages/:page_id', :requires => [ :page ] do
-      #     @page.show    # page is good
-      #     @folder.show  # so is its folder
-      #   end
-      #
-      def __api_locate_resource(r, container = nil)
-
-        resource_id = params[r + '_id'].to_i
-        rklass      = r.camelize
-
-        collection = case
-        when container.nil?;  eval "#{ResourcePrefix}#{rklass}"
-        else;                 container.send("#{r.to_plural}")
-        end
-
-        puts "locating resource #{r} with id #{resource_id} from #{collection} [#{container}]"
-
-        resource = collection.get(resource_id)
-
-        if !resource
-          m = "No such resource: #{rklass}##{resource_id}"
-          if container
-            m << " in #{container.class.name.to_s}##{container.id}"
-          end
-
-          halt 404, m
-        end
-
-        if respond_to?(:can?)
-          unless can? :access, resource
-            halt 403, "You do not have access to this #{rklass} resource."
-          end
-        end
-
-        instance_variable_set('@'+r, resource)
-
-        API.trigger :resource_located, resource, r
-
-        API.aliases_for(r).each { |resource_alias|
-          instance_variable_set('@'+resource_alias, resource)
-          puts "API: resource #{rklass} exported to @#{resource_alias}"
-        }
-
-        resource
-      end
-
-      private
-
-      def parse_api_argument(h = params, name, cnd, type)
-        cnd ||= lambda { |*_| true }
-        name = name.to_s
-
-        unless [:required, :optional].include?(type)
-          raise ArgumentError, 'API Argument type must be either :required or :optional'
-        end
-
-        if !h.has_key?(name)
-          if type == :required
-            halt 400, "Missing required parameter :#{name}"
-          end
-        else
-          if cnd.respond_to?(:call)
-            errmsg = cnd.call(h[name])
-            halt 400, { :"#{name}" => errmsg } if errmsg && errmsg.is_a?(String)
-          end
-
-          @api[type][name.to_sym] = h[name]
-        end
-      end
+module Sinatra::API
+  module Helpers
+    def api_call?
+      (request.accept || '').to_s.include?('json') ||
+      (request.content_type||'').to_s.include?('json')
     end
   end
 end

data/lib/sinatra/api/parameters.rb

@@ -0,0 +1,167 @@
+# Copyright (c) 2013 Algol Labs, LLC. <dev@algollabs.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+
+module Sinatra::API
+  # API for defining parameters an endpoint requires or accepts, their types,
+  # and optional validators.
+  #
+  # TODO: accept nested parameters
+  module Parameters
+    # Define the required API arguments map. Any item defined
+    # not found in the supplied parameters of the API call will
+    # result in a 400 RC with a proper message marking the missing
+    # field.
+    #
+    # The map is a Hash of parameter keys and optional validator blocks.
+    #
+    # @example A map of required API call arguments
+    #   api_required!({ title: nil, user_id: nil })
+    #
+    # Each entry can be optionally mapped to a validation proc that will
+    # be invoked *if* the field was supplied. The proc will be passed
+    # the value of the field.
+    #
+    # If the value is invalid and you need to suspend the request, you
+    # must return a String object with an appropriate error message.
+    #
+    # @example Rejecting a title if it's rude
+    #   api_required!({
+    #     :title => lambda { |t| return "Don't be rude" if t && t =~ /rude/ }
+    #   })
+    #
+    # @note
+    #   The supplied value passed to validation blocks is not pre-processed,
+    #   so you must make sure that you check for nils or bad values in validator blocks!
+    def api_required!(args, h = params)
+      args.each_pair do |name, cnd|
+        if cnd.is_a?(Hash)
+          api_required!(cnd, h[name])
+          next
+        end
+
+        parse_api_argument(h, name, cnd, :required)
+      end
+    end
+
+    # Same as #api_required! except that fields defined in this map
+    # are optional and will be used only if they're supplied.
+    #
+    # @see #api_required!
+    def api_optional!(args, h = params)
+      args.each_pair { |name, cnd|
+        if cnd.is_a?(Hash)
+          api_optional!(cnd, h[name])
+          next
+        end
+
+        parse_api_argument(h, name, cnd, :optional)
+      }
+    end
+
+    # Consumes supplied parameters with the given keys from the API
+    # parameter map, and yields the consumed values for processing by
+    # the supplied block (if any).
+    #
+    # This is useful if:
+    #  1. a certain parameter does not correspond to a model attribute
+    #     and needs to be renamed, or is used in a validation context
+    #  2. the data needs special treatment
+    #  3. the data needs to be (re)formatted
+    #
+    def api_consume!(keys)
+      out  = nil
+
+      keys = [ keys ] unless keys.is_a?(Array)
+      keys.each do |k|
+        if val = @api[:required].delete(k.to_sym)
+          out = val
+          out = yield(val) if block_given?
+        end
+
+        if val = @api[:optional].delete(k.to_sym)
+          out = val
+          out = yield(val) if block_given?
+        end
+      end
+
+      out
+    end
+
+    def api_transform!(key, &handler)
+      if val = @api[:required][key.to_sym]
+        @api[:required][key.to_sym] = yield(val) if block_given?
+      end
+
+      if val = @api[:optional][key.to_sym]
+        @api[:optional][key.to_sym] = yield(val) if block_given?
+      end
+    end
+
+    def api_has_param?(key)
+      @api[:optional].has_key?(key)
+    end
+
+    def api_param(key)
+      @api[:optional][key.to_sym] || @api[:required][key.to_sym]
+    end
+
+    # Returns a Hash of the *supplied* request parameters. Rejects
+    # any parameter that was not defined in the REQUIRED or OPTIONAL
+    # maps (or was consumed).
+    #
+    # @param [Hash] q
+    #   A Hash of attributes to merge with the parameters, useful for defining
+    #   defaults.
+    def api_params(q = {})
+      @api[:optional].deep_merge(@api[:required]).deep_merge(q)
+    end
+
+    def api_clear!()
+      @api = { required: {}, optional: {} }
+    end
+
+    alias_method :api_reset!, :api_clear!
+
+    private
+
+    def parse_api_argument(h = params, name, cnd, type)
+      cnd ||= lambda { |*_| true }
+      name = name.to_s
+
+      unless [:required, :optional].include?(type)
+        raise ArgumentError, 'API Argument type must be either :required or :optional'
+      end
+
+      if !h.has_key?(name)
+        if type == :required
+          halt 400, "Missing required parameter :#{name}"
+        end
+      else
+        if cnd.respond_to?(:call)
+          errmsg = cnd.call(h[name])
+          halt 400, { :"#{name}" => errmsg } if errmsg && errmsg.is_a?(String)
+        end
+
+        @api[type][name.to_sym] = h[name]
+      end
+    end
+  end
+end

data/lib/sinatra/api/resource_aliases.rb

@@ -5,11 +5,7 @@ module Sinatra
 
       def self.extended(base)
         base.resource_aliases = {}
-        base.on :resource_located do |resource, name|
-          base.aliases_for(name).each do |resource_alias|
-            instance_variable_set("@#{resource_alias}", resource)
-          end
-        end
+        base.on :resource_located, &method(:export_alias)
       end
 
       def alias_resource(original, resource_alias)
@@ -31,6 +27,15 @@ module Sinatra
       def reset_aliases!
         self.resource_aliases = {}
       end
+
+      private
+
+      def self.export_alias(resource, name)
+        base = Sinatra::API
+        base.aliases_for(name).each do |resource_alias|
+          base.instance.instance_variable_set("@#{resource_alias}", resource)
+        end
+      end
     end
   end
 end

data/lib/sinatra/api/resources.rb

@@ -0,0 +1,84 @@
+# Copyright (c) 2013 Algol Labs, LLC. <dev@algollabs.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+
+module Sinatra::API
+  # API for defining parameters an endpoint requires or accepts, their types,
+  # and optional validators.
+  #
+  module Resources
+    private
+
+    # Attempt to locate a resource based on an ID supplied in a request parameter.
+    #
+    # If the param map contains a resource id (ie, :folder_id),
+    # we attempt to locate and expose it to the route.
+    #
+    # A 404 is raised if:
+    #   1. the scope is missing (@space for folder, @space or @folder for page)
+    #   2. the resource couldn't be identified in its scope (@space or @folder)
+    #
+    # If the resources were located, they're accessible using @folder or @page.
+    #
+    # The route can be halted using the :requires => [] condition when it expects
+    # a resource.
+    #
+    # @example using :requires to reject a request with an invalid @page
+    #   get '/folders/:folder_id/pages/:page_id', :requires => [ :page ] do
+    #     @page.show    # page is good
+    #     @folder.show  # so is its folder
+    #   end
+    #
+    def api_locate_resource(r, container = nil)
+      resource_id = params[r + '_id'].to_i
+      rklass      = r.camelize
+
+      collection = case
+      when container.nil?;  eval "#{ResourcePrefix}#{rklass}"
+      else;                 container.send("#{r.to_plural}")
+      end
+
+      puts "locating resource #{r} with id #{resource_id} from #{collection} [#{container}]"
+
+      resource = collection.get(resource_id)
+
+      if !resource
+        m = "No such resource: #{rklass}##{resource_id}"
+        if container
+          m << " in #{container.class.name.to_s}##{container.id}"
+        end
+
+        halt 404, m
+      end
+
+      if respond_to?(:can?)
+        unless can? :access, resource
+          halt 403, "You do not have access to this #{rklass} resource."
+        end
+      end
+
+      instance_variable_set('@'+r, resource)
+
+      Sinatra::API.trigger :resource_located, resource, r
+
+      resource
+    end
+  end
+end

data/lib/sinatra/api/version.rb

@@ -21,6 +21,6 @@
 
 module Sinatra
   module API
-    VERSION = "1.0.0"
+    VERSION = "1.0.2"
   end
 end

data/lib/sinatra/api.rb

@@ -30,6 +30,8 @@ require 'sinatra/api/version'
 require 'sinatra/api/callbacks'
 require 'sinatra/api/helpers'
 require 'sinatra/api/resource_aliases'
+require 'sinatra/api/resources'
+require 'sinatra/api/parameters'
 
 module Sinatra
   module API
@@ -37,37 +39,48 @@ module Sinatra
     extend ResourceAliases
 
     class << self
+      # @!attribute logger
+      #   @return [ActiveSupport::Logger]
+      #   A Logger instance.
       attr_accessor :logger
-    end
 
-    ResourcePrefix = '::'
+      # @!attribute instance
+      #   @return [Sinatra::Application]
+      #   The Sinatra instance that is evaluating the current request.
+      attr_accessor :instance
 
-    # Parse a JSON construct from a string stream.
-    #
-    # Override this to use a custom JSON parser, if necessary.
-    #
-    # @param [String] stream The raw JSON stream.
-    #
-    # @return [Hash] A Hash of the parsed JSON.
-    def parse_json(stream)
-      ::JSON.parse(stream)
+      # Parse a JSON construct from a string stream.
+      #
+      # Override this to use a custom JSON parser, if necessary.
+      #
+      # @param [String] stream The raw JSON stream.
+      #
+      # @return [Hash] A Hash of the parsed JSON.
+      def parse_json(stream)
+        ::JSON.parse(stream)
+      end
     end
 
+    ResourcePrefix = '::'
+
     def self.registered(app)
+      base = self
       self.logger = ActiveSupport::Logger.new(STDOUT)
 
-      app.helpers Helpers
+      app.helpers Helpers, Parameters, Resources
       app.before do
+        base.instance = self
+
         @api = { required: {}, optional: {} }
         @parent_resource = nil
 
         if api_call?
           request.body.rewind
-          body = request.body.read.to_s || ''
+          raw_json = request.body.read.to_s || ''
 
-          unless body.empty?
+          unless raw_json.empty?
             begin
-              params.merge!(parse_json(body))
+              params.merge!(base.parse_json(raw_json))
             rescue ::JSON::ParserError => e
               logger.warn e.message
               logger.warn e.backtrace
@@ -82,7 +95,7 @@ module Sinatra
         condition do
           @required = resources.collect { |r| r.to_s }
           @required.each do |r|
-            @parent_resource = __api_locate_resource(r, @parent_resource)
+            @parent_resource = api_locate_resource(r, @parent_resource)
           end
         end
       end

data/spec/integration/api_spec.rb

@@ -0,0 +1,15 @@
+describe Sinatra::API::Helpers do
+  include_examples 'integration specs'
+
+  it 'should catch and reject malformed JSON' do
+    app.post '/' do
+      api_required!({
+        id: nil
+      })
+    end
+
+    post '/', 'x]'
+    last_response.status.should == 400
+    last_response.body.should match(/malformed json/i)
+  end
+end

data/spec/support/integration_specs.rb

@@ -1,5 +1,8 @@
 shared_examples_for "integration specs" do
   before :each do
     Router.purge('/')
+
+    header 'Content-Type', 'application/json'
+    header 'Accept', 'application/json'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-api
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -132,10 +132,13 @@ files:
 - lib/sinatra/api.rb
 - lib/sinatra/api/callbacks.rb
 - lib/sinatra/api/helpers.rb
+- lib/sinatra/api/parameters.rb
 - lib/sinatra/api/resource_aliases.rb
+- lib/sinatra/api/resources.rb
 - lib/sinatra/api/version.rb
 - spec/unit/callbacks_spec.rb
 - spec/unit/resource_aliases_spec.rb
+- spec/integration/api_spec.rb
 - spec/integration/helpers_spec.rb
 - spec/integration/resource_aliases_spec.rb
 - spec/support/integration_specs.rb