reynard 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96421332b89c0816b77704aba7b07f267424c0a238fd5b74c8b91aa9d3943c6d
-  data.tar.gz: a6a714f984bd420fe2254b747972ba804968cc4df6ca534b38c50c1cf2b2687b
+  metadata.gz: 2942c304a1a9caaae88253e2bce40188b79bb8a5d25ccd93c8e9a04f7730e386
+  data.tar.gz: 12948419634f2926ae083ae364bd35f48a6b79b8f6308df95b80baafe061dce6
 SHA512:
-  metadata.gz: 7cbb02d762e3c38b05b59ec25f8320f3a5830b56aabe376249f2347a098b43cff31935829d9dd831edc383a62531a06b78e735d886bf4f2329475e8785820211
-  data.tar.gz: 767b9ba9f0f5eb3fae98d414f778e481fd6b3c0a928128cec29b3a409db44481057afc44c9ac029a98892b71c3d3e09fd80286e0b2e942e47aef97b2921fab22
+  metadata.gz: 2bcf669808d10dfff594861274b301ff77c99038ddea5e121b0ccd61336beb7089e6c20f4e566c9a29e5b813194f5b79d07c7c067c720b6b303de8c07e862944
+  data.tar.gz: 64f7877a9a9e44c77cb357ff36d2ecac691cfce668dc2ba2197f0b68a284e0127fab96c099ca3cb99c0390658466a4fcda3569a2e2479e643d73f95d06cf2a16

data/README.md

@@ -48,7 +48,7 @@ reynard.base_url(base_url)
 
 ## Calling endpoints
 
-Assuming there is an operation called `employeeByUuid` you can it as shown below.
+Assuming there is an operation with the `operationId` set to `employeeByUuid` you can perform a request as shown below. Note that `operationId` is a required property in the specs.
 
 ```ruby
 response = reynard.
@@ -57,7 +57,7 @@ response = reynard.
   execute
 ```
 
-When an operation requires a body, you can add it as structured data.
+When an operation requires a body, you can add it as structured data. It will be converted to JSON automatically.
 
 ```ruby
 response = reynard.
@@ -66,13 +66,7 @@ response = reynard.
   execute
 ```
 
-In case the response matches a response in the specification it will attempt to build an object using the specified schema.
-
-```ruby
-response.object.name #=> 'Sam Seven'
-```
-
-The response object shared much of its interface with `Net::HTTP::Response`.
+The response object shares much of its interface with `Net::HTTP::Response`.
 
 ```ruby
 response.code #=> '200'
@@ -82,6 +76,24 @@ response.body #=> '{"name":"Sam Seven"}'
 response.parsed_body #=> { "name" => "Sam Seven" }
 ```
 
+You can test for groups of response codes, basically matching `1xx` through `5xx`.
+
+```ruby
+response.informational?
+response.success?
+response.redirection?
+response.client_error?
+response.server_error?
+```
+
+In case the response status and content-type matches a response in the specification it will attempt to build an object using the specified schema.
+
+```ruby
+response.object.name #=> 'Sam Seven'
+```
+
+See below for more details about the object builder.
+
 ## Schema and models
 
 Reynard has an object builder that allows you to get a value object backed by model classes based on the resource schema.
@@ -189,7 +201,7 @@ There are two alternatives for accessing this property:
 # parsed JSON on the response object.
 response.parsed_body["1st-class"]
 # When you are processing nested models and you don't have access to the
-# response object, you can chose to use the `[]` method.
+# response object, you can choose to use the `[]` method.
 response.object["1st-class"]
 # Don't use `send` to access the property, this may not work in future
 # versions.
@@ -198,7 +210,7 @@ response.object.send("1st-class")
 
 #### Mapping properties
 
