api-blueprint 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ec684c45d9e4a9a68fff3a249ccf2a55867fe871
-  data.tar.gz: a3d9ae3d1a9cb681122a854f8f71b6e1860d8cf7
+  metadata.gz: 690bfec6246875178ddab86cb4b39c78543a689c
+  data.tar.gz: ea236a3bdd43e5ab463573d072f43d6bca9751a8
 SHA512:
-  metadata.gz: 29850f1231fb34be81d8efcd579ca995741fe896ad2b0d91e4b9372c7c5d4d7e92e82d9b915bea884bafcb4b73fbbe879cb07f2c64481a7395e0158ad344516e
-  data.tar.gz: aceaf3b5c6ce9e8b052fd0968947042922701e8b05e6c29b8bea29205115ba7d4a8fa521b859c69406c9fe5692629170bf7830520ec0c5bee85beb3026b0968f
+  metadata.gz: c9f5f9c9bba8fe2d8081cc2fbea82d8e8bb3e9fc48d6a720d1df88ec424fb3e5e70a4462e2a2d2d60ca41b97fdbd5725cc8cdcdbe41479bbd484ac0d67dbf620
+  data.tar.gz: f7b52ca2dac76e595625a3e4aec9e9ed68a9cf8f144c7979ae699e8a832e9e32380fdda2935ef6b0d1e43f46836d0eb09213599cfa155a699419e08db0166df5

data/README.md

@@ -118,6 +118,37 @@ Astronaut.send_to_space(nil) # => <ActiveModel::Errors ...>
 
 Behind the scenes, ApiBlueprint uses the body hash to initialize a new instance of your model, and then runs validations. If there are any errors, the API request is not run and the errors object is returned.
 
+## Error handling
+
+If an API response includes an `errors` object, ApiBlueprint uses it to assign `ActiveModel::Errors` instances on the class which is built. This way, validation errors which come an the API behave exactly the same as validation errors set locally through validations on the model.
+
+Certain response statuses will also cause ApiBlueprint to behave in different ways:
+
+| HTTP Status range | Behavior |
+| ----------------- | -------- |
+| 200 - 400 | Objects are built normally, no errors raised |
+| 401 | raises `ApiBlueprint::UnauthenticatedError` |
+| 402 - 499 | raises `ApiBlueprint::ClientError` |
+| 500 - 599 | raises `ApiBlueprint::ServerError` |
+
+## Access to response headers and status codes
+
+By default, ApiBlueprint tries to set `response_headers` and `response_status` on the model which is created from an API response. `ApiBlueprint::Model` also has a convenience method `api_request_success?` which can be used to easily assert whether a response was in the 200-399 range. This makes it simple to render different responses in controllers. For example:
+
+```ruby
+# app/controllers/astronauts_controller.rb
+class AstronautsController < ApplicationController
+  def index
+    @astronauts = api.run AstronautsInSpace.fetch
+    if @astronauts.api_request_success?
+      render json: @astronauts
+    else
+      render json: @astronauts.errors, status: :bad_request
+    end
+  end
+end
+```
+
 ## Blueprint options
 
 When defining a blueprint in a model, you can pass it a number of options to set request headers, params, body, or to run code after an instance of the model has been initialized. Here's some examples:

data/lib/api-blueprint/blueprint.rb

@@ -32,7 +32,7 @@ module ApiBlueprint
       response = call_api all_request_options(options)
 
       if creates.present?
-        created = build from: response.body, headers: response.headers
+        created = build from: response.body, headers: response.headers, status: response.status
       else
         created = response
       end
@@ -42,15 +42,18 @@ module ApiBlueprint
 
     private
 
-    def build(from:, headers: {})
+    def build(from:, headers: {}, status: nil)
       builder_options = {
         body: parser.parse(from),
         headers: headers,
+        status: status,
         replacements: replacements,
         creates: creates
       }
 
-      builder.new(builder_options).build
+      builder.new(builder_options).build.tap do |built|
+        set_errors built, builder_options[:body]
+      end
     end
 
     def call_api(options)
@@ -64,8 +67,8 @@ module ApiBlueprint
 
     def connection
       Faraday.new do |conn|
+        conn.use ApiBlueprint::ResponseMiddleware
         conn.response :json, content_type: /\bjson$/
