api-blueprint 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 92b97a2c669c6b891dca65a5d31a2bfa703951bd
-  data.tar.gz: 90dd0b51277c9d8e8279ada2be73e1255c61b75e
+  metadata.gz: bc247d9616a2e34feda3dd467150f03d384628c0
+  data.tar.gz: 68106129bf5eccc56440c0d15ae49f40034c7b20
 SHA512:
-  metadata.gz: 9d36fd33e0683abc566069d8b2698d9317f12fa65e76f0bce55e313bfa43ceb5c1a9191d282cd01359221bd4b012dd6abcccf8b8f4813a10e3a648f184ca72e3
-  data.tar.gz: 242e8eda32ad332e4ebf46e538dcb6173bcbaf8d293ab888ff7aa5a3f7e26fba00a411b295d5577de5b62223209e874c5044ca8d714f1cafaf73d628c943ec12
+  metadata.gz: cc963e572698777cded8128676784cbd2625c6b55f34931a274f7697d93bd57bf50e4ae91590a018841560472898aaf35400a00885e1e0929bfce59a0329c3ca
+  data.tar.gz: 05333cf34ddc87d344cfb5bd90bf8d37e94282b53a6d98114b8a67a04d99450e37dc2470a31aea443ba94b9c57e5eb2bcab17bec3d6beb2eaf6a7c75a00afe53

data/README.md