-In case you are forced to access a property through a method, you could chose to map irregular property names to method names globally for all models:
+In case you are forced to access a property through a method, you could choose to map irregular property names to method names globally for all models:
 
 ```ruby
 reynard.snake_cases({ "1st-class" => "first_class" })
@@ -218,6 +230,82 @@ Don't use this to map common property names that would work fine otherwise, beca
 reynard.snake_cases({ "name" => "naem" })
 ```
 
+### Optional properties
+
+The current version of Reynard does not read or enforce the properties defined in the schema, instead it builds the response object based on the properties returned by the service. This was done deliberately to make it easier to access a server with a newer or older schema than the one used to build the Reynard instance.
+
+In the code that means that you may have to check if you are receiving certain attributes, you can do this in a number of ways:
+
+```ruby
+response.object.respond_to?(:name)
+response.parsed_body["name"]
+response.object["name"]
+```
+
+### Taking control of a model
+
+As noted earlier there is a deterministic way in which Reynard decides on a model name. This means that you can define the model name before Reynard gets to it.
+
+The easiest way to find out how Reynard does this, is to actually perform the operation and look at the response. Let's look at an example where Reynard creates  a `Library` model:
+
+```ruby
+response.object.class #=> Reynard::Models::Library
+response.parsed_body #=> {"name" => "Alexandria"}
+```
+
+One way to ensure that the response object has the required attributes is to defined a `valid?` method on it:
+
+
+```ruby
+class Reynard
+  module Models
+    class Library < Reynard::Model
+      def valid?
+        (%w[name] - @attributes.keys).empty?
+      end
+    end
+  end
+end
+```
+
+Next time you perform a request you can use your version of `Library`:
+
+```ruby
+if response.object.valid?
+  puts "The library is valid!"
+else
+  puts "The library is not valid :-( #{response.parsed_object.inspect}"
+end
+```
+
+Another way to do this is to override the `attributes=` method.
+
+```ruby
+def attributes=(attributes)
+  super # call super or nested attributes and other features will break
+  raise_invalid unless valid?
+end
+
+private
+
+def raise_invalid
+  return if valid?
+
+  raise(
+    ArgumentError,
+    "Library may not be initialized without all required attributes."
+  )
+end
+```
+
+A third way of dealing with optional attributes is to define an accessor yourself.
+
+```ruby
+def name
+  @attributes.fetch("name") { "Unnnamed library" }
+end
+```
+
 ## Logging
 
 When you want to know what the Reynard client is doing you can enable logging.
@@ -234,6 +322,19 @@ The logging should be compatible with the Ruby on Rails logger.
 reynard.logger(Rails.logger).execute
 ```
 
+## Headers
+
+You can add request headers at any time to a Reynard context, these are additive so you can easily have global headers for all requests and specific ones for an operation.
+
+```ruby
+reynard = reynard.headers(
+  {
+    "User-Agent" => "MyApplication/12.1.1 Reynard/#{Reynard::VERSION}",
+    "Accept" => "application/json"
+  }
+)
+```
+
 ## Debugging
 
 You can turn on debug logging in `Net::HTTP` by setting the `DEBUG` environment variable. After setting this, all HTTP interaction will be written to STDERR.

data/lib/reynard/model.rb

@@ -28,7 +28,11 @@ class Reynard
     # Until we can set accessors based on the schema
     def method_missing(attribute_name, *)
       attribute_name = attribute_name.to_s
-      @attributes[attribute_name] || @attributes.fetch(@snake_cases.fetch(attribute_name))
+      if @attributes.key?(attribute_name)
+        @attributes[attribute_name]
+      else
+        @attributes.fetch(@snake_cases.fetch(attribute_name))
+      end
     rescue KeyError
       raise NoMethodError, "undefined method `#{attribute_name}' for #{inspect}"
     end

data/lib/reynard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Reynard
-  VERSION = '0.8.0'
+  VERSION = '0.8.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reynard
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Manfred Stienstra
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-07 00:00:00.000000000 Z
+date: 2023-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json