apiculture 0.0.13 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 110ceee2209d9f8ed34b76754b273a2d0834ac40
-  data.tar.gz: 6b4c9cad319d4c3cb1fb9cc2055634e09635fc7d
+  metadata.gz: 52cb357c6a73e99a64db5e12a108b7a73cd5afd8
+  data.tar.gz: 7c03623922d85c6947ca1ca4026d3b29e584fe4f
 SHA512:
-  metadata.gz: c3a192e792b99422ff9fdb13dec002e083d044b5fd391187967ecd6a8982c2d0067fa03dfd1749406b8ebd573c7de715a1621969ba562c402de0c439ef1ce662
-  data.tar.gz: 32b19da637ed027e4f01dd4e03c3334da9cdcd1509aea9d4a360b2520cf3b860284cce7e2293a6a65ce67712d2e6471e87228b900a5ff1c7351d2b5fe74b23bc
+  metadata.gz: 9c97d38dab84b5c6d4cda3d2fb04c30f1c4c3ea8f7ff6cdd6432f5656ddc6523a7a95aaa4919324f28839669e8aa3c7bea0e65c0c73ab274573625805c1bd3e5
+  data.tar.gz: 8d289be328fbc019a55dab97317c219d0ddb48e181078bc446d5da4d13b8b6de2accf688d03a6965bd8733928efb71f633916ad60a4f6d9900f38c375e0ed26d

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+- 2.1.5
+- 2.2.2
+sudo: false
+cache: bundler

data/Gemfile

@@ -10,6 +10,6 @@ group :development do
   gem "rspec", "~> 3.1", '< 3.2'
   gem "rdoc", "~> 3.12"
   gem "bundler", "~> 1.0"
-  gem "jeweler", "~> 2.0.1"
+  gem "jeweler", "~> 2"
   gem "simplecov", ">= 0"
 end

data/README.md

@@ -2,6 +2,8 @@
 
 A little toolkit for building RESTful API backends on top of Sinatra.
 
+[![Build Status](https://travis-ci.org/WeTransfer/apiculture.svg?branch=master)](https://travis-ci.org/WeTransfer/apiculture)
+
 ## Ideas
 
 A simple API definition DSL with simple premises:
@@ -15,54 +17,60 @@ A simple API definition DSL with simple premises:
  
 ## A taste of honey
 
-    class Api::V2 < Sinatra::Base
-      
-      use Rack::Parser, :content_types => {
-        'application/json'  => JSON.method(:load).to_proc
-      }
-      
-      extend Apiculture
-      
-      desc 'Create a Contact'
-      required_param :name, 'Name of the person', String
-      param :email, 'Email address of the person', String
-      param :phone, 'Phone number', String, cast: ->(v) { v.scan(/\d/).flatten.join }
-      param :notes, 'Notes about this person', String
-      api_method :post, '/contacts' do
-        # anything allowed within Sinatra actions is allowed here, and
-        # works exactly the same - but we suggest using Actions instead.
-        action_result CreateContact # uses Api::V2::CreateContact
-      end
-      
-      desc 'Fetch a Contact'
-      route_param :id, 'ID of the person'
-      responds_with 200, 'Contact data', {name: 'John Appleseed', id: "ac19...fefg"}
-      api_method :get, '/contacts/:id' do | person_id |
-        json Person.find(person_id).to_json
-      end
-    end
+```ruby
+class Api::V2 < Sinatra::Base
+  
+  use Rack::Parser, :content_types => {
+    'application/json'  => JSON.method(:load).to_proc
+  }
+  
+  extend Apiculture
+  
+  desc 'Create a Contact'
+  required_param :name, 'Name of the person', String
+  param :email, 'Email address of the person', String
+  param :phone, 'Phone number', String, cast: ->(v) { v.scan(/\d/).flatten.join }
+  param :notes, 'Notes about this person', String
+  api_method :post, '/contacts' do
+    # anything allowed within Sinatra actions is allowed here, and
+    # works exactly the same - but we suggest using Actions instead.
+    action_result CreateContact # uses Api::V2::CreateContact
+  end
+  
+  desc 'Fetch a Contact'
+  route_param :id, 'ID of the person'
+  responds_with 200, 'Contact data', {name: 'John Appleseed', id: "ac19...fefg"}
+  api_method :get, '/contacts/:id' do | person_id |
+    json Person.find(person_id).to_json
+  end
+end
+```
 
 ## Generating documentation
 
 For the aforementioned example:
 
-    File.open('API.html', 'w') do |f|
-      f << Api::V2.api_documentation.to_html
-    end
+```ruby
+File.open('API.html', 'w') do |f|
+  f << Api::V2.api_documentation.to_html
+end
+```
 
 or to get it in Markdown:
 
-    File.open('API.md', 'w') do |f|
-      f << Api::V2.api_documentation.to_markdown
-    end
+```ruby
+File.open('API.md', 'w') do |f|
+  f << Api::V2.api_documentation.to_markdown
+end
+```
 
 ## Running the tests
 
-    $bundle exec rspec
+    $ bundle exec rspec
 
 If you want to also examine the HTML documentation that gets built during the test, set `SHOW_TEST_DOC` in env:
 
-    $SHOW_TEST_DOC=yes bundle exec rspec
+    $ SHOW_TEST_DOC=yes bundle exec rspec
 
 Note that this requires presence of the `open` commandline utility (should be available on both OSX and Linux).
 

data/apiculture.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: apiculture 0.0.13 ruby lib
+# stub: apiculture 0.0.14 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "apiculture"
-  s.version = "0.0.13"
+  s.version = "0.0.14"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Julik Tarkhanov", "WeTransfer"]
-  s.date = "2015-11-16"
+  s.date = "2016-06-01"
   s.description = "A toolkit for building REST APIs on top of Sinatra"
   s.email = "me@julik.nl"
   s.extra_rdoc_files = [
@@ -19,6 +19,7 @@ Gem::Specification.new do |s|
     "README.md"
   ]
   s.files = [
+    ".travis.yml",
     "Gemfile",
     "LICENSE.txt",
     "README.md",
@@ -58,7 +59,7 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<rspec>, ["< 3.2", "~> 3.1"])
       s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
       s.add_development_dependency(%q<bundler>, ["~> 1.0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 2.0.1"])
+      s.add_development_dependency(%q<jeweler>, ["~> 2"])
       s.add_development_dependency(%q<simplecov>, [">= 0"])
     else
       s.add_dependency(%q<sinatra>, ["~> 1.4"])
@@ -70,7 +71,7 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<rspec>, ["< 3.2", "~> 3.1"])
       s.add_dependency(%q<rdoc>, ["~> 3.12"])
       s.add_dependency(%q<bundler>, ["~> 1.0"])
-      s.add_dependency(%q<jeweler>, ["~> 2.0.1"])
+      s.add_dependency(%q<jeweler>, ["~> 2"])
       s.add_dependency(%q<simplecov>, [">= 0"])
     end
   else
@@ -83,7 +84,7 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<rspec>, ["< 3.2", "~> 3.1"])
     s.add_dependency(%q<rdoc>, ["~> 3.12"])
     s.add_dependency(%q<bundler>, ["~> 1.0"])