@@ -61,6 +61,51 @@ The result of using `api.run` on a blueprint is as you'd expect, nice model inst
 </ul>
 ```
 
+## Collections
+
+Sometimes you might want a model which requires multiple api calls and collects the results onto different attributes. You can use an `ApiBlueprint::Model.collection` for this.
+
+```ruby
+class Vehicles < ApiBlueprint::Model
+  attribute :car, Types.Constructor(Car)
+  attribute :bus, Types.Constructor(Bus)
+
+  def self.fetch_all(color)
+    collection \
+      car: Car.all(color),
+      bus: Bus.all(color)
+  end
+end
+
+# Example use
+red_vehicles = api.run Vehicles.fetch_all("red")
+red_vehicles.cars # [<Car>, <Car>, ...]
+red_vehicles.busses # [<Bus>, <Bus>, ...]
+```
+
+## Request registry
+
+If you use the same api request in multiple controllers, it can be cumbersome to remember to set the cache options and pass all required params to api calls. ApiBlueprint includes a registry, which can be used as a container to store blueprints along with cache options and make it quicker and simpler to re-use in controllers.
+
+You can add to the registry when initialing the api runner, or later.
+
+```ruby
+# Add `astronauts_in_space` to the registry when initializing the runner:
+api = ApiBlueprint::Runner.new registry: {
+  astronauts_in_space: { blueprint: -> { AstronautsInSpace.fetch }, cache: { ttl: 10.minutes } }
+}
+
+# Add `vehicles` to the existing registry:
+api.register :vehicles, -> { Vehicles.fetch_all }, ttl: 60.minutes
+```
+
+Once a blueprint is registered in the registry, you can invoke it via the key name on the runner:
+
+```ruby
+api.astronauts_in_space # the same as running api.run AstronautsInSpace.fetch, ttl: 10.minutes
+api.vehicles # the same as running api.run Vehicles.fetch_all, ttl: 60.minutes
+```
+
 ## Model Configuration
 
 Using a `configure` block on models, you can define a default url (host), a [parser](#configparser), a [builder](#configbuilder) and can define a list of [replacements](#configreplacements):
@@ -126,10 +171,10 @@ Certain response statuses will also cause ApiBlueprint to behave in different wa
 
 | HTTP Status range | Behavior |
 | ----------------- | -------- |
-| 200 - 399 | Objects are built normally, no errors raised |
+| 200 - 400 | Objects are built normally, no errors raised |
 | 401 | raises `ApiBlueprint::UnauthenticatedError` |
 | 404 | raises `ApiBlueprint::NotFoundError` |
-| 400 - 499 | raises `ApiBlueprint::ClientError` |
+| 402 - 499 | raises `ApiBlueprint::ClientError` |
 | 500 - 599 | raises `ApiBlueprint::ServerError` |
 
 ## Access to response headers and status codes

data/lib/api-blueprint.rb

@@ -7,6 +7,7 @@ require 'active_model'
 require 'active_support/core_ext/hash'
 require 'addressable'
 
+require 'api-blueprint/struct'
 require 'api-blueprint/response_middleware'
 require 'api-blueprint/cache'
 require 'api-blueprint/types'
@@ -19,10 +20,19 @@ require 'api-blueprint/runner'
 require 'api-blueprint/collection'
 
 module ApiBlueprint
+  class ResponseError < StandardError
+    attr_reader :status, :headers, :body
+    def initialize(env)
+      @status = env.status
+      @headers = env.response_headers.symbolize_keys
+      @body = env.body
+    end
+  end
+
   class DefinitionError < StandardError; end
   class BuilderError < StandardError; end
-  class ServerError < StandardError; end
-  class UnauthenticatedError < StandardError; end
-  class ClientError < StandardError; end
-  class NotFoundError < StandardError; end
+  class ServerError < ResponseError; end
+  class UnauthenticatedError < ResponseError; end
+  class ClientError < ResponseError; end
+  class NotFoundError < ResponseError; end
 end

data/lib/api-blueprint/blueprint.rb

@@ -1,14 +1,12 @@
 module ApiBlueprint
-  class Blueprint < Dry::Struct
-    constructor_type :schema
-
+  class Blueprint < ApiBlueprint::Struct
     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 :parser, Types.Instance(ApiBlueprint::Parser).optional.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)

data/lib/api-blueprint/builder.rb

@@ -1,12 +1,11 @@
 module ApiBlueprint
-  class Builder < Dry::Struct
-    constructor_type :schema
+  class Builder < ApiBlueprint::Struct
 
     attribute :body, Types::Hash.default(Hash.new)
     attribute :headers, Types::Hash.default(Hash.new)
-    attribute :status, Types::Int.optional
+    attribute :status, Types::Integer.optional
     attribute :replacements, Types::Hash.default(Hash.new)
-    attribute :creates, Types::Any
+    attribute :creates, Types::Any.optional
 
     attr_writer :body
 

data/lib/api-blueprint/model.rb

@@ -1,5 +1,5 @@
 module ApiBlueprint
-  class Model < Dry::Struct
+  class Model < ApiBlueprint::Struct
     extend Dry::Configurable
     include ActiveModel::Conversion
     include ActiveModel::Validations
@@ -7,15 +7,13 @@ module ApiBlueprint
     extend ActiveModel::Naming
     extend ActiveModel::Callbacks
 
-    constructor_type :schema
-
     setting :host, ""
     setting :parser, Parser.new
     setting :builder, Builder.new
     setting :replacements, {}
 
     attribute :response_headers, Types::Hash.optional
-    attribute :response_status, Types::Int.optional
+    attribute :response_status, Types::Integer.optional
 
     def self.blueprint(http_method, url, options = {}, &block)
       blueprint_opts = {

data/lib/api-blueprint/response_middleware.rb

@@ -4,19 +4,15 @@ module ApiBlueprint
     def on_complete(env)
       case env[:status]
       when 401
-        raise ApiBlueprint::UnauthenticatedError, response_values(env)
+        raise ApiBlueprint::UnauthenticatedError.new(env)
       when 404
-        raise ApiBlueprint::NotFoundError, response_values(env)
+        raise ApiBlueprint::NotFoundError.new(env)
       when 402..499
-        raise ApiBlueprint::ClientError, response_values(env)
+        raise ApiBlueprint::ClientError.new(env)
       when 500...599
-        raise ApiBlueprint::ServerError, response_values(env)
+        raise ApiBlueprint::ServerError.new(env)
       end
     end
 
-    def response_values(env)
-      { status: env.status, headers: env.response_headers, body: env.body }
-    end
-
   end
 end

data/lib/api-blueprint/runner.rb

@@ -4,6 +4,7 @@ module ApiBlueprint
 
     option :headers, default: proc { {} }
     option :cache, default: proc { Cache.new key: "global" }
+    option :registry, default: proc { {} }
 
     def run(item, cache_options = {})
       if item.is_a?(Blueprint)
@@ -19,6 +20,18 @@ module ApiBlueprint
       { headers: headers, cache: cache }
     end
 
+    def register(name, blueprint, cache_options = {})
+      registry[name] = { blueprint: blueprint, cache: cache_options }
+    end
+
+    def method_missing(name, *args, &block)
+      if stored_method = registry[name].presence
+        run stored_method[:blueprint].call(*args), stored_method[:cache]
+      else
+        raise NoMethodError, "#{name} is not defined in the ApiBlueprint::Runner registry"
+      end
+    end
+
     private
 
     def run_blueprint(blueprint, cache_options)

data/lib/api-blueprint/struct.rb

@@ -0,0 +1,9 @@
+module ApiBlueprint
+  class Struct < Dry::Struct
+    transform_keys &:to_sym
+
+    transform_types do |type|
+      type.default? ? type : type.meta(omittable: true)
+    end
+  end
+end

data/lib/api-blueprint/version.rb

@@ -1,3 +1,3 @@
 module ApiBlueprint
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api-blueprint
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Damien Timewell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-26 00:00:00.000000000 Z
+date: 2018-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-types
@@ -212,6 +212,7 @@ files:
 - lib/api-blueprint/parser.rb
 - lib/api-blueprint/response_middleware.rb
 - lib/api-blueprint/runner.rb
+- lib/api-blueprint/struct.rb
 - lib/api-blueprint/types.rb
 - lib/api-blueprint/url.rb
 - lib/api-blueprint/version.rb