ddy_remote_resource 1.0.0.rc2 → 1.0.0.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f35784393790ebf350ef35b54603bb614377dff0
-  data.tar.gz: c76505446def63c7885faff3af1b0691405d2014
+  metadata.gz: 81d5006754f703089ef4ce8518c6d76d436f99e0
+  data.tar.gz: fe02833dc3ff9b27f2d737c22b0c7944600a39ad
 SHA512:
-  metadata.gz: bb631e61a3730f260c44dec931ea1da7a97eda48c5dd4f4f56be1456a0d697183083c646cfe8c9210d827fd7bdd5c89594d9285ee28a1beb3f8740169c1b2f0f
-  data.tar.gz: 609cc90d3de1c59bff32be7809df7eb24292d7806a0df1e35f9dbe38c2b7ab77d60608e41abacfd17f96260f17dc8d0e2f712668bbe21ed0ef3163d3e9df4ce1
+  metadata.gz: a7415dc3bc53bb4d491e0751bb27f231e066917f25069f4716480f6f307a0ee8111434770b166166aead5b1853dbdf7324f591ad1e27127896bf367080047a64
+  data.tar.gz: 2b66490233d2656431bd44afb72ef1de4d86bbecb0cbe4e11e5fc60cfff61317c2255dedbeb8d5b43ac2deb29250de96cdd5f357a45ce5c33967ee0c4aec5e6b

data/README.md

@@ -1,6 +1,6 @@
 # RemoteResource
 
-RemoteResource is a gem to use resources with REST services.
+RemoteResource is a gem to consume resources with REST services.
 
 ## Goal of RemoteResource
 
@@ -18,173 +18,184 @@ gem 'remote_resource', git: 'git@lab.digidentity.eu:jvanderpas/remote_resource.g
 gem 'ddy_remote_resource', require: 'remote_resource'
 ```
 
-
 ## Usage
 
 Simply include the `RemoteResource::Base` module in the class you want to enable for the REST services.
 
 ```ruby
-class ContactPerson
+class Post
   include RemoteResource::Base
 
-  self.site    = "https://www.myapp.com"
-  self.version = '/v2'
+  self.site       = 'https://www.example.com'
+  self.collection = true # This option will become default in future versions
+
+  attribute :title, String
+  attribute :featured, Boolean
 end
 ```
 
-### Options
-
-You can set a few options for the `RemoteResource` enabled class.
-
-
-#### Base URL options (`base_url`)
+### Querying
 
-The `base_url` is constructed from the `.site`, `.version`,  `.path_prefix`, `.path_postfix`, `.collection`, `.collection_prefix`, and `.collection_name` options. The `.collection_name` is automatically constructed from the relative class name.
+#### Finder methods
 
-We will use the `ContactPerson` class for these examples, with the `.collection_name` of `'contact_person'`:
+To retrieve resources from the REST service, you can use the `.find`, `.find_by`, `.all` and `.where` class methods:
 
-* `.site`: This sets the URL which should be used to construct the `base_url`.
-    * *Example:* `.site = "https://www.myapp.com"`
-    * *`base_url`:* `https://www.myapp.com/contact_person`
-* `.version`: This sets the API version for the path, after the `.site` and before the `.path_prefix` that is used to construct the `base_url`.
-    * *Example:* `.version = "/api/v2"`
-    * *`base_url`:* `https://www.myapp.com/api/v2/contact_person`
-* `.path_prefix`: This sets the prefix for the path, after the `.version` and before the `.collection_name` that is used to construct the `base_url`.
-    * *Example:* `.path_prefix = "/registration"`
-    * *`base_url`:* `https://www.myapp.com/registration/contact_person`
-* `.path_postfix`: This sets the postfix for the path, after the `.collection_name` that is used to construct the `base_url`.
-    * *Example:* `.path_postfix = "/new"`
-    * *`base_url`:* `https://www.myapp.com/contact_person/new`
-* `.collection`: This toggles the pluralization of the `collection_name` that is used to construct the `base_url`.
-    * *Default:* `false`
-    * *Example:* `.collection = true`
-    * *`base_url`:* `https://www.myapp.com/contact_persons`
-* `.collection_prefix`: This sets the prefix for the collection, before `collection_name` that is used to construct the `base_url`. The prefix variable has to be set via connection_options' key `collection_options`.
-    * *Default:* ``
-    * *Example:* `.collection_prefix = "/companies/:company_id"` and connection_options `collection_options: { company_id: 2 }`
-    * *`base_url`:* `https://www.myapp.com/companies/2/contact_persons`
-* `.collection_name`: This sets the `collection_name` that is used to construct the `base_url`.
-    * *Example:* `.collection_name = "company"`
-    * *`base_url`:* `https://www.myapp.com/company`
+```ruby
+# provide the `id` of the resource as argument
+Post.find(12) #=> GET https://www.example.com/posts/12.json
 
-**override**
+# provide the conditions as argument
+Post.find_by(title: 'Our awesome post') #=> GET https://www.example.com/posts.json?title=Our+awesome+post
 
-To override the `base_url` completely, you can use the `base_url` option. This option should be passed into the `connection_options` hash when making a request:
+# no arguments required
+Post.all #=> GET https://www.example.com/posts.json
 
-* `base_url`: This sets the `base_url`. *note: this does not override the `.content_type` option*
-    * *Example:* `{ base_url: "https://api.foo.com/v1" }`
-    * *`base_url`:* `https://api.foo.com/v1`
+# provide the conditions as argument
+Post.where(ids: [10, 11, 12]) #=> GET https://www.example.com/posts.json?ids[]=10&ids[]=11&ids[]=12
+```
 
+#### Persistence methods
 
-#### Request options
+To create or alter resources from the REST service, you can use the `.create` and `.destroy` class methods or the `#save`, `#update_attributes` and `#destroy` instance methods:
 