-    s.add_dependency(%q<jeweler>, ["~> 2.0.1"])
+    s.add_dependency(%q<jeweler>, ["~> 2"])
     s.add_dependency(%q<simplecov>, [">= 0"])
   end
 end

data/lib/apiculture/method_documentation.rb

@@ -11,7 +11,7 @@ class Apiculture::MethodDocumentation
     @definition = action_definition
     @mountpoint = mountpoint
   end
-  
+
   # Compose a Markdown definition of the action
   def to_markdown
     m = MDBuf.new
@@ -20,42 +20,42 @@ class Apiculture::MethodDocumentation
     m << route_parameters_table
     m << request_parameters_table
     m << possible_responses_table
-    
+
     m.to_s
   end
-  
+
   # Compose an HTML string by converting the result of +to_markdown+
   def to_html_fragment
     require 'rdiscount'
     RDiscount.new(to_markdown).to_html
   end
-  
+
   private
-  
+
   class StringBuf #:nodoc:
     def initialize; @blocks = []; end
     def <<(block); @blocks << block.to_s; self; end
     def to_s; @blocks.join; end
   end
-  
+
   class MDBuf < StringBuf  #:nodoc:
     def to_s; @blocks.join("\n\n"); end
   end
-  
-  def route_parameters_table
+
+  def _route_parameters_table
     return '' unless @definition.defines_route_params?
-    
+
     m = MDBuf.new
     b = StringBuf.new
     m << '### URL parameters'
-    
+
     html = Builder::XmlMarkup.new(:target => b)
     html.table(class: 'apiculture-table') do
       html.tr do
         html.th 'Name'
         html.th 'Description'
       end
-      
+
       @definition.route_parameters.each do | param |
         html.tr do
           html.td { html.tt(':%s' % param.name) }
@@ -65,7 +65,7 @@ class Apiculture::MethodDocumentation
     end
     m << b.to_s
   end
-  
+
   def body_example(for_response_definition)
     if for_response_definition.no_body?
       '(empty)'
@@ -73,14 +73,14 @@ class Apiculture::MethodDocumentation
       JSON.pretty_generate(for_response_definition.jsonable_object_example)
     end
   end
-  
+
   def possible_responses_table
     return '' unless @definition.defines_responses?
