excon-hypermedia 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6c0a3189fb4185c1db3c29a86b699ea1de7549db
-  data.tar.gz: b4d04af297a0ea267d0a2dce0765385bfd5d8483
+  metadata.gz: 38a442095c082e7251b1a72d8e88084833357a3d
+  data.tar.gz: f0ff7d16042fa3d35bfca84b216b6e145f55db2d
 SHA512:
-  metadata.gz: f7576259b25677acc8f9b23171705babafff2bd0510c055723bee712e1f77a329355b090be9544631aabdd199c0e4c068f0818765ffcf1c4abdd5f03a94b004a
-  data.tar.gz: eb29ba745ea6cf03434f3232fd459e7e9bf3db791fba56fc88772e95a10800510f54e5c793e8771df9b77bae240522fd024b305f8bbf5186236d7a0681c815fd
+  metadata.gz: 6ce27164e467d58bd426538b59cb917761c246d36dcb744d43e807169415ca225280cbd9965d41a631c907b2abeed49794090e3800a78e51a05b2f0811f781f1
+  data.tar.gz: 4670c0806fa665a012b0238598cc724296e5252b79735f116954aba80649b116773560d07aeebad932cbfd0f39550bd1a21248376d2ab25ccc6f49f1615fdf9e

data/README.md

@@ -2,6 +2,16 @@
 
 Teaches [Excon][] how to talk to [HyperMedia APIs][hypermedia].
 