-Apart from the options which manipulate the `base_url`, there are some more:
+```ruby
+# provide the attributes as argument
+Post.create(title: 'Our awesome post', featured: true) #=> POST https://www.example.com/posts.json
+
+# provide the attributes on the resource
+# new resource
+post          = Post.new
+post.title    = 'Our awesome post'
+post.featured = true
+post.save #=> POST https://www.example.com/posts.json
+
+# existing resource
+post          = Post.new(id: 12)
+post.title    = 'Our awesome post'
+post.featured = true
+post.save #=> PATCH https://www.example.com/posts/12.json
+
+# provide the attributes as argument
+post = Post.new(id: 12, title: 'Our post')
+post.update_attributes(title: 'Our awesome post', featured: true) #=> PATCH https://www.example.com/posts/12.json
+
+# provide the `id` of the resource as argument
+Post.destroy(12) #=> DELETE https://www.example.com/posts/12.json
+
+# provide the `id` on the resource
+post = Post.new(id: 12)
+post.destroy #=> DELETE https://www.example.com/posts/12.json
+```
 
-* `.extra_headers`: This sets the extra headers which are merged with the `.default_headers` and should be used for the request. *note: you can't set the `.default_headers`*
-    * *Default:* `.default_headers`: `{ "Content-Type" => "application/json" }`
-    * *Example:* `.extra_headers = { "X-Locale" => "en" }`
-    * `.headers`: `{ "Content-Type" => "application/json", "X-Locale" => "en" }`
-* `.content_type`: This sets the content-type which should be used for the request URL. *note: this is appended to the `base_url`*
-    * *Default:* `".json"`
-    * *`base_url`:* `https://www.myapp.com/contact_person`
-    * *Example:* `.content-type = ".json"`
-    * *Request URL:* `https://www.myapp.com/contact_person.json`
+### Connection options
+You can provide some options to alter the request. The options can be given as the first or second argument when making a request.
 
-#### Body and params options
+```ruby
+connection_options = { root_element: :data, headers: { "X-Locale" => "nl" } }
 
-Last but not least, you can pack the request body or params in a `root_element`:
+Post.find(12, connection_options)
 
-* `.root_element`: This sets the `root_element` in which the request body or params should be 'packed' for the request.
-    * *Params:* `{ email_address: "foo@bar.com", phone_number: "0031701234567" }`
-    * *Example:* `.root_element = :contact_person`
-    * *Packed params:* `{ "contact_person" => { email_address: "foo@bar.com", phone_number: "0031701234567" } }`
+Post.all(connection_options)
 
+Post.create({ title:'Our awesome post', featured: true }, connection_options)
 
-### Querying
+post          = Post.new(id: 12)
+post.title    = 'Our awesome post'
+post.featured = true
+post.save(connection_options)
+```
 