-    
+
     m = MDBuf.new
     b = StringBuf.new
     m << '### Possible responses'
-    
+
     html = Builder::XmlMarkup.new(:target => b)
     html.table(class: 'apiculture-table') do
       html.tr do
@@ -88,7 +88,7 @@ class Apiculture::MethodDocumentation
         html.th('What happened')
         html.th('Example response body')
       end
-      
+
       @definition.responses.each do | resp |
         html.tr do
           html.td { html.b(resp.http_status_code) }
@@ -97,15 +97,27 @@ class Apiculture::MethodDocumentation
         end
       end
     end
-    
+
     m << b.to_s
   end
-  
+
   def request_parameters_table
     return '' unless @definition.defines_request_params?
-    
     m = MDBuf.new
     m << '### Request parameters'
+    m << parameters_table(@definition.parameters).to_s
+  end
+
+  def route_parameters_table
+    return '' unless @definition.defines_route_params?
+    m = MDBuf.new
+    m << '### URL parameters'
+    m << parameters_table(@definition.route_parameters).to_s
+  end
+
+
+  private
+  def parameters_table(parameters)
     b = StringBuf.new
     html = Builder::XmlMarkup.new(:target => b)
     html.table(class: 'apiculture-table') do
@@ -115,8 +127,8 @@ class Apiculture::MethodDocumentation
         html.th 'Type after cast'
         html.th 'Description'
       end
-      
-      @definition.parameters.each do | param |
+
+      parameters.each do | param |
         html.tr do
           html.td { html.tt(param.name.to_s) }
           html.td(param.required ? 'Yes' : 'No')
@@ -125,6 +137,6 @@ class Apiculture::MethodDocumentation
         end
       end
     end
-    m << b
+    b
   end
 end

data/lib/apiculture/version.rb

@@ -1,3 +1,3 @@
 module Apiculture
-  VERSION = '0.0.13'
+  VERSION = '0.0.14'
 end

data/lib/apiculture.rb

@@ -35,8 +35,7 @@ module Apiculture
     def name_as_string; name.to_s; end
   end
   
-  class RouteParameter < Struct.new(:name, :description)
-    def name_as_string; name.to_s; end
+  class RouteParameter < Parameter
   end
   
   class PossibleResponse < Struct.new(:http_status_code, :description, :jsonable_object_example)
@@ -119,9 +118,9 @@ module Apiculture
   # Route parameters are always required, and all the parameters specified
   # using +route_param+ should also be included in the path given for the route
   # definition
-  def route_param(name, description)
+  def route_param(name, description, ruby_type = String, cast: IDENTITY_PROC)
     @apiculture_action_definition ||= ActionDefinition.new
-    @apiculture_action_definition.route_parameters << RouteParameter.new(name, description)
+    @apiculture_action_definition.route_parameters << RouteParameter.new(name, description, required=false, ruby_type, cast)
   end
   
   # Add a possible response, specifying the code and the JSON Response by example.
@@ -245,12 +244,22 @@ module Apiculture
     # Pick out all the defined parameters and set up a block that can validate them
     # when the action is called. With that, set up the actual Sinatra method that will
     # respond to the request.
-    parametric_checker_proc = parametric_validator_proc_from(action_def.parameters)
+    parametric_checker_proc = parametric_validator_proc_from(action_def.parameters + action_def.route_parameters)
     public_send(http_verb, path, options) do |*matched_sinatra_route_params|
-      # Verify the parameters first
+      route_params = []
+      action_def.route_parameters.each_with_index do |route_param, index|
+        # Apply the type cast and save it (since using our override we can mutate the params)
+        value_after_type_cast = AC_APPLY_TYPECAST_PROC.call(route_param.cast_proc_or_method, params[route_param.name])
+        route_params[index] = value_after_type_cast
+        
+        # Ensure the typecast value adheres to the enforced Ruby type
+        AC_CHECK_TYPE_PROC.call(route_param, route_params[index])
+        # ..permit it in the strong parameters if we support them
+        AC_PERMIT_PROC.call(route_params, route_param.name)
+      end
       instance_exec(&parametric_checker_proc)
       # Execute the original action via instance_exec, passing along the route args
-      instance_exec(*matched_sinatra_route_params, &blk)
+      instance_exec(*route_params, &blk)
     end
     
     # Reset for the subsequent action definition

data/spec/apiculture/app_documentation_spec.rb

@@ -27,6 +27,11 @@ describe "Apiculture.api_documentation" do
       route_param :id, 'Pancake ID to delete'
       api_method :delete, '/pancake/:id' do
       end
+
+      desc 'Pancake ingredients are in the URL'
+      route_param :topping_id, 'Pancake topping ID', Fixnum, cast: :to_i
+      api_method :get, '/pancake/with/:topping_id' do |topping_id|
+      end
     end
   }
   

