api-blueprint 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: '0809cc6a8a9bb3e101463e557f3e089f8ad14ea4'
-  data.tar.gz: f52e26b878dcf30e2378409e52321709333181b1
+  metadata.gz: 3d23a188a9076e091b9ce710bad84b2bafd27723
+  data.tar.gz: e3cd015fb4cc6b563113515cb8a00f1387fe4345
 SHA512:
-  metadata.gz: be379d505c900cc5d725bc7b67765dde33869a119c29a95dfad39ad986e96711dace8136ccfb05e399f4bb22399e085b54f65d5da67a0f0918fcd00aad9e02e2
-  data.tar.gz: e5d97a944496d8a0255c3489ccb7417f3c5bef1e96b45b80c4617ff1b4c42ba58f20ba338f6ea4cc698a827840d280d7a19c64efc697952903db1e11a29805e3
+  metadata.gz: 4dd0313e92b043c835515e9e970313c79d452167604560de4a988cd7a9aee672629412e990a16fc9c783039eba73bc05e8b50df3e0e735ba41143164a12500dd
+  data.tar.gz: 708aad91e765f722ad8c9fa34b47aa71887d92a3b04fa34a67564bb4d2fb1feecce368283e3e76c3cff47a95c8bd9db15179f70718ad9ddfe375f70f4ff8cb14

data/README.md

@@ -60,3 +60,82 @@ The result of using `api.run` on a blueprint is as you'd expect, nice model inst
   <% end %>
 </ul>
 ```
+
+## 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):
+
+```ruby
+class AstronautsInSpace < ApiBlueprint::Model
+  configure do |config|
+    config.host = "http://api.open-notify.org"
+    config.parser = CustomResponseParser.new
+    config.builder = CustomObjectBuilder.new
+    config.replacements = {}
+  end
+end
+```
+
+### Config.builder
+
+When running a blueprint, after the response is returned and parsed, the result is passed to a builder, which is responsible for initializing objects from the response. The default [ApiBlueprint::Builder](https://github.com/iZettle/api-blueprint/blob/master/lib/api-blueprint/builder.rb)
+ will pass the attributes from the response into the initializer for the class the blueprint was defined in.
+
+If you want to change the behavior of the builder, or have a complex response which needs manipulation before it should be passed to the initializer, you can define a custom builder. Custom builders must inherit from the default builder, and can override any combination of the core methods which are used to build responses; `build`, `prepare_item`, and `build_item`. Refer to the [default builder](https://github.com/iZettle/api-blueprint/blob/master/lib/api-blueprint/builder.rb) to see what those methods do.
+
+### Config.parser
+
+The parser is responsible for taking the raw response body string and generating a useful object from it, which can be passed into the builder to generate instances of the model. The [default parser](https://github.com/iZettle/api-blueprint/blob/master/lib/api-blueprint/parser.rb) is used to parse json strings and return a hash.
+
+If you need a custom parser (for example, an XML parser), you must define a class which inherits from `ApiBlueprint::Parser`, and overrides the `#parse` method.
+
+### Config.replacements
+
+Replacements can be used to handle poorly named keys in api responses, or to re-word things without the need to creating a custom builder. For example, if the api by default returned a key called `numberOfAstronautsInSpace` and you wanted this to assign the `number` attribute on the model, you could use a replacement to handle that:
+
+```ruby
+config.replacements = {
+  numberOfAstronautsInSpace: :number
+}
+```
+
+## 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:
+
+```ruby
+# Most basic usage
+blueprint :get, "/endpoint"
+
+# Different http methods are supported (:get, :post, :put, :delete, :head, :patch, :options)
+blueprint :put, "/endpoint"
+
+# Request headers, body, or params can be passed along
+blueprint :post, "/endpoint", {
+  headers: { "Content-Type": "application/json" },
+  params: { hello: "world" },
+  body: { something: "in the body" }
+}
+
+# If you need to modify the instance which will be returned, or run subsequent requests using
+# the runner, you can do so in a block. Note, this is the only place the runner will be available
+# when running the blueprint.
+blueprint :get, "/endpoint" do |runner, result|
+  result.tap do |astronaut|
+    astronaut.number = 23 # override something
+    astronaut.more_info = runner.run SomeOtherModel.fetch # run another request
+  end
+end
+```
+
+## A note on Dry::Struct immutability
+
+Models you create use `Dry::Struct` to handle initialization and assignment. `Dry::Struct` is designed with immutability in mind, so if you need to mutate the objects you have, there are two possibilities; explicitly define an `attr_writer` for the attributes which you want to mutate, or do things the "Dry::Struct way" and use the current instance to initialize a new instance:
+
+```ruby
+astros = AstronautsInSpace.new number: 5, foo: "bar"
+astros.number # => 5
+astros.number = 10 # NoMethodError: undefined method `number=' for #<AstronautsInSpace number=5 foo="bar">
+new_astros = astros.new number: 10
+new_astros # #<AstronautsInSpace number=10 foo="bar">
+```

data/lib/api-blueprint/blueprint.rb

@@ -47,7 +47,7 @@ module ApiBlueprint
     def call_api(options)
       connection.send options[:http_method] do |req|
         req.url options[:url]
-        req.headers.merge! options[:headers]
+        req.headers.merge!({ "Content-Type": "application/json" }.merge(options[:headers]))
         req.params = options[:params]
         req.body = options[:body].to_json
       end
@@ -56,6 +56,7 @@ module ApiBlueprint
     def connection
       Faraday.new do |conn|
         conn.response :json, content_type: /\bjson$/
+        conn.response :raise_error
         # conn.response :logger
 
         conn.adapter Faraday.default_adapter

data/lib/api-blueprint/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api-blueprint
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Damien Timewell