-#### Finder methods
+#### REST methods
 
-You can use the `.find`, `.find_by` and `.all` class methods:
+You can make custom requests by using the REST methods directly. The following REST methods are defined: the `.get`, `.put`, `.patch` and `.post` class methods or the `#get`, `#put`, `#patch` and `#post` instance methods.
 
 ```ruby
-# use the `id` as argument
-ContactPerson.find(12)
+Post.post(title: 'Our awesome post', featured: true) #=> RemoteResource::Response
+```
 
-# use a conditions `Hash` as argument
-ContactPerson.find_by(username: 'foobar')
+### Connection options
 
-# just the whole collection
-ContactPerson.all
-```
+You can provide some connection options to alter the request. The options can be defined on serveral ways:
+- On the `RemoteResource` enabled class
+- In the `.with_connection_options` block
+- Directly as the first or second argument when making a request.
 
-To override the given `options`, you can pass in a `connection_options` hash:
 
-```ruby
-connection_options: { root_element: :contact_person, headers: { "X-Locale" => "nl" } }
+#### URL options
 
-# use the `id` as argument
-ContactPerson.find(12, connection_options)
+There are several connection options that can alter the request URL. Normally the request URL is constructed using the `.site` and the relative class name of the `RemoteResource` enabled class. You can find this request URL by calling `.base_url` on the `RemoteResource` enabled class:
 
-# use a conditions `Hash` as argument
-ContactPerson.find_by((username: 'foobar'), connection_options)
+```ruby
+Post.base_url #=> https://www.example.com/posts
 ```
 
-#### Persistence methods
+We will use the `Post` class for these examples:
 
-You can use the `.create` class method and the `#save` instance method:
+* `.site`: This sets the host which should be used to construct the `base_url`.
+    * *Example:* `.site = 'https://api.myapp.com'`
+    * `Post.base_url #=> https://api.myapp.com/posts`
+* `.version`: This sets the API version for the path, after the `.site` and before the `.path_prefix` that is used to construct the `base_url`.
+    * *Example:* `.version = '/api/v2'`
+    * `Post.base_url #=> https://www.example.com/api/v2/posts`
+* `.path_prefix`: This sets the prefix for the path, after the `.version` and before the `.collection_name` that is used to construct the `base_url`.
+    * *Example:* `.path_prefix = '/registration'`
+    * `Post.base_url #=> https://www.example.com/registration/posts`
+* `.path_postfix`: This sets the postfix for the path, after the `.collection_name` that is used to construct the `base_url`.
+    * *Example:* `.path_postfix = '/new'`
+    * `Post.base_url #=> https://www.example.com/posts/new`
+* `.collection`: This toggles the pluralization of the `collection_name` that is used to construct the `base_url`.
+    * *Default:* `false`, but will be `true` in future versions
+    * *Example:* `.collection = false`
+    * `Post.base_url #=> https://www.example.com/post`
+* `.collection_prefix`: This sets the prefix for the collection, before `collection_name` that is used to construct the `base_url`. The prefix variable has to be set via connection_options' key `collection_options`.
+    * *Example:* `.collection_prefix = '/companies/:company_id'`
+    * `Post.base_url #=> https://www.example.com/companies/:company_id/posts`
+    * `Post.base_url(collection_options: { company_id: 2 }) #=> https://www.example.com/companies/2/posts`
+* `.collection_name`: This sets the `collection_name` that is used to construct the `base_url`.
+    * *Example:* `.collection_name = 'company'`
+    * `Post.base_url #=> https://www.example.com/company`
 
 
-```ruby
-# .create
-ContactPerson.create(username: 'aapmies', first_name: 'Mies')
+#### Request options
 
-# #save
-contact_person = ContactPerson.new(id: 12)
-contact_person.username = 'aapmies'
-contact_person.save
-```
-To override the given `options`, you can pass in a `connection_options` hash:
+Apart from the options which manipulate the request URL, there are also options to alter the request:
 
