interpol 0.0.8 → 0.1.0

data/README.md

@@ -51,7 +51,9 @@ name: user_projects
 route: /users/:user_id/projects
 method: GET
 definitions:
-  - versions: ["1.0"]
+  - message_type: response
+    versions: ["1.0"]
+    status_codes: ["2xx", "404"]
     schema:
       description: Returns a list of projects for the given user.
       type: object
@@ -94,8 +96,17 @@ Let's look at this YAML file, point-by-point:
 * The `definitions` array contains a list of versioned schema definitions, with
   corresponding examples.  Everytime you modify your schema and change the version,
   you should add a new entry here.
+* The `message_type` describes whether the following schema is for requests or responses.
+  It is an optional attribute that when omitted defaults to response. The only valid values
+  are `request` and `response`.
 * The `versions` array lists the endpoint versions that should be associated with a
   particular schema definition.
+* The `status_codes` is an optional array of status code strings describing for which
+  status code or codes this schema applies to. `status_codes` is ignored if used with the
+  `request` `message_type`. When used with the `response` `message_type` it is an optional
+  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".
 * 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

data/Rakefile

@@ -12,7 +12,7 @@ if defined?(RUBY_ENGINE) && RUBY_ENGINE == 'ruby' # MRI only
 
   desc "Run cane to check quality metrics"
   Cane::RakeTask.new(:quality) do |cane|
-    cane.abc_max = 12
+    cane.abc_max = 16
     cane.add_threshold 'coverage/coverage_percent.txt', :==, 100
     cane.style_measure = 100
   end

data/lib/interpol/configuration.rb

@@ -8,14 +8,21 @@ module Interpol
     include HashFetcher
     NoDefinitionFound = Class.new
 
-    def find_definition(method, path)
+    def find_definition(method, path, message_type, status_code = nil)
       with_endpoint_matching(method, path) do |endpoint|
         version = yield endpoint
-        endpoint.definitions.find { |d| d.version == version }
+        find_definitions_for(endpoint, version, message_type).find do |definition|
+          definition.matches_status_code?(status_code)
+        end
       end
     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 || []
+    end
 
     def with_endpoint_matching(method, path)
       method = method.downcase.to_sym

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

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

data/lib/interpol/endpoint.rb

@@ -27,23 +27,36 @@ module Interpol
       validate_name!
     end
 
-    def find_definition!(version)
-      @definitions.fetch(version) do
+    def find_definition!(version, message_type)
+      @definitions.fetch([message_type, version]) do
         message = "No definition found for #{name} endpoint for version #{version}"
+        message << " and message_type #{message_type}"
         raise ArgumentError.new(message)
       end
     end
 
-    def find_example_for!(version)
-      find_definition!(version).examples.first
+    def find_example_for!(version, message_type)
+      find_definition!(version, message_type).first.examples.first
+    end
+
+    def find_example_status_code_for!(version)
+      find_definition!(version, 'response').first.example_status_code
     end
 
     def available_versions
-      definitions.map(&:version)
+      definitions.map { |d| d.first.version }
     end
 
     def definitions
-      @definitions.values.sort_by(&:version)
+      # 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
+        else
+          x.first.message_type <=> y.first.message_type
+        end
+      end
     end
 
     def route_matches?(path)
@@ -66,12 +79,16 @@ module Interpol
       end
     end
 
+    DEFAULT_MESSAGE_TYPE = 'response'
+
     def extract_definitions_from(endpoint_hash)
-      definitions = {}
+      definitions = Hash.new { |h, k| h[k] = [] }
 
       fetch_from(endpoint_hash, 'definitions').each do |definition|
         fetch_from(definition, 'versions').each do |version|
-          definitions[version] = EndpointDefinition.new(name, version, definition)
+          message_type = definition.fetch('message_type', DEFAULT_MESSAGE_TYPE)
+          key = [message_type, version]
+          definitions[key] << EndpointDefinition.new(name, version, message_type, definition)
         end
       end
 
@@ -90,13 +107,15 @@ module Interpol
   # Provides the means to validate data against that version of the schema.
   class EndpointDefinition
     include HashFetcher
-    attr_reader :endpoint_name, :version, :schema, :examples
-
-    def initialize(endpoint_name, version, definition)
-      @endpoint_name = endpoint_name
-      @version       = version
-      @schema        = fetch_from(definition, 'schema')
-      @examples      = fetch_from(definition, 'examples').map { |e| EndpointExample.new(e, self) }
+    attr_reader :endpoint_name, :message_type, :version, :schema, :examples
+
+    def initialize(endpoint_name, version, message_type, definition)
+      @endpoint_name  = endpoint_name
+      @message_type   = message_type
+      @status_codes   = StatusCodeMatcher.new(definition['status_codes'])
+      @version        = version
+      @schema         = fetch_from(definition, 'schema')
+      @examples       = fetch_from(definition, 'examples').map { |e| EndpointExample.new(e, self) }
       make_schema_strict!(@schema)
     end
 
