api-blueprint 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: '0809cc6a8a9bb3e101463e557f3e089f8ad14ea4'
+  data.tar.gz: f52e26b878dcf30e2378409e52321709333181b1
+SHA512:
+  metadata.gz: be379d505c900cc5d725bc7b67765dde33869a119c29a95dfad39ad986e96711dace8136ccfb05e399f4bb22399e085b54f65d5da67a0f0918fcd00aad9e02e2
+  data.tar.gz: e5d97a944496d8a0255c3489ccb7417f3c5bef1e96b45b80c4617ff1b4c42ba58f20ba338f6ea4cc698a827840d280d7a19c64efc697952903db1e11a29805e3

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2018 Damien
+
+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,62 @@
+# ApiBlueprint
+
+ApiBlueprint is a simple wrapper designed to be used in a Rails app for running http requests through Faraday and generating strongly-typed models from the JSON responses.
+
+## Example use
+
+The examples below use the [open notify astros](http://api.open-notify.org/astros.json) api endpoint to list the astronauts who are current in space and which craft they are on.
+
+### Blueprints in models
+
+Using ApiBlueprint::Model, you can define model classes with [dry-types attributes](http://dry-rb.org/gems/dry-types/) and define blueprints which describe how an api call will be made.
+
+```ruby
+# app/models/person.rb
+class Person < ApiBlueprint::Model
+  attribute :name, Types::String
+  attribute :craft, Types::String
+end
+
+# app/models/astronauts_in_space.rb
+class AstronautsInSpace < ApiBlueprint::Model
+  attribute :number, Types::Integer
+  attribute :people, Types::Array.of(Types.Constructor(Person))
+
+  def self.fetch
+    blueprint :get, "http://api.open-notify.org/astros.json"
+  end
+end
+```
+
+### Running blueprints
+
+Blueprints can be run from controllers using an instance of `ApiBlueprint::Runner`. You can use that runner instance to store session based information such as Authorization headers and such which need to be passed into requests.
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  def api
+    ApiBlueprint::Runner.new headers: { Authorization: "something" }
+  end
+end
+
+# app/controllers/astronauts_controller.rb
+class AstronautsController < ApplicationController
+  def index
+    @astronauts = api.run AstronautsInSpace.fetch
+  end
+end
+```
+
+The result of using `api.run` on a blueprint is as you'd expect, nice model instances with the attributes set:
+
+```erb
+<!-- app/views/astronauts/index.html.erb -->
+<h1>There are <%= @astronauts.number %> astronauts in space currently:</h1>
+
+<ul>
+  <% @astronauts.each do |astronaut| %>
+    <li><%= astronaut.name %> is on <%= astronaut.craft %></li>
+  <% end %>
+</ul>
+```

data/Rakefile

@@ -0,0 +1,33 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ApiBlueprint'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/lib/api-blueprint.rb

@@ -0,0 +1,21 @@
+require 'dry-types'
+require 'dry-struct'
+require 'dry-initializer'
+require 'faraday'
+require 'faraday_middleware'
+require 'active_model'
+require 'addressable'
+
+require 'api-blueprint/cache'
+require 'api-blueprint/types'
+require 'api-blueprint/url'
+require 'api-blueprint/parser'
+require 'api-blueprint/builder'
+require 'api-blueprint/model'
+require 'api-blueprint/blueprint'
+require 'api-blueprint/runner'
+require 'api-blueprint/collection'
+
+module ApiBlueprint
+  class DefinitionError < StandardError; end
+end

data/lib/api-blueprint/blueprint.rb

@@ -0,0 +1,69 @@
+module ApiBlueprint
+  class Blueprint < Dry::Struct
+    constructor_type :schema
+
+    attribute :http_method, Types::Symbol.default(:get).enum(*Faraday::Connection::METHODS)
+    attribute :url, Types::String
+    attribute :headers, Types::Hash.default(Hash.new)
+    attribute :params, Types::Hash.default(Hash.new)
+    attribute :body, Types::Hash.default(Hash.new)
+    attribute :creates, Types::Any
+    attribute :parser, Types.Instance(ApiBlueprint::Parser).default(ApiBlueprint::Parser.new)
+    attribute :replacements, Types::Hash.default(Hash.new)
+    attribute :after_build, Types::Instance(Proc).optional
+    attribute :builder, Types.Instance(ApiBlueprint::Builder).default(ApiBlueprint::Builder.new)
+
+    def all_request_options(options = {})
+      {
+        http_method: http_method,
+        url: url,
+        headers: headers.merge(options.fetch(:headers, {})),
+        params: params.merge(options.fetch(:params, {})),
+        body: body.merge(options.fetch(:body, {}))
+      }
+    end
+
+    def run(options = {}, runner = nil)
+      response = call_api all_request_options(options)
+
+      if creates.present?
+        builder_options = {
+          body: parser.parse(response.body),
+          headers: response.headers,
+          replacements: replacements,
+          creates: creates
+        }
+
+        created = builder.new(builder_options).build
+      else
+        created = response
+      end
+
+      after_build.present? ? after_build.call(runner, created) : created
+    end
+
+    private
+
+    def call_api(options)
+      connection.send options[:http_method] do |req|
+        req.url options[:url]
+        req.headers.merge! options[:headers]
+        req.params = options[:params]
+        req.body = options[:body].to_json
+      end
+    end
+
+    def connection
+      Faraday.new do |conn|
+        conn.response :json, content_type: /\bjson$/
+        # conn.response :logger
+
+        conn.adapter Faraday.default_adapter
+        conn.headers = {
+          "User-Agent": "ApiBlueprint"
+        }
+      end
+    end
+
+  end
+end

data/lib/api-blueprint/builder.rb

@@ -0,0 +1,39 @@
+module ApiBlueprint
+  class Builder < Dry::Struct
+    constructor_type :schema
+
+    attribute :body, Types::Hash.default(Hash.new)
+    attribute :headers, Types::Hash.default(Hash.new)
+    attribute :replacements, Types::Hash.default(Hash.new)
+    attribute :creates, Types::Any
+
+    attr_writer :body
+
+    def build
+      if body.is_a? Array
+        body.collect { |item| build_item prepare_item(item) }
+      else
+        build_item prepare_item(body)
+      end
+    end
+
+    def prepare_item(item)
+      with_replacements item.with_indifferent_access
+    end
+
+    def build_item(item)
+      creates.new item
+    end
+
+    private
+
+    def with_replacements(item)
+      item.tap do |item|
+        replacements.each do |bad, good|
+          item[good] = item.delete bad if item.has_key? bad
+        end
+      end
+    end
+
+  end
+end

data/lib/api-blueprint/cache.rb

@@ -0,0 +1,26 @@
+module ApiBlueprint
+  class Cache
+    extend Dry::Initializer
+
+    option :key
+
+    def exist?(id)
+      false
+    end
+
+    def read(id)
+      false
+    end
+
+    def write(id, data, options)
+      data
+    end
+
+    def generate_cache_key(options)
+      options = options.clone.except :body
+      options_digest = Digest::MD5.hexdigest Marshal::dump(options.to_s.chars.sort.join)
+      "#{key}:#{options_digest}"
+    end
+
+  end
+end

data/lib/api-blueprint/collection.rb

@@ -0,0 +1,24 @@
+module ApiBlueprint
+  class Collection
+
+    attr_reader :blueprints, :creates
+
+    def initialize(blueprints, creates = nil)
+      unless blueprints.is_a?(Hash)
+        raise DefinitionError, "a collection of blueprints must be a hash"
+      end
+
+      unless blueprints.values.all? { |bp| bp.is_a? Blueprint }
+        raise DefinitionError, "all collection values must be blueprints"
+      end
+
+      @blueprints = blueprints
+      @creates = creates
+    end
+
+    def create(args)
+      creates.present? ? creates.new(args) : args
+    end
+
+  end
+end

data/lib/api-blueprint/model.rb

@@ -0,0 +1,39 @@
+module ApiBlueprint
+  class Model < Dry::Struct
+    extend Dry::Configurable
+    include ActiveModel::Conversion
+    include ActiveModel::Validations
+    include ActiveModel::Serialization
+    extend ActiveModel::Naming
+    extend ActiveModel::Callbacks
+
+    constructor_type :schema
+
+    setting :host, ""
+    setting :parser, Parser.new
+    setting :builder, Builder.new
+    setting :replacements, {}
+
+    def self.blueprint(http_method, url, options = {}, &block)
+      blueprint_opts = {
+        http_method: http_method,
+        url: Url.new(config.host, url).to_s,
+        creates: self,
+        parser: config.parser,
+        replacements: config.replacements,
+        builder: config.builder
+      }.merge(options)
+
+      if block_given?
+        blueprint_opts[:after_build] = block
+      end
+
+      Blueprint.new blueprint_opts
+    end
+
+    def self.collection(blueprints)
+      Collection.new blueprints, self
+    end
+
+  end
+end

data/lib/api-blueprint/parser.rb

@@ -0,0 +1,11 @@
+module ApiBlueprint
+  class Parser
+
+    # Nothing special here. Write a class which overrides #parse
+    # to make a custom parser.
+    def parse(body)
+      body.is_a?(String) ? JSON.parse(body) : body
+    end
+
+  end
+end

data/lib/api-blueprint/runner.rb

@@ -0,0 +1,50 @@
+module ApiBlueprint
+  class Runner
+    extend Dry::Initializer
+
+    option :headers, default: proc { {} }
+    option :cache, default: proc { Cache.new key: "global" }
+
+    def run(item, cache_options = {})
+      if item.is_a?(Blueprint)
+        run_blueprint item, cache_options
+      elsif item.is_a?(Collection)
+        run_collection item, cache_options
+      else
+        raise ArgumentError, "expected a blueprint or blueprint collection, got #{item.class}"
+      end
+    end
+
+    def runner_options
+      { headers: headers, cache: cache }
+    end
+
+    private
+
+    def run_blueprint(blueprint, cache_options)
+      request_options = blueprint.all_request_options(runner_options)
+
+      if cache.present?
+        cache_key = cache.generate_cache_key request_options
+        return cache.read cache_key if cache.exist? cache_key
+      end
+
+      blueprint.run(runner_options, self).tap do |result|
+        if cache.present?
+          cache_key = cache.generate_cache_key request_options
+          cache.write cache_key, result, cache_options
+        end
+      end
+    end
+
+    def run_collection(collection, cache_options)
+      args = {}
+      collection.blueprints.each do |name, blueprint|
+        args[name] = run_blueprint blueprint, cache_options
+      end
+
+      collection.create args
+    end
+
+  end
+end

data/lib/api-blueprint/types.rb

@@ -0,0 +1,3 @@
+module Types
+  include Dry::Types.module
+end

data/lib/api-blueprint/url.rb

@@ -0,0 +1,30 @@
+module ApiBlueprint
+  class Url
+    attr_reader :base, :custom
+
+    def initialize(base = "", custom = "")
+      self.base = base
+      self.custom = custom
+    end
+
+    def base=(str)
+      @base = Addressable::URI.parse str
+    end
+
+    def custom=(str)
+      @custom = Addressable::URI.parse str
+    end
+
+    def to_s
+      if base.path.present? && custom.path.present? && !custom.host.present?
+        # Join paths in a permissive way which handles extra slashes gracefully and returns
+        # a string which Addressable can handle when joining with other paths
+        paths = [base.path, custom.path].compact.map { |path| path.gsub(%r{^/*(.*?)/*$}, '\1') }.join("/")
+        Addressable::URI.join(base.site, paths).to_s
+      else
+        base.join(custom).to_s
+      end
+    end
+
+  end
+end

data/lib/api-blueprint/version.rb

@@ -0,0 +1,3 @@
+module ApiBlueprint
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,256 @@
+--- !ruby/object:Gem::Specification
+name: api-blueprint
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Damien Timewell
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-04-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: dry-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: dry-initializer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: dry-configurable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.1.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.1.5
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A faster, leaner, and simpler successor to ApiModel. Makes returning
+  objects from api calls a breeze.
+email:
+- mail@damientimewell.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/api-blueprint.rb
+- lib/api-blueprint/blueprint.rb
+- lib/api-blueprint/builder.rb
+- lib/api-blueprint/cache.rb
+- lib/api-blueprint/collection.rb
+- lib/api-blueprint/model.rb
+- lib/api-blueprint/parser.rb
+- lib/api-blueprint/runner.rb
+- lib/api-blueprint/types.rb
+- lib/api-blueprint/url.rb
+- lib/api-blueprint/version.rb
+homepage: https://github.com/iZettle/api-blueprint
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.14
+signing_key: 
+specification_version: 4
+summary: A faster, leaner, and simpler successor to ApiModel. Makes returning objects
+  from api calls a breeze.
+test_files: []