-```ruby
-connection_options: { root_element: :contact_person, headers: { "X-Locale" => "nl" } }
+* `.default_headers`: This sets the default headers.
+    * *Default:* `{ "Accept" => "application/json", "User-Agent" => "RemoteResource <version>" }`
+    * *Example:* `.headers = { "User-Agent" => "My App" }`
+    * `{ "User-Agent" => "My App" }`
+* `.headers`: This sets the headers which are merged with the default headers.
+    * *Default:* `{ "Accept" => "application/json", "User-Agent" => "RemoteResource <version>" }`
+    * *Example:* `.headers = { "X-Locale" => "en" }`
+    * `{ "Accept" => "application/json", "User-Agent" => "RemoteResource <version>", "X-Locale" => "en" }`
 
-contact_person = ContactPerson.new(id: 12)
-contact_person.username = 'aapmies'
-contact_person.save(connection_options)
-```
 
-#### REST methods
+#### Body options
 
-You can use the `.get`, `.put`, `.patch` and `.post` class methods  and the `
-#get`, `#put`, `#patch` and `#post` instance methods.
+Some API wrap the resource within a specific element, we call this element the root element. When a root element is given as option the attributes in the request body will be wrapped in the element and the attributes of the response will be unwrapped from the element.
 
+* `.root_element`: This sets the element in which the body is wrapped.
+    * *Example:* `.root_element = :data`
+    * `{"data":{"title":"My awesome post", "featured":true}}`
 
-#### With a `connection_options` block
+#### Using the `.with_connection_options` block
 
-You can make your requests in a `connection_options` block. All the requests in the block will use the passed in `connection_options`.
+You can make your requests in a `.with_connection_options` block. All the requests in the block will use the passed in connection options.
 
 ```ruby
-ContactPerson.with_connection_options(headers: { "X-Locale" => "en" }) do
-  ContactPerson.find_by(username: 'foobar')
-  ContactPerson.find_by(username: 'aapmies', (content-type: '.xml'))
-  ContactPerson.find_by((username: 'viking'), (headers: { "X-Locale" => "nl" }))
+Post.with_connection_options(headers: { "X-Locale" => "en" }) do
+  Post.find(12)
+  Post.where({ featured: true }, { version: '/api/v2' })
+  Post.all({ collection_prefix: '/companies/:company_id', collection_options: { company_id: 10 })
 end
 ```
 
-This will result in two request which use the `{ headers: { "X-Locale" => "en" } }` as `connection_options`, one which will use the `{ headers: { "X-Locale" => "nl" } }` as `connection_options`. And one that will append `.xml` to the request URL.
-
-### Responses
-
-The response body of the request will be 'unpacked' from the `root_element` if necessary and parsed. The resulting `Hash` will be used to assign the attributes of the resource.
-
-However if you want to access the response of the request, you can use the `#_response` method. This returns a `RemoteResource::Response` object with the `#response_body` and `#response_code` methods.
+### Debug methods
 
+The last request and response of the resource is set on the resource. You can use this to debug your implementation.
 
 ```ruby
-contact_person = ContactPerson.find_by((username: 'foobar'), connection_options)
-contact_person._response                 #=> RemoteResource::Response
-contact_person._response.response_code   #=> 200
-contact_person._response.response_body   #=> '{"username":"foobar", "name":"Foo", "surname":"Bar"}'
+post = Post.find(12)
+post.last_request   #=> RemoteResource::Request
+post.last_response  #=> RemoteResource::Response
 ```
-
-

data/lib/remote_resource/base.rb

@@ -19,11 +19,12 @@ module RemoteResource
       include RemoteResource::Querying::FinderMethods
       include RemoteResource::Querying::PersistenceMethods
 
-      attr_accessor :_response
+      attr_accessor :last_request, :last_response, :meta
       attr_accessor :destroyed
 
-      attribute :id
       class_attribute :root_element, instance_accessor: false
+
+      attribute :id
     end
 
     def self.global_headers=(headers)
@@ -85,7 +86,7 @@ module RemoteResource
     end
 
     def success?