@@ -108,7 +127,19 @@ module Interpol
     end
 
     def description
-      "#{endpoint_name} (v. #{version})"
+      "#{endpoint_name} (v. #{version}, mt. #{message_type}, sc. #{status_codes})"
+    end
+
+    def status_codes
+      @status_codes.code_strings.join(',')
+    end
+
+    def matches_status_code?(status_code)
+      status_code.nil? || @status_codes.matches?(status_code)
+    end
+
+    def example_status_code
+      @example_status_code ||= @status_codes.example_status_code
     end
 
   private
@@ -127,6 +158,49 @@ module Interpol
     end
   end
 
+  # Holds the acceptable status codes for an enpoint entry
+  # Acceptable status code are either exact status codes (200, 404, etc)
+  # or partial status codes (2xx, 3xx, 4xx, etc). Currently, partial status
+  # codes can only be a digit followed by two lower-case x's.
+  class StatusCodeMatcher
+    attr_reader :code_strings
+
+    def initialize(codes)
+      codes = ["xxx"] if Array(codes).empty?
+      @code_strings = codes
+      validate!
+    end
+
+    def matches?(status_code)
+      code_regexes.any? { |re| re =~ status_code.to_s }
+    end
+
+    def example_status_code
+      example_status_code = "200"
+      code_strings.first.chars.each_with_index do |char, index|
+        example_status_code[index] = char if char != 'x'
+      end
+      example_status_code
+    end
+
+    private
+      def code_regexes
+        @code_regexes ||= code_strings.map do |string|
+          /\A#{string.gsub('x', '\d')}\z/
+        end
+      end
+
+      def validate!
+        code_strings.each do |code|
+          # ensure code is 3 characters and all chars are a number or 'x'
+          # http://rubular.com/r/4sl68Bb4XO
+          unless code =~ /\A[\dx]{3}\Z/
+            raise StatusCodeMatcherArgumentError, "#{code} is not a valid format"
+          end
+        end
+      end
+  end
+
   # Wraps an example for a particular endpoint entry.
   class EndpointExample
     attr_reader :data, :definition
@@ -140,5 +214,3 @@ module Interpol
     end
   end
 end
-
-

data/lib/interpol/errors.rb

@@ -31,5 +31,8 @@ module Interpol
   # Error raised when the schema validator cannot find a matching
   # endpoint definition for the request.
   class NoEndpointDefinitionFoundError < Error; end
+
+  # Raised when an invalid status code is found during validate_codes!
+  class StatusCodeMatcherArgumentError < ArgumentError; end
 end
 

data/lib/interpol/response_schema_validator.rb

@@ -67,7 +67,8 @@ module Interpol
       end
 
       def validator
-        @validator ||= @config.endpoints.find_definition(request_method, path) do |endpoint|
+        @validator ||= @config.endpoints.
+            find_definition(request_method, path, 'response', status) do |endpoint|
           @config.api_version_for(env, endpoint)
         end
       end

data/lib/interpol/stub_app.rb

@@ -18,8 +18,8 @@ module Interpol
         self.class.interpol_config
       end
 
-      def example_for(endpoint, version)
-        endpoint.find_example_for!(version)
+      def example_for(endpoint, version, message_type)
+        endpoint.find_example_for!(version, message_type)
       rescue ArgumentError
         interpol_config.request_version_unavailable(self, version, endpoint.available_versions)
       end
@@ -49,8 +49,10 @@ module Interpol
       def endpoint_definition(endpoint)
         lambda do
           version = interpol_config.api_version_for(request.env, endpoint)
-          example = example_for(endpoint, version)
+          message_type = 'response'
+          example = example_for(endpoint, version, message_type)
           example.validate!
+          status endpoint.find_example_status_code_for!(version)
           JSON.dump(example.data)
         end
       end

data/lib/interpol/test_helper.rb

@@ -5,9 +5,11 @@ module Interpol
     module Common
       def each_example_from(endpoints)
         endpoints.each do |endpoint|
-          endpoint.definitions.each do |definition|
-            definition.examples.each_with_index do |example, index|
-              yield endpoint, definition, example, index
+          endpoint.definitions.each do |definitions|
+            definitions.each do |definition|
+              definition.examples.each_with_index do |example, index|
+                yield endpoint, definition, example, index
+              end
             end
           end
         end

data/lib/interpol/version.rb

@@ -1,3 +1,3 @@
 module Interpol
-  VERSION = "0.0.8"
+  VERSION = "0.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: interpol
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-29 00:00:00.000000000 Z
+date: 2012-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json-schema
@@ -218,7 +218,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3251393236495982186
+      hash: -430941373413258822
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -227,7 +227,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3251393236495982186
+      hash: -430941373413258822
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24