-        conn.response :raise_error
         # conn.response :logger
 
         conn.adapter Faraday.default_adapter
@@ -75,5 +78,24 @@ module ApiBlueprint
       end
     end
 
+    def set_errors(obj, body)
+      if obj.respond_to?(:errors) && body.is_a?(Hash)
+        errors = body.with_indifferent_access.fetch :errors, {}
+        errors.each do |field, messages|
+          if messages.is_a? Array
+            messages.each do |message|
+              set_error obj, field, message
+            end
+          else
+            set_error obj, field, messages
+          end
+        end
+      end
+    end
+
+    def set_error(obj, field, messages)
+      obj.errors.add field.to_sym, messages
+    end
+
   end
 end

data/lib/api-blueprint/builder.rb

@@ -4,6 +4,7 @@ module ApiBlueprint
 
     attribute :body, Types::Hash.default(Hash.new)
     attribute :headers, Types::Hash.default(Hash.new)
+    attribute :status, Types::Int.optional
     attribute :replacements, Types::Hash.default(Hash.new)
     attribute :creates, Types::Any
 
@@ -18,7 +19,12 @@ module ApiBlueprint
     end
 
     def prepare_item(item)
-      with_replacements item.with_indifferent_access
+      meta = {
+        response_headers: headers,
+        response_status: status
+      }
+
+      meta.merge with_replacements(item.deep_symbolize_keys)
     end
 
     def build_item(item)

data/lib/api-blueprint/model.rb

@@ -14,6 +14,9 @@ module ApiBlueprint
     setting :builder, Builder.new
     setting :replacements, {}
 
+    attribute :response_headers, Types::Hash.optional
+    attribute :response_status, Types::Int.optional
+
     def self.blueprint(http_method, url, options = {}, &block)
       blueprint_opts = {
         http_method: http_method,
@@ -35,5 +38,9 @@ module ApiBlueprint
       Collection.new blueprints, self
     end
 
+    def api_request_success?
+      response_status.present? && (200...299).include?(response_status)
+    end
+
   end
 end

data/lib/api-blueprint/parser.rb

@@ -5,6 +5,8 @@ module ApiBlueprint
     # to make a custom parser.
     def parse(body)
       body.is_a?(String) ? JSON.parse(body) : body
+    rescue JSON::ParserError
+      {}
     end
 
   end

data/lib/api-blueprint/response_middleware.rb

@@ -0,0 +1,20 @@
+module ApiBlueprint
+  class ResponseMiddleware < Faraday::Response::Middleware
+
+    def on_complete(env)
+      case env[:status]
+      when 401
+        raise ApiBlueprint::UnauthenticatedError, response_values(env)
+      when 402..499
+        raise ApiBlueprint::ClientError, response_values(env)
+      when 500...599
+        raise ApiBlueprint::ServerError, response_values(env)
+      end
+    end
+
+    def response_values(env)
+      { status: env.status, headers: env.response_headers, body: env.body }
+    end
+
+  end
+end

data/lib/api-blueprint/version.rb

@@ -1,3 +1,3 @@
 module ApiBlueprint
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/api-blueprint.rb

@@ -7,6 +7,7 @@ require 'active_model'
 require 'active_support/core_ext/hash'
 require 'addressable'
 
+require 'api-blueprint/response_middleware'
 require 'api-blueprint/cache'
 require 'api-blueprint/types'
 require 'api-blueprint/url'
@@ -20,4 +21,7 @@ require 'api-blueprint/collection'
 module ApiBlueprint
   class DefinitionError < StandardError; end
   class BuilderError < StandardError; end
+  class ServerError < StandardError; end
+  class UnauthenticatedError < StandardError; end
+  class ClientError < StandardError; end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api-blueprint
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Damien Timewell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-13 00:00:00.000000000 Z
+date: 2018-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-types
@@ -210,6 +210,7 @@ files:
 - lib/api-blueprint/collection.rb
 - lib/api-blueprint/model.rb
 - lib/api-blueprint/parser.rb
+- lib/api-blueprint/response_middleware.rb
 - lib/api-blueprint/runner.rb
 - lib/api-blueprint/types.rb
 - lib/api-blueprint/url.rb