-      _response.success? && !errors?
+      last_response.success? && !errors?
     end
 
     def errors?
@@ -94,20 +95,19 @@ module RemoteResource
 
     def handle_response(response)
       if response.unprocessable_entity?
-        rebuild_resource_from_response(response).tap do |resource|
-          resource.assign_errors_from_response response
-        end
+        rebuild_resource_from_response(response)
+        assign_errors_from_response(response)
       else
         rebuild_resource_from_response(response)
-      end
+      end and self
     end
 
-    def assign_response(response)
-      @_response = response
+    def assign_errors_from_response(response)
+      assign_errors(response.errors)
     end
 
-    def assign_errors_from_response(response)
-      assign_errors response.error_messages_response_body
+    def _response
+      warn '[DEPRECATION] `._response` is deprecated. Please use `.last_response` instead.'
     end
 
     private

data/lib/remote_resource/builder.rb

@@ -5,49 +5,37 @@ module RemoteResource
     module ClassMethods
 
       def build_resource_from_response(response)
-        build_resource response.sanitized_response_body, response_hash(response)
+        build_resource(response.attributes, { last_request: response.request, last_response: response, meta: response.meta })
       end
 
-      def build_resource(collection, response_hash = {})
-        if collection.is_a? Hash
-          new collection.merge response_hash
+      def build_resource(collection, options = {})
+        if collection.is_a?(Hash)
+          new(collection.merge(options))
         end
       end
 
       def build_collection_from_response(response)
-        build_collection response.sanitized_response_body, response_hash(response)
+        build_collection(response.attributes, { last_request: response.request, last_response: response, meta: response.meta })
       end
 
-      def build_collection(collection, response_hash = {})
-        if collection.is_a? Array
-          RemoteResource::Collection.new self, collection, response_hash
+      def build_collection(collection, options = {})
+        if collection.is_a?(Array)
+          RemoteResource::Collection.new(self, collection, options)
         end
       end
-
-      private
-
-      def response_hash(response_object)
-        { _response: response_object, meta: response_object.sanitized_response_meta }
-      end
     end
 
     def rebuild_resource_from_response(response)
-      rebuild_resource response.sanitized_response_body, response_hash(response)
+      rebuild_resource(response.attributes, { last_request: response.request, last_response: response, meta: response.meta })
     end
 
-    def rebuild_resource(collection, response_hash = {})
-      if collection.is_a? Hash
-        self.attributes = collection.merge(response_hash)
+    def rebuild_resource(collection, options = {})
+      if collection.is_a?(Hash)
+        self.attributes = collection.merge(options)
       else
-        self.attributes = response_hash
+        self.attributes = options
       end and self
     end
 
-    private
-
-    def response_hash(response_object)
-      self.class.send :response_hash, response_object
-    end
-
   end
 end

data/lib/remote_resource/collection.rb

@@ -2,27 +2,26 @@ module RemoteResource
   class Collection
     include Enumerable
 
-    delegate :[], :at, :reverse, :size, to: :to_a
+    attr_reader :resource_klass, :resources_collection
+    attr_accessor :last_request, :last_response, :meta
 
-    attr_reader :resource_klass, :resources_collection, :meta, :_response
+    delegate :[], :at, :reverse, :size, to: :to_a
 
-    def initialize(resource_klass, resources_collection, response_hash)
+    def initialize(resource_klass, resources_collection, options = {})
       @resource_klass       = resource_klass
       @resources_collection = resources_collection
-      @response_hash        = response_hash
-      @meta                 = response_hash[:meta] || {}
-      @_response            = response_hash[:_response]
+      @options              = options
     end
 
     def each(&block)
-      if resources_collection.is_a? Array
+      if resources_collection.is_a?(Array)
         if defined?(@collection)
           @collection.each(&block)
         else
           @collection = []
           resources_collection.each do |element|
-            record = resource_klass.new element.merge(@response_hash)
-            @collection << record
+            record = resource_klass.new(element.merge(@options))
+            @collection.push(record)
             yield(record)
           end
         end
@@ -34,7 +33,23 @@ module RemoteResource
     end
 
     def success?
