interpol 0.2.2 → 0.3.0

data/README.md

@@ -22,6 +22,9 @@ definitions:
   ensure that your real API returns valid responses.
 * `Interpol::DocumentationApp` builds a sinatra app that renders
   documentation for your API based on the endpoint definitions.
+* `Interpol::Sinatra::RequestParamsParser` validates and parses
+  a sinatra `params` hash based on your endpoint params schema
+  definitions.
 
 You can use any of these tools individually or some combination of all
 of them.
@@ -51,6 +54,15 @@ name: user_projects
 route: /users/:user_id/projects
 method: GET
 definitions:
+  - message_type: request
+    versions: ["1.0"]
+    path_params:
+      type: object
+      properties:
+        user_id:
+          type: integer
+    schema: {}
+    examples: []
   - message_type: response
     versions: ["1.0"]
     status_codes: ["2xx", "404"]
@@ -107,6 +119,9 @@ Let's look at this YAML file, point-by-point:
   attribute that defaults to all status codes. Valid formats for a status code are 3
   characters. Each character must be a digit (0-9) or 'x' (wildcard). The following strings
   are all valid: "200", "4xx", "x0x".
+* `path_params` lists the path parameters that are used by a request to
+  this endpoint. You can also list `query_params` in the same manner.
+  These are both used by `Interpol::Sinatra::RequestParamsParser`.
 * The `schema` contains a [JSON schema](http://tools.ietf.org/html/draft-zyp-json-schema-03)
   description of the contents of the endpoint. This schema definition is used by the
   `SchemaValidation` middleware to ensure that your implementation of the endpoint
@@ -136,14 +151,15 @@ Interpol.default_configuration do |config|
   # This is useful when you need to extract the version from a
   # request header (e.g. Accept) or from the request URI.
   #
-  # Needed by Interpol::StubApp and Interpol::ResponseSchemaValidator.
+  # Needed by Interpol::StubApp, Interpol::ResponseSchemaValidator
+  # and Interpol::Sinatra::RequestParamsParser.
   config.api_version '1.0'
 
   # Determines the stub app response when the requested version is not
-  # available. This block will be eval'd in the context of the stub app
+  # available. This block will be eval'd in the context of a
   # sinatra application, so you can use sinatra helpers like `halt` here.
   #
-  # Needed by Interpol::StubApp.
+  # Needed by Interpol::StubApp and Interpol::Sinatra::RequestParamsParser.
   config.on_unavailable_request_version do |requested_version, available_versions|
     message = JSON.dump(
       "message" => "Not Acceptable",
@@ -189,6 +205,17 @@ Interpol.default_configuration do |config|
   config.filter_example_data do |example, request_env|
     example.data["current_url"] = Rack::Request.new(request_env).url
   end
+
+  # Determines what to do when Interpol::Sinatra::RequestParamsParser
+  # detects invalid path or query parameters based on their schema
+  # definitions. This block will be eval'd in the context of your
+  # sinatra application so you can use any helper methods such as
+  # `halt`.
+  #
+  # Used by Interpol::Sinatra::RequestParamsParser.
+  config.on_invalid_sinatra_request_params do |error|
+    halt 400, JSON.dump(:error => error.message)
+  end
 end
 
 ```
@@ -307,6 +334,56 @@ run doc_app
 Note: the documentation app is definitely a work-in-progress and I'm not
 a front-end/UI developer. I'd happily accept a pull request improving it!
 
+### Interpol::Sinatra::RequestParamsParser
+
+This Sinatra middleware does a few things:
+
+* It validates the path and query params according to the schema
+  definitions in your YAML files.
+* It replaces the `params` hash with an object that:
+  * Exposes a method for each defined parameter--so you can use
+    `params.user_id` rather than `params[:user_id]`. Undefined
+    params will raise a `NoMethodError` rather than getting `nil`
+    as you would with the normal params hash.
+  * Exposes a predicate method for each defined parameter -- so
+    you can use `params.user_id?` in a conditional rather than
+    `params.user_id`.
+  * Parses each parameter value into an appropriate object based on
+    the defined schema:
+    * An `integer` param will be exposed as a `Fixnum`.
+    * A `number` param will be exposed as a `Float`.
+    * A `null` param will be exposed as `nil` (rather than the empty
+      string).
+    * A `boolean` param will be exposed as `true` or `false` (rather
+      than the corresponding strings).
+    * A `string` param with a `date` format will be exposed as a `Date`.
+    * A `string` param with a `date-time` format will be exposed as a `Time`.
+    * A `string` param with a `uri` format will be exposed as `URI`.
+    * Anything that cannot be parsed into an object will be exposed as
+      its original `string` value.
+* It exposes the original params hash as `unparsed_params`.
+
+Usage:
+
+``` ruby
+require 'sinatra/base'
+require 'interpol/sinatra/request_params_parser'
+
+class MySinatraApp < Sinatra::Base
+  # The block is only necessary if you want to override the
+  # default config or have not set a default config.
+  use Interpol::Sinatra::RequestParamsParser do |config|
+    config.on_invalid_sinatra_request_params do |error|
+      halt 400, JSON.dump(:error => error.message)
+    end
+  end
+
+  get '/users/:user_id' do
+    JSON.dump User.find(params.user_id)
+  end
+end
+```
+
 ## Contributing
 
 1. Fork it

data/Rakefile

@@ -17,7 +17,7 @@ if defined?(RUBY_ENGINE) && RUBY_ENGINE == 'ruby' # MRI only
     cane.style_measure = 100
 
     cane.abc_exclude = %w[
-      Interpol::Endpoint#definitions
+      Interpol::Configuration#register_default_callbacks
     ]
   end
 else

data/lib/interpol/configuration.rb

@@ -18,10 +18,9 @@ module Interpol
     end
 
   private
+
     def find_definitions_for(endpoint, version, message_type)
-      endpoint.definitions.find do |d|
-          d.first.version == version && d.first.message_type == message_type
-      end || []
+      endpoint.find_definition(version, message_type) { [] }
     end
 
     def with_endpoint_matching(method, path)
@@ -86,6 +85,14 @@ module Interpol
       execution_context.instance_exec(*args, &@unavailable_request_version_block)
     end
 
+    def on_invalid_sinatra_request_params(&block)
+      @invalid_sinatra_request_params_block = block
+    end
+
+    def sinatra_request_params_invalid(execution_context, *args)
+      execution_context.instance_exec(*args, &@invalid_sinatra_request_params_block)
+    end
+
     def filter_example_data(&block)
       filter_example_data_blocks << block
     end
@@ -145,6 +152,10 @@ module Interpol
                   "Available: #{available}"
         halt 406, JSON.dump(:error => message)
       end
+
+      on_invalid_sinatra_request_params do |error|
+        halt 400, JSON.dump(:error => error.message)
+      end
     end
   end
 end

data/lib/interpol/define_singleton_method.rb

@@ -0,0 +1,10 @@
+module Interpol
+  # 1.9 has Object#define_singleton_method but 1.8 does not.
+  # This provides 1.8 compatibility for the places we need it.
+  module DefineSingletonMethod
+    def define_singleton_method(name, &block)
+      (class << self; self; end).send(:define_method, name, &block)
+    end
+  end
+end
+

data/lib/interpol/documentation_app/views/endpoint.erb

@@ -3,15 +3,13 @@
     <h1><%= endpoint.name %></h1>
     <h2><%= endpoint.method.to_s.upcase %> <%= endpoint.route %></h2>
 
-    <% endpoint.definitions.each do |definitions| %>
-      <% definitions.each do |definition| %>
-        <div class="versioned-endpoint-definition">
-          <h3><%= definition.message_type.capitalize %> - Version <%= definition.version %> - <%= definition.status_codes %></h3>
-          <br/>
-          <%= Interpol::Documentation.html_for_schema(definition.schema) %>
-        </div>
-        <hr/>
-      <% end %>
+    <% endpoint.definitions.each do |definition| %>
+      <div class="versioned-endpoint-definition">
+        <h3><%= definition.message_type.capitalize %> - Version <%= definition.version %> - <%= definition.status_codes %></h3>
+        <br/>
+        <%= Interpol::Documentation.html_for_schema(definition.schema) %>
+      </div>
+      <hr/>
     <% end %>
   </div>
 </div><!--/span-->

data/lib/interpol/documentation_app.rb

@@ -94,7 +94,7 @@ module Interpol
       attr_reader :app
 
       def initialize(config)
-        @app = Sinatra.new do
+        @app = ::Sinatra.new do
           dir = File.dirname(File.expand_path(__FILE__))
           set :views, "#{dir}/documentation_app/views"
           set :public_folder, "#{dir}/documentation_app/public"

data/lib/interpol/dynamic_struct.rb

@@ -0,0 +1,37 @@
+require 'interpol/define_singleton_method' unless Object.method_defined?(:define_singleton_method)
+
+module Interpol
+  # Transforms an arbitrarily deeply nested hash into a dot-syntax
+  # object. Useful as an alternative to a hash since it is "strongly typed"
+  # in the sense that fat-fingered property names result in a NoMethodError,
+  # rather than getting a nil as you would with a hash.
+  class DynamicStruct
+    attr_reader :attribute_names, :to_hash
+
+    def initialize(hash)
+      @to_hash = hash
+      @attribute_names = hash.keys.map(&:to_sym)
+
+      hash.each do |key, value|
+        value = method_value_for(value)
+        define_singleton_method(key) { value }
+        define_singleton_method("#{key}?") { !!value }
+      end
+    end
+
+  private
+
+    def method_value_for(hash_value)
+      return self.class.new(hash_value) if hash_value.is_a?(Hash)
+
+      if hash_value.is_a?(Array) && hash_value.all? { |v| v.is_a?(Hash) }
+        return hash_value.map { |v| self.class.new(v) }
+      end
+
+      hash_value
+    end
+
+    include DefineSingletonMethod unless method_defined?(:define_singleton_method)
+  end
+end
+

data/lib/interpol/each_with_object.rb

@@ -0,0 +1,9 @@
+# 1.9 has Enumerable#each_with_object, but 1.8 does not.
+# This provides 1.8 compat for the places where we use each_with_object.
+module Enumerable
+  def each_with_object(object)
+    each { |item| yield item, object }
+    object
+  end
+end
+

data/lib/interpol/endpoint.rb

@@ -1,5 +1,6 @@
 require 'json-schema'
 require 'interpol/errors'
+require 'forwardable'
 
 module JSON
   # The JSON-schema namespace
@@ -44,18 +45,24 @@ module Interpol
       @name        = fetch_from(endpoint_hash, 'name')
       @route       = fetch_from(endpoint_hash, 'route')
       @method      = fetch_from(endpoint_hash, 'method').downcase.to_sym
-      @definitions = extract_definitions_from(endpoint_hash)
+
+      @definitions_hash, @all_definitions = extract_definitions_from(endpoint_hash)
+
       validate_name!
     end
 
     def find_definition!(version, message_type)
-      @definitions.fetch([message_type, version]) do
+      find_definition(version, message_type) do
         message = "No definition found for #{name} endpoint for version #{version}"
         message << " and message_type #{message_type}"
         raise NoEndpointDefinitionFoundError.new(message)
       end
     end
 
+    def find_definition(version, message_type, &block)
+      @definitions_hash.fetch([message_type, version], &block)
+    end
+
     def find_example_for!(version, message_type)
       find_definition!(version, message_type).first.examples.first
     end
@@ -65,17 +72,19 @@ module Interpol
     end
 
     def available_versions
-      definitions.map { |d| d.first.version }
+      @all_definitions.inject(Set.new) do |set, definition|
+        set << definition.version
+      end.to_a
     end
 
     def definitions
       # sort all requests before all responses
       # sort higher version numbers before lower version numbers
-      @definitions.values.sort do |x,y|
-        if x.first.message_type == y.first.message_type
-          y.first.version <=> x.first.version
+      @sorted_definitions ||= @all_definitions.sort do |x, y|
+        if x.message_type == y.message_type
+          y.version <=> x.version
         else
-          x.first.message_type <=> y.first.message_type
+          x.message_type <=> y.message_type
         end
       end
     end
@@ -104,16 +113,19 @@ module Interpol
 
     def extract_definitions_from(endpoint_hash)
       definitions = Hash.new { |h, k| h[k] = [] }
+      all_definitions = []
 
       fetch_from(endpoint_hash, 'definitions').each do |definition|
         fetch_from(definition, 'versions').each do |version|
           message_type = definition.fetch('message_type', DEFAULT_MESSAGE_TYPE)
           key = [message_type, version]
-          definitions[key] << EndpointDefinition.new(name, version, message_type, definition)
+          endpoint_definition = EndpointDefinition.new(self, version, message_type, definition)
+          definitions[key] << endpoint_definition
+          all_definitions << endpoint_definition
         end
       end
 
-      definitions
+      return definitions, all_definitions
     end
 
     def validate_name!
@@ -128,21 +140,33 @@ module Interpol
   # Provides the means to validate data against that version of the schema.
   class EndpointDefinition
     include HashFetcher
-    attr_reader :endpoint_name, :message_type, :version, :schema,
+    attr_reader :endpoint, :message_type, :version, :schema,
                 :path_params, :query_params, :examples
+    extend Forwardable
+    def_delegators :endpoint, :route
 
-    def initialize(endpoint_name, version, message_type, definition)
-      @endpoint_name  = endpoint_name
+    DEFAULT_PARAM_HASH = { 'type' => 'object', 'properties' => {} }
+
+    def initialize(endpoint, version, message_type, definition)
+      @endpoint       = endpoint
       @message_type   = message_type
       @status_codes   = StatusCodeMatcher.new(definition['status_codes'])
       @version        = version
       @schema         = fetch_from(definition, 'schema')
-      @path_params    = definition.fetch('path_params', {})
-      @query_params   = definition.fetch('query_params', {})
-      @examples       = fetch_from(definition, 'examples').map { |e| EndpointExample.new(e, self) }
+      @path_params    = definition.fetch('path_params', DEFAULT_PARAM_HASH.dup)
+      @query_params   = definition.fetch('query_params', DEFAULT_PARAM_HASH.dup)
+      @examples       = extract_examples_from(definition)
       make_schema_strict!(@schema)
     end
 
+    def request?
+      message_type == "request"
+    end
+
+    def endpoint_name
+      @endpoint.name
+    end
+
     def validate_data!(data)
       errors = ::JSON::Validator.fully_validate_schema(schema)
       raise ValidationError.new(errors, nil, description) if errors.any?
@@ -166,6 +190,14 @@ module Interpol
       @example_status_code ||= @status_codes.example_status_code
     end
 
+    def parse_request_params(request_params)
+      request_params_parser.parse(request_params)
+    end
+
+    def request_params_parser
+      @request_params_parser ||= RequestParamsParser.new(self)
+    end
+
   private
 
     def make_schema_strict!(raw_schema, modify_object=true)
@@ -180,6 +212,12 @@ module Interpol
       raw_schema['additionalProperties'] ||= false
       raw_schema['required'] = !raw_schema.delete('optional')
     end
+
+    def extract_examples_from(definition)
+      fetch_from(definition, 'examples').map do |ex|
+        EndpointExample.new(ex, self)
+      end
+    end
   end
 
   # Holds the acceptable status codes for an enpoint entry

data/lib/interpol/request_params_parser.rb

@@ -0,0 +1,263 @@
+require 'interpol'
+require 'interpol/dynamic_struct'
+require 'uri'
+require 'interpol/each_with_object' unless Enumerable.method_defined?(:each_with_object)
+
+module Interpol
+  # This class is designed to parse and validate a rails or sinatra
+  # style params hash based on the path_params/query_params
+  # declarations of an endpoint request definition.
+  #
+  # The path_params and query_params declarations are merged together
+  # during validation, since both rails and sinatra give users a single
+  # params hash that contains the union of both kinds of params.
+  #
+  # Note that the validation here takes some liberties; it supports
+  # '3' as well as 3 for 'integer' params, for example, because it
+  # assumes that the values in a params hash are almost certainly going
+  # to be strings since that's how rails and sinatra give them to you.
+  #
+  # The parsed params object supports dot-syntax for accessing parameters
+  # and will convert values where feasible (e.g. '3' = 3, 'true' => true, etc).
+  class RequestParamsParser
+    def initialize(endpoint_definition)
+      @validator = ParamValidator.new(endpoint_definition)
+      @validator.validate_path_params_valid_for_route!
+      @converter = ParamConverter.new(@validator.param_definitions)
+    end
+
+    def parse(params)
+      validate!(params)
+      DynamicStruct.new(@converter.convert params)
+    end
+
+    def validate!(params)
+      @validator.validate!(params)
+    end
+
+    # Private: This takes care of the validation.
+    class ParamValidator
+      def initialize(endpoint_definition)
+        @endpoint_definition = endpoint_definition
+        @params_schema = build_params_schema
+      end
+
+      def validate_path_params_valid_for_route!
+        route = @endpoint_definition.route
+        invalid_params = property_defs_from(:path_params).keys.reject do |param|
+          route =~ %r</:#{Regexp.escape(param)}(/|$)>
+        end
+
+        return if invalid_params.none?
+        raise InvalidPathParamsError.new(*invalid_params)
+      end
+
+      def validate!(params)
+        errors = ::JSON::Validator.fully_validate(@params_schema, params)
+        raise ValidationError.new(errors, params, description) if errors.any?
+      end
+
+      def param_definitions
+        @param_definitions ||= property_defs_from(:path_params).merge \
+          property_defs_from(:query_params)
+      end
+
+    private
+
+      def description
+        @description ||= "#{@endpoint_definition.description} - request params"
+      end
+
+      def property_defs_from(meth)
+        schema = @endpoint_definition.send(meth)
+
+        unless schema['type'] == 'object'
+          raise InvalidParamsDefinitionError,
+            "The #{meth} of #{@endpoint_definition.description} " +
+            "is not typed as an object expected."
+        end
+
+        schema.fetch('properties') do
+          raise InvalidParamsDefinitionError,
+            "The #{meth} of #{@endpoint_definition.description} " +
+            "does not contain 'properties' as required."
+        end
+      end
+
+      def build_params_schema
+        path_params = @endpoint_definition.path_params
+        query_params = @endpoint_definition.query_params
+
+        query_params.merge(path_params).tap do |schema|
+          schema['properties'] = adjusted_definitions
+          schema['additionalProperties'] = false if no_additional_properties?
+        end
+      end
+
+      def adjusted_definitions
+        param_definitions.each_with_object({}) do |(name, schema), hash|
+          hash[name] = adjusted_schema(schema)
+        end
+      end
+
+      def no_additional_properties?
+        [
+          @endpoint_definition.path_params,
+          @endpoint_definition.query_params
+        ].none? { |params| params['additionalProperties'] }
+      end
+
+      STRING_EQUIVALENTS = {
+        'string'  => nil,
+        'integer' => { 'type' => 'string', 'pattern' => '^\-?\d+$' },
+        'number'  => { 'type' => 'string', 'pattern' => '^\-?\d+(\.\d+)?$' },
+        'boolean' => { 'type' => 'string', 'enum'    => %w[ true false ] },
+        'null'    => { 'type' => 'string', 'enum'    => [''] }
+      }
+
+      def adjusted_schema(schema)
+        types = Array(schema['type'])
+
+        string_equivalents = types.map do |type|
+          STRING_EQUIVALENTS.fetch(type) do
+            unless type.is_a?(Hash) # a nested union type
+              raise UnsupportedTypeError.new(type)
+            end
+          end
+        end.compact
+
+        schema.merge('type' => (types + string_equivalents)).tap do |adjusted|
+          adjusted['required'] = true unless adjusted['optional']
+        end
+      end
+    end
+
+    # Private: This takes care of the parameter conversions.
+    class ParamConverter
+      attr_reader :param_definitions
+
+      def initialize(param_definitions)
+        @param_definitions = param_definitions
+      end
+
+      def convert(params)
+        @param_definitions.keys.each_with_object({}) do |name, hash|
+          hash[name] = if params.has_key?(name)
+            convert_param(name, params.fetch(name))
+          else
+            nil
+          end
+        end
+      end
+
+    private
+
+      def convert_param(name, value)
+        definition = param_definitions.fetch(name)
+
+        Array(definition['type']).each do |type|
+          converter = converter_for(type, definition)
+
+          begin
+            return converter.call(value)
+          rescue ArgumentError => e
+            # Try the next unioned type...
+          end
+        end
+
+        raise CannotBeParsedError, "The #{name} #{value.inspect} cannot be parsed"
+      end
+
+      BOOLEANS = { 'true'  => true,  true  => true,
+                   'false' => false, false => false }
+      def self.convert_boolean(value)
+        BOOLEANS.fetch(value) do
+          raise ArgumentError, "#{value} is not convertable to a boolean"
+        end
+      end
+
+      NULLS = { '' => nil, nil => nil }
+      def self.convert_null(value)
+        NULLS.fetch(value) do
+          raise ArgumentError, "#{value} is not convertable to null"
+        end
+      end
+
+      def self.convert_date(value)
+        unless value =~ /\A\d{4}\-\d{2}\-\d{2}\z/
+          raise ArgumentError, "Not in iso8601 format"
+        end
+
+        Date.new(*value.split('-').map(&:to_i))
+      end
+
+      def self.convert_uri(value)
+        URI(value).tap do |uri|
+          unless uri.scheme && uri.host
+            raise ArgumentError, "Not a valid full URI"
+          end
+        end
+      rescue URI::InvalidURIError => e
+        raise ArgumentError, e.message, e.backtrace
+      end
+
+      CONVERTERS = {
+        'integer' => method(:Integer),
+        'number'  => method(:Float),
+        'boolean' => method(:convert_boolean),
+        'null'    => method(:convert_null)
+      }
+
+      IDENTITY_CONVERTER = lambda { |v| v }
+
+      def converter_for(type, definition)
+        CONVERTERS.fetch(type) do
+          if Hash === type && type['type']
+            converter_for(type['type'], type)
+          elsif type == 'string'
+            string_converter_for(definition)
+          else
+            raise CannotBeParsedError, "#{type} cannot be parsed"
+          end
+        end
+      end
+
+      STRING_CONVERTERS = {
+        'date'      => method(:convert_date),
+        'date-time' => Time.method(:iso8601),
+        'uri'       => method(:convert_uri)
+      }
+
+      def string_converter_for(definition)
+        STRING_CONVERTERS.fetch(definition['format'], IDENTITY_CONVERTER)
+      end
+    end
+
+    # Raised when an unsupported parameter type is defined.
+    class UnsupportedTypeError < ArgumentError
+      attr_reader :type
+
+      def initialize(type)
+        @type = type
+        super("#{type} params are not supported")
+      end
+    end
+
+    # Raised when the path_params are not part of the endpoint route.
+    class InvalidPathParamsError < ArgumentError
+      attr_reader :invalid_params
+
+      def initialize(*invalid_params)
+        @invalid_params = invalid_params
+        super("The path params #{invalid_params.join(', ')} are not in the route")
+      end
+    end
+
+    # Raised when a parameter value cannot be parsed.
+    CannotBeParsedError = Class.new(ArgumentError)
+
+    # Raised when a params definition is invalid.
+    InvalidParamsDefinitionError = Class.new(ArgumentError)
+  end
+end
+

data/lib/interpol/sinatra/request_params_parser.rb

@@ -0,0 +1,102 @@
+require 'interpol/request_params_parser'
+
+module Interpol
+  module Sinatra
+    # Parses and validates a sinatra params hash based on the
+    # endpoint definitions.
+    # Note that you use this like a sinatra middleware
+    # (using a `use` directive in the body of the sinatra class), but
+    # it hooks into sinatra differently so that it has access to the params.
+    # It's more like a mix-in, honestly, but we piggyback on `use` so that
+    # it can take a config block.
+    class RequestParamsParser
+      def initialize(app, &block)
+        @app = app
+        hook_into(app, &block)
+      end
+
+      def call(env)
+        @app.call(env)
+      end
+
+    private
+
+      def hook_into(app, &block)
+        return if defined?(app.settings.interpol_config)
+        config = Configuration.default.customized_duplicate(&block)
+
+        app.class.class_eval do
+          alias unparsed_params params
+          helpers SinatraHelpers
+          set :interpol_config, config
+          enable :parse_params unless settings.respond_to?(:parse_params)
+          include SinatraOverriddes
+        end
+      end
+
+      module SinatraHelpers
+        # Make the config available at the instance level for convenience.
+        def interpol_config
+          self.class.interpol_config
+        end
+
+        def endpoint_definition
+          @endpoint_definition ||= begin
+            version = available_versions = nil
+
+            definition = interpol_config.endpoints.find_definition \
+              env.fetch('REQUEST_METHOD'), request.path, 'request', nil do |endpoint|
+                available_versions ||= endpoint.available_versions
+                interpol_config.api_version_for(env, endpoint).tap do |_version|
+                  version ||= _version
+                end
+              end
+
+            if definition == DefinitionFinder::NoDefinitionFound
+              interpol_config.request_version_unavailable(self, version, available_versions)
+            end
+
+            definition
+          end
+        end
+
+        def params
+          @_parsed_params || super
+        end
+
+        def validate_params
+          @_parsed_params = endpoint_definition.parse_request_params(params_to_parse)
+        rescue Interpol::ValidationError => error
+          request_params_invalid(error)
+        end
+
+        def request_params_invalid(error)
+          interpol_config.sinatra_request_params_invalid(self, error)
+        end
+
+        # Sinatra includes a couple of "meta" params that are always
+        # present in the params hash even though they are not declared
+        # as params: splat and captures.
+        def params_to_parse
+          unparsed_params.dup.tap do |p|
+            p.delete('splat')
+            p.delete('captures')
+          end
+        end
+      end
+
+      module SinatraOverriddes
+        # We cannot access the full params (w/ path params) in a before hook,
+        # due to the order that sinatra runs the hooks in relation to route
+        # matching.
+        def process_route(*method_args)
+          super do |*block_args|
+            validate_params if settings.parse_params?
+            yield *block_args
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/interpol/stub_app.rb

@@ -33,7 +33,7 @@ module Interpol
       attr_reader :app
 
       def initialize(config)
-        @app = Sinatra.new do
+        @app = ::Sinatra.new do
           set            :interpol_config, config
           helpers        Helpers
           not_found      { JSON.dump(:error => "The requested resource could not be found") }

data/lib/interpol/test_helper.rb

@@ -1,5 +1,6 @@
 require 'interpol'
 require 'rack/mock'
+require 'interpol/request_params_parser'
 
 module Interpol
   module TestHelper
@@ -7,28 +8,48 @@ module Interpol
       def define_interpol_example_tests(&block)
         config = Configuration.default.customized_duplicate(&block)
 
-        each_example_from(config.endpoints) do |endpoint, definition, example, example_index|
-          description = "#{endpoint.name} (v #{definition.version}) has " +
-                        "valid data for example #{example_index + 1}"
-          example = filtered_example(config, endpoint, example)
-          define_test(description) { example.validate! }
+        each_definition_from(config.endpoints) do |endpoint, definition|
+          define_definition_test(endpoint, definition)
+
+          each_example_from(definition) do |example, example_index|
+            define_example_test(config, endpoint, definition, example, example_index)
+          end
         end
       end
 
     private
 
-      def each_example_from(endpoints)
+      def each_definition_from(endpoints)
         endpoints.each do |endpoint|
-          endpoint.definitions.each do |definitions|
-            definitions.each do |definition|
-              definition.examples.each_with_index do |example, index|
-                yield endpoint, definition, example, index
-              end
-            end
+          endpoint.definitions.each do |definition|
+            yield endpoint, definition
           end
         end
       end
 
+      def each_example_from(definition)
+        definition.examples.each_with_index do |example, index|
+          yield example, index
+        end
+      end
+
+      def define_example_test(config, endpoint, definition, example, example_index)
+        description = "#{endpoint.name} (v #{definition.version}) has " +
+                      "valid data for example #{example_index + 1}"
+        example = filtered_example(config, endpoint, example)
+        define_test(description) { example.validate! }
+      end
+
+      def define_definition_test(endpoint, definition)
+        return unless definition.request?
+
+        description = "#{endpoint.name} (v #{definition.version}) request " +
+                      "definition has valid params schema"
+        define_test description do
+          definition.request_params_parser # it will raise an error if it is invalid
+        end
+      end
+
       def filtered_example(config, endpoint, example)
         path = endpoint.route.gsub(':', '') # turn path params into static segments
         rack_env = ::Rack::MockRequest.env_for(path)

data/lib/interpol/version.rb

@@ -1,3 +1,3 @@
 module Interpol
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: interpol
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-20 00:00:00.000000000 Z
+date: 2012-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json-schema
@@ -169,12 +169,17 @@ files:
 - Rakefile
 - lib/interpol/configuration.rb
 - lib/interpol/configuration_ruby_18_extensions.rb
+- lib/interpol/define_singleton_method.rb
 - lib/interpol/documentation.rb
 - lib/interpol/documentation_app/config.rb
 - lib/interpol/documentation_app.rb
+- lib/interpol/dynamic_struct.rb
+- lib/interpol/each_with_object.rb
 - lib/interpol/endpoint.rb
 - lib/interpol/errors.rb
+- lib/interpol/request_params_parser.rb
 - lib/interpol/response_schema_validator.rb
+- lib/interpol/sinatra/request_params_parser.rb
 - lib/interpol/stub_app.rb
 - lib/interpol/test_helper.rb
 - lib/interpol/version.rb
@@ -218,7 +223,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -521228935891374364
+      hash: 2719553250962726743
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -227,7 +232,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -521228935891374364
+      hash: 2719553250962726743
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24