apiculture 0.0.12

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cea2109a603040e6f683ded9261b52bc2d03e53a
+  data.tar.gz: 8b99f10724eb4cbd0484ca8ecd85feedf24e3e1f
+SHA512:
+  metadata.gz: 90e06f221ad4da20e8ba09a51bde34d62761aad0374a9dd306db8fb3550d52a75fc8c24362277be2a542550de1dbff70443c99a14f998fc4444e292aa785cc5d
+  data.tar.gz: fe654fa36f250506311098ff322d3202f6b67d7d1c390fb8241eaddd7608b104e4e40725814e74ff063b1d87914c2a08ffa74e99ed27e5e029d935deb67bb2ec

data/Gemfile

@@ -0,0 +1,15 @@
+source "http://rubygems.org"
+gem 'sinatra', '~> 1.4', :require => 'sinatra/base'
+gem 'builder'
+gem 'rdiscount'
+gem 'github-markup'
+gem "mustache"
+
+group :development do
+  gem 'rack-test'
+  gem "rspec", "~> 3.1", '< 3.2'
+  gem "rdoc", "~> 3.12"
+  gem "bundler", "~> 1.0"
+  gem "jeweler", "~> 2.0.1"
+  gem "simplecov", ">= 0"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2015 WeTransfer
+
+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.

data/README.md

@@ -0,0 +1,83 @@
+# apiculture
+
+A little toolkit for building RESTful API backends on top of Sinatra.
+
+## Ideas
+
+A simple API definition DSL with simple premises:
+  
+ * Endpoint URLs should be _visible_ in the actual code. The reason for that is with nested
+   blocks you inevitably end up setting up context somewhere far away from the terminal route
+   that ends up using that context.
+ * Explicit allowed/required parameters (both payload/query string and body)
+ * Explicit description in front of the API action definition
+ * Wrap the actual work into Actions, so that the API definition is mostly routes
+ 
+## 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
+
+## Generating documentation
+
+For the aforementioned example:
+
+    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
+
+## Running the tests
+
+    $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
+
+Note that this requires presence of the `open` commandline utility (should be available on both OSX and Linux).
+
+## Contributing to apiculture
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2015 WeTransfer. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,45 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require_relative 'lib/apiculture/version'
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  gem.name = "apiculture"
+  gem.version = Apiculture::VERSION
+  gem.homepage = "https://github.com/WeTransfer/apiculture"
+  gem.license = "MIT"
+  gem.description = %Q{A toolkit for building REST APIs on top of Sinatra}
+  gem.summary = %Q{Sweet API sauce on top of Sintra}
+  gem.email = "me@julik.nl"
+  gem.authors = ["Julik Tarkhanov", "WeTransfer"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "apiculture #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/apiculture.gemspec

@@ -0,0 +1,90 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+# stub: apiculture 0.0.12 ruby lib
+
+Gem::Specification.new do |s|
+  s.name = "apiculture"
+  s.version = "0.0.12"
+
+  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.description = "A toolkit for building REST APIs on top of Sinatra"
+  s.email = "me@julik.nl"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    "Gemfile",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "apiculture.gemspec",
+    "lib/apiculture.rb",
+    "lib/apiculture/action.rb",
+    "lib/apiculture/action_definition.rb",
+    "lib/apiculture/app_documentation.rb",
+    "lib/apiculture/app_documentation_tpl.mustache",
+    "lib/apiculture/markdown_segment.rb",
+    "lib/apiculture/method_documentation.rb",
+    "lib/apiculture/sinatra_instance_methods.rb",
+    "lib/apiculture/timestamp_promise.rb",
+    "lib/apiculture/version.rb",
+    "spec/apiculture/action_spec.rb",
+    "spec/apiculture/app_documentation_spec.rb",
+    "spec/apiculture/method_documentation_spec.rb",
+    "spec/apiculture_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = "https://github.com/WeTransfer/apiculture"
+  s.licenses = ["MIT"]
+  s.rubygems_version = "2.2.2"
+  s.summary = "Sweet API sauce on top of Sintra"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 4
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<sinatra>, ["~> 1.4"])
+      s.add_runtime_dependency(%q<builder>, [">= 0"])
+      s.add_runtime_dependency(%q<rdiscount>, [">= 0"])
+      s.add_runtime_dependency(%q<github-markup>, [">= 0"])
+      s.add_runtime_dependency(%q<mustache>, [">= 0"])
+      s.add_development_dependency(%q<rack-test>, [">= 0"])
+      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<simplecov>, [">= 0"])
+    else
+      s.add_dependency(%q<sinatra>, ["~> 1.4"])
+      s.add_dependency(%q<builder>, [">= 0"])
+      s.add_dependency(%q<rdiscount>, [">= 0"])
+      s.add_dependency(%q<github-markup>, [">= 0"])
+      s.add_dependency(%q<mustache>, [">= 0"])
+      s.add_dependency(%q<rack-test>, [">= 0"])
+      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<simplecov>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<sinatra>, ["~> 1.4"])
+    s.add_dependency(%q<builder>, [">= 0"])
+    s.add_dependency(%q<rdiscount>, [">= 0"])
+    s.add_dependency(%q<github-markup>, [">= 0"])
+    s.add_dependency(%q<mustache>, [">= 0"])
+    s.add_dependency(%q<rack-test>, [">= 0"])
+    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<simplecov>, [">= 0"])
+  end
+end
+