data/spec/apiculture/method_documentation_spec.rb

@@ -63,6 +63,24 @@ describe Apiculture::MethodDocumentation do
     expect(generated_html).not_to include('<h3>Request parameters</h3>')
   end
   
+  it 'generates HTML from an ActionDefinition with a casted route param' do
+    definition = Apiculture::ActionDefinition.new
+    
+    definition.description = "This adds a topping to a pancake"
+    
+    definition.route_parameters << Apiculture::RouteParameter.new(:topping_id, 'ID of the pancake topping', Fixnum, cast: :to_i)
+    definition.http_verb = 'get'
+    definition.path = '/pancake/:topping_id'
+    
+    documenter = described_class.new(definition)
+    
+    generated_html = documenter.to_html_fragment
+    generated_markdown = documenter.to_markdown
+    expect(generated_html).to include('<h3>URL parameters</h3>')
+    expect(generated_html).to include('Type after cast')
+  end
+
+
   it 'generates Markdown from an ActionDefinition with a mountpoint' do
     definition = Apiculture::ActionDefinition.new
     

data/spec/apiculture_spec.rb

@@ -191,7 +191,94 @@ describe "Apiculture" do
       post '/thing', {number: '123'}
       expect(last_response.body).to eq('Total success')
     end
+
+    it 'ensures current behaviour for route params is not changed' do
+      @app_class = Class.new(Sinatra::Base) do
+        settings.show_exceptions = false
+        settings.raise_errors = true
+        extend Apiculture
+      
+        route_param :number, "Number of the thing"
+        api_method :post, '/thing/:number' do
+          raise "Casted to int" if params[:number] == 123
+          'Total success'
+        end
+      end
+      post '/thing/123'
+      expect(last_response.body).to eq('Total success')
+    end
+
+    it 'ensures current behaviour when no route params are present does not change' do
+      @app_class = Class.new(Sinatra::Base) do
+        settings.show_exceptions = false
+        settings.raise_errors = true
+        extend Apiculture
+      
+        param :number, "Number of the thing", Integer, cast: :to_i
+        api_method :post, '/thing' do
+          raise "Behaviour changed" unless params[:number] == 123
+          'Total success'
+        end
+      end
+      post '/thing', {number: '123'}
+      expect(last_response.body).to eq('Total success')
+    end
+
+    it 'applies a symbol typecast by calling a method on the route parameter value' do
+      @app_class = Class.new(Sinatra::Base) do
+        settings.show_exceptions = false
+        settings.raise_errors = true
+        extend Apiculture
+      
+        route_param :number, "Number of the thing", Integer, :cast => :to_i
+        api_method :post, '/thing/:number' do
+          raise "Not cast" unless params[:number] == 123
+          'Total success'
+        end
+      end
+      post '/thing/123'
+      expect(last_response.body).to eq('Total success')
+    end
+
+
+    it 'cast block arguments to the right type', run: true do
+      @app_class = Class.new(Sinatra::Base) do
+        settings.show_exceptions = false
+        settings.raise_errors = true
+        extend Apiculture
+      
+        route_param :number, "Number of the thing", Fixnum, :cast => :to_i
+        api_method :post, '/thing/:number' do |number|
+          raise "Not cast" unless number.class == Fixnum
+          'Total success'
+        end
+      end
+      post '/thing/123'
+      expect(last_response.body).to eq('Total success')
+    end
+
     
+    it 'merges route_params and regular params' do
+      @app_class = Class.new(Sinatra::Base) do
+        settings.show_exceptions = false
+        settings.raise_errors = true
+        extend Apiculture
+      
+        param :number, "Number of the thing", Integer, :cast => :to_i
+        route_param :id, "Id of the thingy", Fixnum, :cast => :to_i
+        route_param :awesome, "Hash of the thingy"
+
+        api_method :post, '/thing/:id/:awesome' do |id|
+          raise 'Not merged' unless params.has_key?("id")
+          raise 'Not merged' unless params.has_key?("awesome")
+          'Thanks'
+        end
+      end
+      post '/thing/1/true', {number: '123'}
+      expect(last_response.body).to eq('Thanks')
+    end
+
+
     it 'applies a Proc typecast by calling the proc (for example - for ISO8601 time)' do
       @app_class = Class.new(Sinatra::Base) do
         settings.show_exceptions = false

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: apiculture
 version: !ruby/object:Gem::Version
-  version: 0.0.13
+  version: 0.0.14
 platform: ruby
 authors:
 - Julik Tarkhanov
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-11-16 00:00:00.000000000 Z
+date: 2016-06-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra
@@ -149,14 +149,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.1
+        version: '2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.1
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -179,6 +179,7 @@ extra_rdoc_files:
 - LICENSE.txt
 - README.md
 files:
+- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md