hal-client 1.1.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a22811cd4e0f71ae8fe9767f40314c6c070a603b
-  data.tar.gz: de7b7a1b94bc47dd3a1da179d2241ce85e337eb0
+  metadata.gz: 2feba4ea1ae2adc4762239ce875c4d4db3dad541
+  data.tar.gz: d0854b133f4ca25cb6ee21d10e2e7ba8e87d1480
 SHA512:
-  metadata.gz: 6d75d90c76548319814b03a18d7c8518609ef4911325d59c686a4ad63f5aba75933254fd70b850d05bb7b008504f5a8245a650841bc34046d99fb051aef048d8
-  data.tar.gz: 9cf40c295ddc43e1083a45e67c74a75fb901ebe793bfb0a097acbcd9f93fc5d4bfc74b50037e5a3750b890b3254780df2141776a27ec449a94c1798004889f04
+  metadata.gz: 2ac5423a12091b050f6e27b93994b4a4914ab65a1702565b22ab724b45f73baa30a1896402ade0e62c024b1b2cbfacfde689143d41f9246d6900ddf6b723e4fa
+  data.tar.gz: be45454510e90beb073b2b9c8852e59718727ca91ff89cd1da6ef8ccb26d593b9d5a71d604fc02f7f2dad7453515340e8754dab217743bd79729763676ce52a9

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - "1.9.2"
+  - "1.9.3"
+  - "2.0.0"
+  - ruby-head
+  - jruby-19mode # JRuby in 1.9 mode

data/README.md