+* [Installation](#installation)
+* [Quick Start](#quick-start)
+* [Usage](#usage)
+  * [resources](#resources)
+  * [links](#links)
+  * [relations](#relations)
+  * [properties](#properties)
+  * [embedded](#embedded)
+* [License](#license)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -22,6 +32,22 @@ Or install it yourself as:
 gem install excon-hypermedia
 ```
 
+## Quick Start
+
+```ruby
+Excon.defaults[:middlewares].push(Excon::HyperMedia::Middleware)
+
+api = Excon.get('https://www.example.org/api.json')
+api.class # => Excon::Response
+
+product = api.rel('product', expand: { uid: 'bicycle' })
+product.class # => Excon::Connection
+
+response = product.get
+response.class # => Excon::Response
+response.resource.name # => 'bicycle'
+```
+
 ## Usage
 
 To let Excon know the API supports HyperMedia, simply enable the correct
@@ -34,65 +60,202 @@ api = Excon.get('https://www.example.org/api.json')
 api.class # => Excon::Response
 ```
 
-Using the `HyperMedia` middleware, the `Excon::Response` object now knows how
-to handle the HyperMedia aspect of the API:
+> NOTE: we'll use the following JSON response body in the below examples:
+> 
+> **https://www.example.org/api.json**
+> 
+> ```json
+> {
+>   "_links": {
+>     "self": {
+>       "href": "https://www.example.org/api.json"
+>     },
+>     "product": {
+>       "href": "https://www.example.org/product/{uid}",
+>       "templated": true
+>     }
+>   }
+> }
+> ```
+> 
+> **https://www.example.org/product/bicycle**
+> 
+> ```json
+> {
+>   "_links": {
+>     "self": {
+>       "href": "https://www.example.org/product/bicycle"
+>     }
+>   },
+>   "bike-type": "Mountain Bike",
+>   "BMX": false,
+>   "derailleurs": {
+>     "back": 7,
+>     "front": 3
+>   },
+>   "name": "bicycle",
+>   "reflectors": true,
+>   "_embedded": {
+>     "pump": {
+>       "_links": {
+>         "self": "https://www.example.org/product/pump"
+>       },
+>       "weight": "2kg",
+>       "type": "Floor Pump",
+>       "valve-type": "Presta"
+>     }
+>   }
+> }
+
+With this middleware injected in the stack, Excon's model is now expanded with
+several key concepts:
+
+### resources
+
+A **resource** is the representation of the object returned by the API. Almost
+all other concepts and methods originate from this object.
+
+Use the newly available `Excon::Response#resource` method to access the resource
+object:
 
 ```ruby
-product = api.product(expand: { uid: 'bicycle' })
-product.class # => Excon::Connection
+api.resource.class # => Excon::HyperMedia::ResourceObject
+```
 
-response = product.get
-response.class # => Excon::Response
-response.body.class # => String
+A resource has several methods exposed:
+
+```ruby
+api.resource.public_methods(false) # => [:_links, :_properties, :_embedded]
+```
+
+Each of these methods represents one of the following HyperMedia concepts.
+
+### links
+
+A resource has links, that point to related resources (and itself), these can be
+accessed as well:
+
+```ruby
+api.resource._links.class # => Excon::HyperMedia::ResourceObject::Links
+```
+
+You can get a list of valid links using `keys`:
+
+```ruby
+api.resource._links.keys # => ['self', 'product']
+```
+
+Each links is represented by a `LinkObject` instance:
+
+```ruby
+api.resource._links.product.class # => Excon::HyperMedia::LinkObject
+api.resource._links.product.href # => 'https://www.example.org/product/{uid}'
+api.resource._links.product.templated # => true
+```
+
+### relations
+
+Links are the primary way to traverse between relations. This is what makes a
+HyperMedia-based API "self-discoverable".
+
+To go from one resource, to the next, you use the `rel` (short for relation)
+method. This method is available on any `LinkObject` instance.
+
+Using `rel`, returns an `Excon::Connection` object, the same as if you where to
+call `Excon.new`:
+
+```ruby
+relation = api.resource._links.self.rel
+relation.class # => Excon::Connection
+```
+
+Since the returned object is of type `Excon::Connection`, all
+[Excon-provided options][options] are available as well:
+
+```ruby
+relation.get(idempotent: true, retry_limit: 6)
+```
+
+`Excon::Response` also has a convenient delegation to `LinkObject#rel`:
+
+```ruby
+relation = api.rel('self').get
+```
+
+Once you call `get` (or `post`, or any other valid Excon request method), you
+are back where you started, with a new `Excon::Response` object, imbued with
+HyperMedia powers:
+
+```ruby
+relation.resource._links.keys # => ['self', 'product']
+```
+
+In this case, we ended up back with the same type of object as before. To go
+anywhere meaningful, we want to use the `product` rel:
+
+```ruby
+product = api.rel('product', expand: { uid: 'bicycle' }).get
 ```
 
 As seen above, you can expand URI Template variables using the `expand` option,
 provided by the [`excon-addressable` library][excon-addressable].
 
-Since each new resource is simply an `Excon::Response` object, accessed through
-the default `Excon::Connection` object, all [Excon-provided options][options]
-are available as well:
+### properties
+
+Properties are what make a resource unique, they tell us more about the state of
+the resource, they are the key/value pairs that define the resource.
+
+In HAL/JSON terms, this is everything returned by the response body, excluding
+the `_links` and `_embedded` sections:
 
 ```ruby
-product.get(idempotent: true, retry_limit: 6)
+product.resource.name # => "bicycle"
+product.resource.reflectors # => true
 ```
 
-### Links
-
-You can access all links in a resource using the `links` method:
+Nested properties are supported as well:
 
 ```ruby
-api.links.first.class # => Excon::HyperMedia::Link
-api.links.first.name  # => 'product'
-api.links.first.href  # => 'https://www.example.org/product/{uid}'
+product.resource.derailleurs.class # => Excon::HyperMedia::ResourceObject::Properties
+product.resource.derailleurs.front # => 3
+product.resource.derailleurs.back # => 7
 ```
 
-You can also access a link directly, using its name:
+Property names that aren't valid method names can always be accessed using the
+hash notation:
 
 ```ruby
-api.link('product').href # => 'https://www.example.org/product/{uid}'
+product.resource['bike-type'] # => 'Mountain Bike'
+product.resource['BMX'] # => false
+product.resource.bmx # => false
 ```
 
-If you want to access a relation through its link, but can't use the implicit
-naming, you can use the `rel` method:
+Properties should be implicitly accessed on a resource, but are internally
+accessed via the `_properties` method:
 
 ```ruby
-api.links.last.name # => 'customer-orders'
+product.resource._properties.class # => Excon::HyperMedia::ResourceObject::Properties
+```
 
-# won't work, due to invalid ruby method name:
-api.customer-orders(expand: { sort: 'desc' }) # => NoMethodError: undefined method `customer' 
+The `Properties` object inherits its logics from `Enumerable`:
 
-# works
-api.rel('customer-orders', expand: { sort: 'desc' })
+```ruby
+product.resource._properties.to_h.class # => Hash
+product.resource._properties.first # => ['name', 'bicycle']
 ```
 
-### Attributes
+### embedded
+
+Embedded resources are resources that are available through link relations, but
+embedded in the current resource for easier access.
+
+For more information on this concept, see the [formal specification][_embedded].
 
-Attributes are available through the `attributes` method:
+Embedded resources work the same as the top-level resource:
 
 ```ruby
-product.attributes.to_h # => { uid: 'bicycle', stock: 5 }
-product.attributes.uid  # => 'bicycle'
+product._embedded.pump.class # => Excon::HyperMedia::ResourceObject
+product._embedded.pump.weight # => '2kg'
 ```
 
 ## License
@@ -103,3 +266,4 @@ The gem is available as open source under the terms of the [MIT License](http://
 [hypermedia]: https://en.wikipedia.org/wiki/HATEOAS
 [excon-addressable]: https://github.com/JeanMertz/excon-addressable
 [options]: https://github.com/excon/excon#options
+[_embedded]: https://tools.ietf.org/html/draft-kelly-json-hal-08#section-4.1.2

data/lib/excon/hypermedia/ext/response.rb

@@ -9,6 +9,8 @@ module Excon
       # on top.
       #
       module Response
+        private
+
         def method_missing(method_name, *params)
           hypermedia_response.handle(method_name, *params) || super
         end

data/lib/excon/hypermedia/helpers/collection.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Excon
+  module HyperMedia
+    # Collection
+    #
+    # Given a `Hash`, provides dot-notation properties and other helper methods.
+    #
+    module Collection
+      include Enumerable
+
+      def initialize(collection = {})
+        @collection ||= collection
+        to_properties
+      end
+
+      def each(&block)
+        collection.each(&block)
+      end
+
+      def keys
+        @collection.keys
+      end
+
+      def key?(key)
+        collection.key?(key.to_s)
+      end
+
+      def [](key)
+        to_property(key)
+      end
+
+      private
+
+      def to_properties
+        collection.each do |key, value|
+          key = key.downcase
+          next unless /[@$"]/ !~ key.to_sym.inspect
+
+          singleton_class.class_eval { attr_reader key }
+          instance_variable_set("@#{key}", property(value))
+        end
+      end
+
+      def property(value)
+        value.respond_to?(:keys) ? self.class.new(value) : value
+      end
+
+      def to_property(key)
+        key?(key) ? property(collection[key]) : nil
+      end
+
+      def to_property!(key)
+        key?(key) ? to_property(key) : method_missing(key)
+      end
+
+      attr_reader :collection
+    end
+  end
+end

data/lib/excon/hypermedia/link_object.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Excon
+  module HyperMedia
+    # Link
+    #
+    # Encapsulates a link pointing to a resource.
+    #
+    # @see https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5
+    #
+    class LinkObject
+      include Collection
+
+      # href
+      #
+      # The "href" property is REQUIRED.
+      #
+      # Its value is either a URI [RFC3986] or a URI Template [RFC6570].
+      #
+      # If the value is a URI Template then the Link Object SHOULD have a
+      # "templated" attribute whose value is true.
+      #
+      # @see https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5.1
+      #
+      def href
+        to_property!(:href)
+      end
+
+      # The "templated" property is OPTIONAL.
+      #
+      # Its value is boolean and SHOULD be true when the Link Object's "href"
+      # property is a URI Template.
+      #
+      # Its value SHOULD be considered false if it is undefined or any other
+      # value than true.
+      #
+      # @see: https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5.2
+      #
+      def templated
+        to_property(__method__) || false
+      end
+
+      # type
+      #
+      # The "type" property is OPTIONAL.
+      #
+      # Its value is a string used as a hint to indicate the media type
+      # expected when dereferencing the target resource.
+      #
+      # @see: https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5.3
+      #
+      def type
+        to_property!(__method__)
+      end
+
+      # deprecation
+      #
+      # The "deprecation" property is OPTIONAL.
+      #
+      # Its presence indicates that the link is to be deprecated (i.e.
+      # removed) at a future date.  Its value is a URL that SHOULD provide
+      # further information about the deprecation.
+      #
+      # A client SHOULD provide some notification (for example, by logging a
+      # warning message) whenever it traverses over a link that has this
+      # property.  The notification SHOULD include the deprecation property's
+      # value so that a client manitainer can easily find information about
+      # the deprecation.
+      #
+      # @see https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5.4
+      #
+      def deprecation
+        to_property!(__method__)
+      end
+
+      # name
+      #
+      # The "name" property is OPTIONAL.
+      #
+      # Its value MAY be used as a secondary key for selecting Link Objects
+      # which share the same relation type.
+      #
+      # @see https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5.5
+      #
+      def name
+        to_property!(__method__)
+      end
+
+      # profile
+      #
+      # The "profile" property is OPTIONAL.
+      #
+      # Its value is a string which is a URI that hints about the profile (as
+      # defined by [I-D.wilde-profile-link]) of the target resource.
+      #
+      # @see https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5.6
+      #
+      def profile
+        to_property!(__method__)
+      end
+
+      # title
+      #
+      # The "title" property is OPTIONAL.
+      #
+      # Its value is a string and is intended for labelling the link with a
+      # human-readable identifier (as defined by [RFC5988]).
+      #
+      # @see https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5.7
+      #
+      def title
+        to_property!(__method__)
+      end
+
+      # hreflang
+      #
+      # The "hreflang" property is OPTIONAL.
+      #
+      # Its value is a string and is intended for indicating the language of
+      # the target resource (as defined by [RFC5988]).
+      #
+      # @see https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5.8
+      #
+      def hreflang
+        to_property!(__method__)
+      end
+
+      # uri
+      #
+      # Returns a URI representation of the provided "href" property.
+      #
+      # @return [URI] URI object of the "href" property
+      #
+      def uri
+        ::Addressable::URI.parse(href)
+      end
+
+      # rel
+      #
+      # Returns an `Excon::Connection` instance, based on the current link.
+      #
+      # @return [Excon::Connection] Connection object based on current link
+      #
+      def rel(params = {})
+        Excon.new(href, params)
+      end
+
+      private def property(value)
+        value
+      end
+    end
+  end
+end

data/lib/excon/hypermedia/middleware.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+Excon.defaults[:middlewares].delete(Excon::Addressable::Middleware)
 Excon.defaults[:middlewares].unshift(Excon::Addressable::Middleware)
 
 module Excon
@@ -16,6 +17,7 @@ module Excon
       def request_call(datum)
         return super unless (content_type = datum.dig(:response, :headers, 'Content-Type').to_s)
 
+        datum[:response] ||= {}
         datum[:response][:hypermedia] = if datum[:hypermedia].nil?
           content_type.include?('hal+json')
         else

data/lib/excon/hypermedia/resource_object/embedded.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Excon
+  module HyperMedia
+    class ResourceObject
+      # Links
+      #
+      # Represents a collection of links part of a resource.
+      #
+      class Embedded
+        include Collection
+
+        private def property(value)
+          if value.respond_to?(:to_ary)
+            value.map { |v| ResourceObject.new(v) }
+          else
+            ResourceObject.new(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/excon/hypermedia/resource_object/links.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Excon
+  module HyperMedia
+    class ResourceObject
+      # Links
+      #
+      # Represents a collection of links part of a resource.
+      #
+      class Links
+        include Collection
+
+        private def property(value)
+          value.respond_to?(:to_ary) ? value.map { |v| LinkObject.new(v) } : LinkObject.new(value)
+        end
+      end
+    end
+  end
+end

data/lib/excon/hypermedia/resource_object/properties.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Excon
+  module HyperMedia
+    class ResourceObject
+      # Properties
+      #
+      # Provides consistent access to resource properties.
+      #
+      class Properties
+        include Collection
+      end
+    end
+  end
+end

data/lib/excon/hypermedia/resource_object.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'excon/hypermedia/resource_object/embedded'
+require 'excon/hypermedia/resource_object/links'
+require 'excon/hypermedia/resource_object/properties'
+
+module Excon
+  module HyperMedia
+    # ResourceObject
+    #
+    # Represents a resource.
+    #
+    class ResourceObject
+      RESERVED_PROPERTIES = %w(_links _embedded).freeze
+
+      def initialize(data)
+        @data = data
+
+        _properties.each do |key, value|
+          key = key.downcase
+          next unless /[@$"]/ !~ key.to_sym.inspect
+
+          singleton_class.class_eval { attr_reader key }
+          instance_variable_set("@#{key}", value.respond_to?(:keys) ? Properties.new(value) : value)
+        end
+      end
+
+      def _properties
+        @_properties ||= Properties.new(@data.reject { |k, _| RESERVED_PROPERTIES.include?(k) })
+      end
+
+      # _links
+      #
+      # The reserved "_links" property is OPTIONAL.
+      #
+      # It is an object whose property names are link relation types (as
+      # defined by [RFC5988]) and values are either a Link Object or an array
+      # of Link Objects.  The subject resource of these links is the Resource
+      # Object of which the containing "_links" object is a property.
+      #
+      # @see https://tools.ietf.org/html/draft-kelly-json-hal-08#section-4.1.1
+      #
+      def _links
+        @_links ||= Links.new(@data['_links'])
+      end
+
+      # _embedded
+      #
+      # The reserved "_embedded" property is OPTIONAL
+      #
+      # It is an object whose property names are link relation types (as
+      # defined by [RFC5988]) and values are either a Resource Object or an
+      # array of Resource Objects.
+      #
+      # Embedded Resources MAY be a full, partial, or inconsistent version of
+      # the representation served from the target URI.
+      #
+      # @see https://tools.ietf.org/html/draft-kelly-json-hal-08#section-4.1.2
+      #
+      def _embedded
+        @_embedded ||= Embedded.new(@data['_embedded'])
+      end
+
+      def [](key)
+        _properties[key]
+      end
+    end
+  end
+end