data/lib/apiculture.rb

@@ -0,0 +1,266 @@
+# Allows brief definitions of APIs for documentation and parameter checks
+module Apiculture
+  require_relative 'apiculture/version'
+  require_relative 'apiculture/action'
+  require_relative 'apiculture/sinatra_instance_methods'
+  require_relative 'apiculture/action_definition'
+  require_relative 'apiculture/markdown_segment'
+  require_relative 'apiculture/timestamp_promise'
+  
+  def self.extended(in_class)
+    in_class.send(:include, SinatraInstanceMethods)
+    super
+  end
+  
+  IDENTITY_PROC = ->(arg) { arg }
+  
+  AC_APPLY_TYPECAST_PROC = ->(cast_proc_or_method, v) {
+    cast_proc_or_method.is_a?(Symbol) ? v.public_send(cast_proc_or_method) : cast_proc_or_method.call(v)
+  }
+  
+  AC_CHECK_PRESENCE_PROC = ->(name_as_string, params) {
+    params.has_key?(name_as_string) or raise MissingParameter.new(name_as_string)
+  }
+  
+  AC_CHECK_TYPE_PROC = ->(param, value) {
+    value.is_a?(param.ruby_type) or raise ParameterTypeMismatch.new(param, value.class)
+  }
+  
+  AC_PERMIT_PROC = ->(maybe_strong_params, param_name) {
+    maybe_strong_params.permit(param_name) if maybe_strong_params.respond_to?(:permit)
+  }
+  
+  class Parameter < Struct.new(:name, :description, :required, :ruby_type, :cast_proc_or_method)
+    # Return Strings since Sinatra prefers string keys for params{}
+    def name_as_string; name.to_s; end
+  end
+  
+  class RouteParameter < Struct.new(:name, :description)
+    def name_as_string; name.to_s; end
+  end
+  
+  class PossibleResponse < Struct.new(:http_status_code, :description, :jsonable_object_example)
+    def no_body?
+      jsonable_object_example.nil?
+    end
+  end
+  
+  # Indicates where this API will be mounted. This is only used
+  # for the generated documentation. In general, this should match
+  # the SCRIPT_NAME of the Sinatra application when it will be called.
+  # For example, if you use this in your +config.ru+:
+  #
+  #     map('/api/v3') { run MyApi }
+  #
+  # then it is handy to set that with +mounted_at+ as well so that the API
+  # documentation references the mountpoint:
+  #
+  #     mounted_at '/api/v3'
+  #
+  # Again: this does not change the way requests are handled in any way,
+  # it just alters the documentation output.
+  def mounted_at(path)
+    @apiculture_mounted_at = path.to_s.gsub(/\/$/, '')
+  end
+  
+  # Inserts the generation timestamp into the documentation at this point.
+  # The timestamp will be not very precise (to the minute) and in UTC time
+  def documentation_build_time!
+    apiculture_stack << Apiculture::TimestampPromise
+  end
+  
+  # Inserts a literal Markdown string into the documentation at this point.
+  # For instance, if used after an API method declaration, it will insert
+  # the header between the API methods in the doc.
+  #
+  #     api_method :get, '/foo/bar' do
+  #       #...
+  #     end
+  #     markdown_string "# Subsequent methods do thing to Bars"
+  #     api_method :get, '/bar/thing' do
+  #       #...
+  #     end
+  def markdown_string(str)
+    apiculture_stack << MarkdownSegment.new(str)
+  end
+  
+  # Inserts the contents of the file at +path+ into the documentation, using +markdown_string+.
+  # For instance, if used after an API method declaration, it will insert
+  # the header between the API methods in the doc.
+  #
+  #     markdown_file "SECURITY_CONSIDERATIONS.md"
+  #     api_method :get, '/bar/thing' do
+  #       #...
+  #     end
+  def markdown_file(path_to_markdown)
+    md = File.read(path_to_markdown).encode(Encoding::UTF_8)
+    markdown_string(md)
+  end
+  
+  # Describe the API method that is going to be defined
+  def desc(action_description)
+    @apiculture_action_definition ||= ActionDefinition.new
+    @apiculture_action_definition.description = action_description.to_s
+  end
+  
+  # Add an optional parameter for the API call
+  def param(name, description, ruby_type, cast: IDENTITY_PROC)
+    @apiculture_action_definition ||= ActionDefinition.new
+    @apiculture_action_definition.parameters << Parameter.new(name, description, required=false, ruby_type, cast)
+  end
+  
+  # Add a requred parameter for the API call
+  def required_param(name, description, ruby_type, cast: IDENTITY_PROC)
+    @apiculture_action_definition ||= ActionDefinition.new
+    @apiculture_action_definition.parameters << Parameter.new(name, description, required=true, ruby_type, cast)
+  end
+  
+  # Describe a parameter that has to be included in the URL of the API call.
+  # 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)
+    @apiculture_action_definition ||= ActionDefinition.new
+    @apiculture_action_definition.route_parameters << RouteParameter.new(name, description)
+  end
+  
+  # Add a possible response, specifying the code and the JSON Response by example.
+  # Multiple response packages can be specified.
+  def responds_with(http_status, description, example_jsonable_object = nil)
+    @apiculture_action_definition ||= ActionDefinition.new
+    @apiculture_action_definition.responses << PossibleResponse.new(http_status, description, example_jsonable_object)
+  end
+  
+  DefinitionError = Class.new(StandardError)
+  ValidationError = Class.new(StandardError)
+  
+  class RouteParameterNotInPath < DefinitionError; end
+  class ReservedParameter < DefinitionError; end
+  class ConflictingParameter < DefinitionError; end
+  
+  # Gets raised when a parameter is missing
+  class MissingParameter < ValidationError
+    def initialize(parameter_name)
+      super "Missing parameter :#{parameter_name}"
+    end
+  end
+  
+  # Gets raised when a parameter is supplied and has a wrong type
+  class ParameterTypeMismatch < ValidationError
+    def initialize(ac_parameter, received_ruby_type)
+      parameter_name, expected_type = ac_parameter.name, ac_parameter.ruby_type
+      received_type = received_ruby_type
+      super "Received #{received_type}, expected #{expected_type} for :#{parameter_name}"
+    end
+  end
+  
+  # Returns a Proc that calls the strong parameters to check the presence/types
+  def parametric_validator_proc_from(parametric_validators)
+    required_params = parametric_validators.select{|e| e.required }
+    # Return a lambda that will be called with the Sinatra params
+    parametric_validation_blk = ->{
+      # Within this block +params+ is the Sinatra's instance params
+      # Ensure the required parameters are present first, before applying casts/validations etc.
+      required_params.each { |param| AC_CHECK_PRESENCE_PROC.call(param.name_as_string, params) }
+      parametric_validators.each do |param|
+        param_name = param.name_as_string
+        next unless params.has_key?(param_name) # this is checked via required_params
+        
+        # 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(param.cast_proc_or_method, params[param_name])
+        params[param_name] = value_after_type_cast
+        
+        # Ensure the typecast value adheres to the enforced Ruby type
+        AC_CHECK_TYPE_PROC.call(param, params[param_name])
+        # ..permit it in the strong parameters if we support them
+        AC_PERMIT_PROC.call(params, param_name)
+      end
+      
+      # The following only applies if the app does not use strong_parameters - 
+      # this makes use of parameter mutability again to kill the parameters that are not permitted
+      # or mentioned in the API specification
+      unexpected_parameters = params.keys.map(&:to_s) - parametric_validators.map(&:name).map(&:to_s)
+      unexpected_parameters.each do | parameter_to_discard |
+        # TODO: raise or record a warning
+        if env['rack.logger'].respond_to?(:warn)
+          env['rack.logger'].warn "Discarding disallowed parameter #{parameter_to_discard.inspect}"
+        end
+        params.delete(parameter_to_discard)
+      end
+    }
+  end
+  
+  # Serve the documentation for the API at the given URL
+  def serve_api_documentation_at(url)
+    get(url) do
+      content_type :html
+      self.class.api_documentation.to_html
+    end
+  end
+  
+  # Returns an +AppDocumentation+ object for all actions defined so far.
+  #
+  #   MyApi.api_documentation.to_markdown #=> "..."
+  #   MyApi.api_documentation.to_html #=> "..."
+  def api_documentation
+    require_relative 'apiculture/app_documentation'
+    AppDocumentation.new(self, @apiculture_mounted_at.to_s, @apiculture_actions_and_docs || [])
+  end
+  
+  # Define an API method. Under the hood will call the related methods in Sinatra
+  # to define the route.
+  def api_method(http_verb, path, options={}, &blk)
+    action_def = (@apiculture_action_definition || ActionDefinition.new)
+    action_def.http_verb = http_verb
+    action_def.path = path
+    
+    # Ensure no reserved Sinatra parameters are used
+    all_parameter_names = action_def.all_parameter_names_as_strings
+    %w( splat captures ).each do | reserved_param |
+      if all_parameter_names.include?(reserved_param)
+        raise ReservedParameter.new(":#{reserved_param} is a reserved magic parameter name in Sinatra")
+      end
+    end
+    
+    # Ensure no conflations between route/req params
+    seen_params = {}
+    all_parameter_names.each do |e| 
+      if seen_params[e]
+        raise ConflictingParameter.new(":#{e} mentioned twice as a possible parameter. Note that URL" + 
+          " parameters and request parameters share a namespace.")
+      else
+        seen_params[e] = true
+      end
+    end
+    
+    # Ensure the path has the route parameters that were predeclared
+    action_def.route_parameters.map(&:name).each do | route_parameter_key |
+      unless path.include?(':%s' % route_parameter_key)
+        raise RouteParameterNotInPath.new("Parameter :#{route_parameter_key} not present in path #{path.inspect}")
+      end
+    end
+    
+    # TODO: ensure all route parameters are documented
+    
+    # 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)
+    public_send(http_verb, path, options) do |*matched_sinatra_route_params|
+      # Verify the parameters first
+      instance_exec(&parametric_checker_proc)
+      # Execute the original action via instance_exec, passing along the route args
+      instance_exec(*matched_sinatra_route_params, &blk)
+    end
+    
+    # Reset for the subsequent action definition
+    @apiculture_action_definition = ActionDefinition.new
+    # and store the just defined action for future use
+    apiculture_stack << action_def
+  end
+  
+  def apiculture_stack
+    @apiculture_actions_and_docs ||= []
+    @apiculture_actions_and_docs
+  end
+end