-      _response.success?
+      last_response.success?
+    end
+
+    def last_request
+      @last_request ||= @options[:last_request]
+    end
+
+    def last_response
+      @last_response ||= @options[:last_response]
+    end
+
+    def meta
+      @meta ||= @options[:meta]
+    end
+
+    def _response
+      warn '[DEPRECATION] `._response` is deprecated. Please use `.last_response` instead.'
     end
 
   end

data/lib/remote_resource/request.rb

@@ -42,7 +42,7 @@ module RemoteResource
       SUPPORTED_HTTP_METHODS.include?(http_action) || raise(RemoteResource::HTTPMethodUnsupported, "Requested HTTP method=#{http_action.to_s} is NOT supported, the HTTP action MUST be a supported HTTP action=#{SUPPORTED_HTTP_METHODS.join(', ')}")
 
       connection_response = connection.public_send(http_action, request_url, params: query, body: body, headers: headers)
-      response            = RemoteResource::Response.new(connection_response, connection_options)
+      response            = RemoteResource::Response.new(connection_response, connection_options.merge(request: self, connection_request: connection_response.request))
 
       if response.success? || response.unprocessable_entity?
         response

data/lib/remote_resource/response.rb

@@ -1,81 +1,63 @@
 module RemoteResource
   class Response
 
-    attr_reader :original_response, :original_request
-    private :original_response, :original_request
+    def initialize(connection_response, connection_options = {})
+      @connection_response = connection_response
+      @connection_request  = connection_options[:connection_request]
+      @request             = connection_options[:request]
+      @connection_options  = connection_options
+    end
 
-    def initialize(response, connection_options = {})
-      @original_response  = response
-      @original_request   = response.request
-      @connection_options = connection_options
+    def request
+      @request
     end
 
     def success?
-      original_response.success?
+      @connection_response.success?
     end
 
     def unprocessable_entity?
       response_code == 422
     end
 
-    def response_body
-      original_response.body
-    end
-
     def response_code
-      original_response.response_code
+      @response_code ||= @connection_response.response_code
     end
 
-    def response_headers
-      original_response.headers
+    def headers
+      @headers ||= @connection_response.headers
     end
 
-    def sanitized_response_body
-      return empty_hash if response_body.blank?
-      return empty_hash if parsed_response_body.blank?
-
-      unpacked_parsed_response_body
+    def body
+      @body ||= @connection_response.body
     end
 
-    def sanitized_response_meta
-      return empty_hash if response_body.blank?
-      return empty_hash if parsed_response_body.blank?
-
-      return parsed_response_body['meta'] if parsed_response_body.try :has_key?, 'meta'
-
-      empty_hash
+    def parsed_body
+      @parsed_body ||= begin
+        JSON.parse(body.to_s)
+      rescue JSON::ParserError
+        {}
+      end
     end
 
-    def error_messages_response_body
-      return empty_hash if response_body.blank?
-      return empty_hash if parsed_response_body.blank?
+    def attributes
+      @attributes ||= begin
+        root_element = @connection_options[:root_element]
 
-      return parsed_response_body["errors"]          if parsed_response_body.try :has_key?, "errors"
-      return unpacked_parsed_response_body["errors"] if unpacked_parsed_response_body.try :has_key?, "errors"
-
-      empty_hash
+        if root_element.present?
+          parsed_body[root_element.to_s]
+        else
+          parsed_body
+        end.presence || {}
+      end
     end
 
-    def parsed_response_body
-      @parsed_response_body ||= JSON.parse response_body
-    rescue JSON::ParserError
-      nil
+    def errors
+      @errors ||= parsed_body['errors'].presence || attributes['errors'].presence || {}
     end
 
-    private
-
-    def empty_hash
-      {}
-    end
-
-    def unpacked_parsed_response_body
-      root_element = @connection_options[:root_element].presence
-
-      if root_element
-        parsed_response_body[root_element.to_s]
-      else
-        parsed_response_body
-      end
+    def meta
+      @meta ||= parsed_body['meta'].presence || {}
     end
 
   end

data/lib/remote_resource/version.rb

@@ -1,3 +1,3 @@
 module RemoteResource
-  VERSION = '1.0.0.rc2'.freeze
+  VERSION = '1.0.0.rc3'.freeze
 end