Improve error message when server returns invalid data

As discussed in #121, the error message you get when a web server
returns non-json hal data or the Content-Type is incorrect is rather
unclear on what happened.

This commit adds a check when creating a Resource that the received
representation is something that makes sense.

This turns the error message for an example such as
`Hyperclient.new('http://www.google.com/').foo` from

```
/lib/hyperclient/collection.rb:78:in `method_missing': undefined method
`fetch' for #<String:0x005654b3898628> (NoMethodError)
        from /lib/hyperclient/resource.rb:87:in `block in method_missing'
        from /lib/hyperclient/resource.rb:85:in `each'
        from /lib/hyperclient/resource.rb:85:in `method_missing'
        from /lib/hyperclient/link.rb:129:in `method_missing'
        from example.rb:3:in `<main>'
```

to

```
/lib/hyperclient/resource.rb:90:in `validate': Invalid representation
for resource (got String, expected Hash). Is your web server returning
JSON HAL data with a 'Content-Type: application/hal+json' header?
(Hyperclient::InvalidRepresentationError)
        from /lib/hyperclient/resource.rb:43:in `initialize'
        from /lib/hyperclient/link.rb:179:in `new'
        from /lib/hyperclient/link.rb:179:in `http_method'
        from /lib/hyperclient/link.rb:89:in `_get'
        from /lib/hyperclient/link.rb:84:in `_resource'
        from /lib/hyperclient/link.rb:128:in `method_missing'
        from example.rb:3:in `<main>'
```

e.g. we now validate immediately after the request, and provide
meaningful information and even a hint towards the possibly-missing
header.

Author: ivoanjo

features/steps/default_config.rb

@@ -12,7 +12,7 @@ class Spinach::Features::DefaultConfig < Spinach::FeatureSteps
   end
 
   step 'I send some data to the API' do
-    stub_request(:post, 'http://api.example.org/posts')
+    stub_request(:post, 'http://api.example.org/posts').to_return(headers: { 'Content-Type' => 'application/hal+json' })
     assert_equal 200, api._links.posts._post(title: 'My first blog post')._response.status
   end
 

lib/hyperclient/resource.rb

@@ -1,6 +1,17 @@
 require 'forwardable'
 
 module Hyperclient
+  # Public: Exception that is raised when passing in invalid representation data
+  # for the resource.
+  class InvalidRepresentationError < ArgumentError
+    attr_reader :representation
+
+    def initialize(error_description, representation)
+      super(error_description)
+      @representation = representation
+    end
+  end
+
   # Public: Represents a resource from your API. Its responsability is to
   # ease the way you access its  attributes, links and embedded resources.
   class Resource
@@ -29,8 +40,9 @@ class Resource
     # representation - The hash with the HAL representation of the Resource.
     # entry_point    - The EntryPoint object to inject the configutation.
     def initialize(representation, entry_point, response = nil)
-      representation = representation ? representation.dup : {}
+      representation = validate(representation)
       links = representation['_links'] || {}
+
       @_links       = LinkCollection.new(links, links['curies'], entry_point)
       @_embedded    = ResourceCollection.new(representation['_embedded'], entry_point)
       @_attributes  = Attributes.new(representation)
@@ -68,6 +80,21 @@ def fetch(key, *args)
 
     private
 
+    # Internal: Ensures the received representation is a valid Hash-lookalike.
+    def validate(representation)
+      return {} unless representation
+
+      if representation.respond_to?(:to_hash)
+        representation.to_hash.dup
+      else
+        raise InvalidRepresentationError.new(
+          "Invalid representation for resource (got #{representation.class}, expected Hash). " \
+          "Is your web server returning JSON HAL data with a 'Content-Type: application/hal+json' header?",
+          representation
+        )
+      end
+    end
+
     # Internal: Returns the self Link of the Resource. Used to handle the HTTP
     # methods.
     def _self_link

test/hyperclient/resource_test.rb

@@ -40,6 +40,12 @@ module Hyperclient
 
         resource._response.body.must_equal body
       end
+
+      describe 'with an invalid representation' do
+        it 'raises an InvalidRepresentationError' do
+          proc { Resource.new('invalid representation data', entry_point) }.must_raise InvalidRepresentationError
+        end
+      end
     end
 
     describe '_links' do