@@ -1,6 +1,9 @@
+[![Build Status](https://travis-ci.org/pezra/hal-client.png?branch=master)](https://travis-ci.org/pezra/hal-client)
+[![Code Climate](https://codeclimate.com/github/pezra/hal-client.png)](https://codeclimate.com/github/pezra/hal-client)
+
 # HalClient
 
-An easy to use interface for REST APIs that use [HAL](http://stateless.co/hal_specification.html).
+An easy to use client interface for REST APIs that use [HAL](http://stateless.co/hal_specification.html).
 
 ## Installation
 
@@ -16,21 +19,13 @@ Or install it yourself as:
 
     $ gem install hal-client
 
-## Usage
-
-The first step to using HalClient is to create a `HalClient` instance.
-
-    my_client = HalClient.new
-
-If the API uses one or more a custom mime types we can specify that they be included in the `Accept` header field of each request.
-
-    my_client = HalClient.new(accept: "application/vnd.myapp+hal+json")
-
-### `GET`ting an entry point
+Usage
+-----
 
-In normal usage you will rarely use the `HalClient` instance directly. Normally, you will traverse links on a representation which uses the `HalClient` indirectly. Getting API entry points is main use for the HalClient instance.
+The first step in using a HAL based API is getting a representation of one of its entry point. The simplest way to do this is using the `get` class method of `HalClient`.
 
-    blog = my_client.get("http://blog.me/")
+    blog = HalClient.get("http://blog.me/")
+    # => #<Representation: http://blog.me/>
 
 `HalClient::Representation`s expose a `#property` method to retrieve properties from the HAL document.
 
@@ -39,19 +34,36 @@ In normal usage you will rarely use the `HalClient` instance directly. Normally,
 
 ### Link navigation
 
-Once we have a representation we are going to need to navigate its links. This can be accomplished by using the `#related` method.
+Once we have a representation we will want to navigate its links. This can be accomplished using the `#related` method.
 
     articles = blog.related("item")
     # => #<RepresentationSet:...>
 
-In the example above `item` is the link rel. The `#related` method looks up both embedded representations and links with the rel of `item`. Links are then dereferenced using the same `HalClient` instance used to retrieve the entry point. The dereferenced links and extracted embedded representations are converted into individual `HalClient::Representation`s and packaged into a `HalClient::RepresentationSet`. `HalClient` always returns `RepresentationSet`s when following links, even when there is only one result as doing so tends to result in simpler client code.
+In the example above `item` is the link rel. The `#related` method extracts embedded representations and dereferences links with the specified rel. The resulting representations and packaged into a `HalClient::RepresentationSet`. `HalClient` always returns `RepresentationSet`s when following links, even when there is only one result as doing so tends to result in simpler client code.
 
-`RepresentationSet`s are `Enumerable` so they expose all your favorite methods like `#each`, `#map`, `#any?`, etc. Additionally, `RepresentationSet`s expose a `#related` method which calls `#related` on each member of the set and then merges the results into a new representation set.
+`RepresentationSet`s are `Enumerable` so they expose all your favorite methods like `#each`, `#map`, `#any?`, etc. `RepresentationSet`s expose a `#related` method which calls `#related` on each member of the set and then merges the results into a new representation set.
 
     authors = blog.related("author").related("item")
     authors.first.property("name")
     # => "Bob Smith"
 
+#### CURIEs
+
+Links specified using a compact URI (or CURIE) as the rel are fully supported. They are accessed using the fully expanded version of the curie. For example, given a representations of an author:
+
+    { "name": "Bob Smith,
+      "_links": {
+        "so:homeLocation": { "href": "http://example.com/denver" },
+        "curies": [{ "name": "so", "href": "http://schema.org/{rel}", "templated": true }]
+    }}
+
+Bob's home location can be retrieved with
+
+    author.related("http://schema.org/homeLocation")
+    # => #<Representation: http://example.com/denver>
+
+Links are always accessed using the full link relation, rather than the CURIE, because the document producer can use any arbitrary string as the prefix. This means that clients must not make any assumptions regarding what prefix will be used because it might change over time or even between documents.
+
 ### Templated links
 
 The `#related` methods takes a `Hash` as its second argument which is used to expand any templated links that are involved in the navigation.
@@ -73,13 +85,21 @@ All `HalClient::Representation`s exposed an `#href` attribute which is its ident
 
     blog['title'] # => "Some Person's Blog"
     blog['item']  # =>  #<RepresentationSet:...>
-    
+
+### Custom media types
+
+If the API uses one or more a custom mime types we can specify that they be included in the `Accept` header field of each request.
+
+    my_client = HalClient.new(accept: "application/vnd.myapp+hal+json")
+    my_client.get("http://blog.me/")
+    # => #<Representation: http://blog.me/>
 
 ## Contributing
 
 1. Fork it ( http://github.com/pezra/hal-client/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-3. Update `lib/hal_client/version.rb` following [semantic versioning rules](http://semver.org/)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+3. Implement your improvement
+4. Update `lib/hal_client/version.rb` following [semantic versioning rules](http://semver.org/)
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Create new Pull Request

data/lib/hal_client/curie_resolver.rb

@@ -0,0 +1,52 @@
+require 'addressable/template'
+
+class HalClient
+
+  # Expands CURIEs to fully qualified URLs using a set curie
+  # definitions.
+  class CurieResolver
+
+    # Initialize new CurieResolver
+    #
+    # curie_defs - Array of curie definition links (per the HAL spec)
+    def initialize(curie_defs)
+      curie_defs = [curie_defs].flatten
+      @namespaces = interpret curie_defs
+    end
+
+    # Returns a an expanded version of `curie_or_uri` or the
+    # input. The input is returned when `curie_or_uri` is not a curie
+    # or is a curie whose namespace is not recognized.
+    #
+    # curie_or_uri - the (potential) curie to resolve
+    def resolve(curie_or_uri)
+      ns, short_name = split_curie curie_or_uri
+
+      if ns && (namespaces.has_key? ns)
+        namespaces[ns].expand(rel: short_name).to_s
+      else
+        curie_or_uri
+      end
+    end
+
+    protected
+    attr_reader :namespaces
+
+    def split_curie(a_curie)
+      curie_parts = /(?<ns>[^:]+):(?<short_name>.+)/.match(a_curie)
+
+      if curie_parts
+        [curie_parts[:ns], curie_parts[:short_name]]
+      else
+        [nil,nil]
+      end
+    end
+
+    def interpret(curie_defs)
+      Hash[curie_defs.map{|it|
+             [it["name"], Addressable::Template.new(it["href"])]
+           }]
+    end
+
+  end
+end

data/lib/hal_client/representation.rb

@@ -131,17 +131,23 @@ class HalClient
       end
     end
 
+    # Returns a short human readable description of this
+    # representation.
+    def to_s
+      "#<" + self.class.name + ": " + href + ">"
+    end
+
     protected
     attr_reader :raw, :hal_client
 
     MISSING = Object.new
 
     def link_section
-      @link_section ||= raw.fetch("_links", {})
+      @link_section ||= fully_qualified raw.fetch("_links", {})
     end
 
     def embedded_section
-      @embedded_section ||= raw.fetch("_embedded", {})
+      @embedded_section ||= fully_qualified raw.fetch("_embedded", {})
     end
 
     def embedded(link_rel)
@@ -177,5 +183,17 @@ class HalClient
       end
     end
 
+    def fully_qualified(relations_section)
+      Hash[relations_section.map {|rel, link_info|
+        [(namespaces.resolve rel), link_info]
+      }]
+    end
+
+    def namespaces
+      @namespaces ||= CurieResolver.new raw.fetch("_links", {}).fetch("curies", [])
+    end
+
+
+
   end
 end

data/lib/hal_client/version.rb

@@ -1,3 +1,3 @@
 class HalClient
-  VERSION = "1.1.0"
+  VERSION = "1.3.1"
 end

data/lib/hal_client.rb

@@ -5,6 +5,7 @@ require 'rest-client'
 class HalClient
   autoload :Representation, 'hal_client/representation'
   autoload :RepresentationSet, 'hal_client/representation_set'
+  autoload :CurieResolver, 'hal_client/curie_resolver'
 
   # Initializes a new client instance
   #
@@ -31,4 +32,22 @@ class HalClient
   def rest_client_options(overrides)
     {accept: default_accept}.merge overrides
   end
+
+  module EntryPointCovenienceMethods
+    # Returns a `Representation` of the resource identified by `url`.
+    #
+    # url - The URL of the resource of interest.
+    # options - set of options to pass to `RestClient#get`
+    def get(url, options={})
+      default_client.get(url, options)
+    end
+
+    protected
+
+    def default_client
+      @default_client ||= self.new
+    end
+  end
+  extend EntryPointCovenienceMethods
+
 end

data/spec/hal_client/curie_resolver_spec.rb

@@ -0,0 +1,38 @@
+require_relative "../spec_helper"
+
+require 'hal_client/curie_resolver'
+
+describe HalClient::CurieResolver do
+  describe "#new" do
+    it "takes an array of curie definitions" do
+      expect(described_class.new([f_ns, b_ns])).to be_kind_of described_class
+    end
+
+    it "takes a single curie definition" do
+      expect(described_class.new(f_ns)).to be_kind_of described_class
+    end
+  end
+
+  subject(:resolver) { described_class.new([f_ns, b_ns]) }
+
+  describe "#resolve" do
+    it "returns rel name given a standard rel name" do
+      expect(resolver.resolve("item")).to eq "item"
+    end
+
+    it "returns url given a fully qualified url" do
+      expect(resolver.resolve("http://example.com/foo")).to eq "http://example.com/foo"
+    end
+
+    it "returns expanded url given a curie in known namespace" do
+      expect(resolver.resolve("f:yer")).to eq "foo:yer"
+    end
+
+    it "returns unexpanded curie given a curie in unknown namespace" do
+      expect(resolver.resolve("ex:yer")).to eq "ex:yer"
+    end
+  end
+
+  let(:f_ns) { {"name" => "f", "href" => "foo:{rel}", "templated" => true} }
+  let(:b_ns) { {"name" => "b", "href" => "bar:{rel}", "templated" => true} }
+end

data/spec/hal_client/representation_spec.rb

@@ -31,6 +31,12 @@ describe HalClient::Representation do
 HAL
   subject(:repr) { described_class.new(a_client, MultiJson.load(raw_repr)) }
 
+  describe "#to_s" do
+    subject(:return_val) { repr.to_s }
+
+    it { should eq "#<HalClient::Representation: http://example.com/foo>" }
+  end
+
   describe "#property" do
     context "existent" do
       subject { repr.property "prop1" }
@@ -148,6 +154,61 @@ HAL
   end
 
 
+  context "curie links" do
+    let(:raw_repr) { <<-HAL }
+{ "_links": {
+    "self": { "href": "http://example.com/foo" }
+    ,"ex:bar": { "href": "http://example.com/bar" }
+    ,"curies": [{"name": "ex", "href": "http://example.com/rels/{rel}", "templated": true}]
+  }
+}
+HAL
+
+    describe "#related return value " do
+      subject(:return_val) { repr.related("http://example.com/rels/bar") }
+      it { should include_representation_of "http://example.com/bar" }
+    end
+
+    describe "#[] return value " do
+      subject(:return_val) { repr["http://example.com/rels/bar"] }
+      it { should include_representation_of "http://example.com/bar" }
+    end
+
+    describe "#related_hrefs return value " do
+      subject(:return_val) { repr.related_hrefs("http://example.com/rels/bar") }
+      it { should include "http://example.com/bar" }
+    end
+  end
+
+  context "curie embedded" do
+    let(:raw_repr) { <<-HAL }
+{ "_links": {
+    "self": { "href": "http://example.com/foo" }
+    ,"curies": {"name": "ex", "href": "http://example.com/rels/{rel}", "templated": true}
+  }
+  ,"_embedded": {
+    "ex:embed1": { "_links": { "self": { "href": "http://example.com/embed1" } } }
+  }
+}
+HAL
+
+    describe "#related return value " do
+      subject(:return_val) { repr.related("http://example.com/rels/embed1") }
+      it { should include_representation_of "http://example.com/embed1" }
+    end
+
+    describe "#[] return value " do
+      subject(:return_val) { repr["http://example.com/rels/embed1"] }
+      it { should include_representation_of "http://example.com/embed1" }
+    end
+
+    describe "#related_hrefs return value " do
+      subject(:return_val) { repr.related_hrefs("http://example.com/rels/embed1") }
+      it { should include "http://example.com/embed1" }
+    end
+  end
+
+
 
   let(:a_client) { HalClient.new }
   let!(:bar_request) { stub_identity_request("http://example.com/bar") }

data/spec/hal_client_spec.rb

@@ -39,6 +39,24 @@ describe HalClient do
     end
   end
 
+  describe ".get(<url>)" do 
+    let!(:return_val) { HalClient.get "http://example.com/foo" }
+
+    it "returns a HalClient::Representation" do
+      expect(return_val).to be_kind_of HalClient::Representation
+    end
+
+    describe "request" do
+      subject { request }
+      it("should have been made") { should have_been_made }
+
+      it "sends accept header" do
+        expect(request.with(headers: {'Accept' => 'application/hal+json'})).
+          to have_been_made
+      end
+    end
+  end
+
   let!(:request) { stub_request(:get, "http://example.com/foo").
     to_return body: "{}" }
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hal-client
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.1
 platform: ruby
 authors:
 - Peter Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-11 00:00:00.000000000 Z
+date: 2014-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -152,6 +152,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -159,9 +160,11 @@ files:
 - hal-client.gemspec
 - lib/hal-client.rb
 - lib/hal_client.rb
+- lib/hal_client/curie_resolver.rb
 - lib/hal_client/representation.rb
 - lib/hal_client/representation_set.rb
 - lib/hal_client/version.rb
+- spec/hal_client/curie_resolver_spec.rb
 - spec/hal_client/representation_set_spec.rb
 - spec/hal_client/representation_spec.rb
 - spec/hal_client_spec.rb
@@ -191,6 +194,7 @@ signing_key:
 specification_version: 4
 summary: Use HAL APIs easily
 test_files:
+- spec/hal_client/curie_resolver_spec.rb
 - spec/hal_client/representation_set_spec.rb
 - spec/hal_client/representation_spec.rb
 - spec/hal_client_spec.rb