hal-client 2.0.2 → 2.2.0

data/README.md

@@ -47,7 +47,7 @@ In the example above `item` is the link rel. The `#related` method extracts embe
 
 #### Request timing
 
-If the `author` relationship was a link in the above example the HTTP GET to retrieve Bob's representation from the server does not happen until the `#property` method is called. This lazy dereferencing allows for working with efficiently with larger relationship sets.
+If the `author` relationship was a regular link (that is, not embedded) in the above example the HTTP GET to retrieve Bob's representation from the server does not happen until the `#property` method is called. This lazy dereferencing allows for working with efficiently with larger relationship sets.
 
 #### CURIEs
 
@@ -66,7 +66,7 @@ Bob's home location can be retrieved with
 
 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
+#### 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.
 
@@ -88,6 +88,26 @@ All `HalClient::Representation`s exposed an `#href` attribute which is its ident
     blog['title'] # => "Some Person's Blog"
     blog['item']  # =>  #<RepresentationSet:...>
 
+### POST requests
+
+HalClient supports POST requests to remote resources via it's `#post` method.
+
+    blog.post(new_article_as_hal_json_str)
+    #=> #<Representation: http://blog.me>
+
+The argument to post may be `String` or any object that responds to `#to_hal`. Additional options may be passed to change the content type of the post, etc.
+
+### Paged collections
+
+HalClient provides a high level abstraction for paged collections encoded using [standard `item`, `next` and `prev` link relations](http://tools.ietf.org/html/rfc6573).
+
+    articles = HalClient::Collection.new(blog)
+    articles.each do |an_article|
+      # do something with each article representation
+    end
+
+If the collection is paged this will navigate to the next page after yielding all the items on the current page. `HalClient::Collection` is `Enumerable` so all your favorite collection methods are available.
+
 ### 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.
@@ -96,7 +116,12 @@ If the API uses one or more a custom mime types we can specify that they be incl
     my_client.get("http://blog.me/")
     # => #<Representation: http://blog.me/>
 
-### Parsing presentations from clients
+Similarly we can set the default `Content-Type` for post requests.
+
+    my_client = HalClient.new(accept: "application/vnd.myapp+hal+json",
+                              content_type: "application/vnd.myapp+hal+json")
+
+### Parsing representations on the server side
 
 HalClient can be used by servers of HAL APIs to interpret the bodies of requests. For example,
 

data/hal-client.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "rest-client", "~> 1.6", '>= 1.6.0'
   spec.add_dependency "addressable", "~> 2.3", '>= 2.3.0'
-  spec.add_dependency "multi_json", "~> 1.8", '>= 1.8.0'
+  spec.add_dependency "multi_json", "~> 1.9", '>= 1.9.0'
 
   spec.add_development_dependency "bundler", "~> 1.5"
   spec.add_development_dependency "rake", "~> 10.1", '>= 10.1.0'

data/lib/hal_client/collection.rb

@@ -0,0 +1,73 @@
+require_relative "../hal_client"
+
+class HalClient
+
+  # Enumerable for items in a paged collection of HAL representations
+  # that are encoded using the IANA standard `item`, `next` and `prev`
+  # link rels.
+  #
+  # This will fetch subsequent pages on iteration
+  class Collection
+    include Enumerable
+
+    # Initializes a collection starting at `first_page`.
+    #
+    # first_page - The HalClient::Representation of the first page of
+    #   the collection to be iterated over.
+    #
+    # Raises HalClient::NotACollectionError if `first_page` is not a
+    #   page of a collection.
+    # Raises ArgumentError if `first_page` is some page other than 
+    #   the first of the collection.
+    def initialize(first_page)
+      (fail NotACollectionError) unless first_page.has_related? "item"
+      (fail ArgumentError, "Not the first page of the collection") if first_page.has_related? "prev"
+
+      @first_page = first_page
+    end
+
+    # Returns the number of items in the collection if it is fast to
+    # calculate.
+    #
+    # Raises NotImplementedError if any of the pages of the collection
+    #   have not already been cached.
+    def count(&blk)
+      (fail NotImplementedError, "Cowardly refusing to make an arbitrary number of HTTP requests") unless all_pages_cached?
+
+      total = 0
+      each_page do |p|
+        total += p.related("item").count
+      end
+
+      total
+    end
+
+    # Iterates over the members of the collection fetching the next
+    # page as necessary.
+    #
+    # Yields the next item of the iteration.
+    def each(&blk)
+      each_page do |a_page|
+        a_page.related("item").each(&blk)
+      end
+    end
+
+    protected
+
+    attr_reader :first_page
+
+    def all_pages_cached?
+      ! first_page.has_related?("next")
+    end
+
+    def each_page(&blk)
+      yield first_page
+
+      cur_page = first_page
+      while cur_page.has_related? "next"
+        cur_page = cur_page.related("next").first
+        yield cur_page
+      end
+    end
+  end
+end

data/lib/hal_client/errors.rb

@@ -1,3 +1,4 @@
 class HalClient
   InvalidRepresentationError = Class.new(StandardError)
+  NotACollectionError = Class.new(StandardError)
 end

data/lib/hal_client/representation.rb

@@ -27,7 +27,15 @@ class HalClient
         @raw.nil? && @href.nil?
 
       (fail InvalidRepresentationError, "Invalid HAL representation: #{raw.inspect}") if
-        raw && ! hashish?(raw)
+        @raw && ! hashish?(@raw)
+    end
+
+    # Posts a `Representation` or `String` to this resource.
+    #
+    # data - a `String` or an object that responds to `#to_hal`
+    # options - set of options to pass to `HalClient#post`
+    def post(data, options={})
+      @hal_client.post(href, data, options)
     end
 
     # Returns The value of the specified property or the specified
@@ -146,13 +154,19 @@ class HalClient
       "#<" + self.class.name + ": " + href + ">"
     end
 
+    # Returns the raw json representation of this representation
+    def to_json
+      raw.to_json
+    end
+
     protected
     attr_reader :hal_client
 
     MISSING = Object.new
 
     def raw
-      if @raw.nil? && @href && hal_client
+      if @raw.nil? && @href
+        (fail "unable to make requests due to missing hal client") unless hal_client
         @raw ||= hal_client.get(@href).raw
       end
 

data/lib/hal_client/representation_set.rb

@@ -27,6 +27,29 @@ class HalClient
       RepresentationSet.new flat_map{|it| it.related(link_rel, options){[]}.to_a }
     end
 
+    # Returns true if any member representation contains a link
+    # (including embedded links) whose rel is `link_rel`.
+    #
+    # link_rel - The link rel of interest
+    def has_related?(link_rel)
+      _ = related link_rel
+      true
+
+    rescue KeyError
+      false
+    end
+
+    # Post a `Representation` or `String` to the resource.
+    #
+    # NOTE: This only works for a single representation.
+    #
+    # data - a `String` or an object that responds to `#to_hal`
+    # options - set of options to pass to `HalClient#post`
+    def post(data, options={})
+      raise NotImplementedError, "We only posts to singular resources." if count > 1
+      first.post(data, options)
+    end
+
     protected
 
     attr_reader :reprs

data/lib/hal_client/version.rb

@@ -1,3 +1,3 @@
 class HalClient
-  VERSION = "2.0.2"
+  VERSION = "2.2.0"
 end

data/lib/hal_client.rb

@@ -1,5 +1,6 @@
 require "hal_client/version"
 require 'rest-client'
+require 'multi_json'
 
 # Adapter used to access resources.
 class HalClient
@@ -7,14 +8,18 @@ class HalClient
   autoload :RepresentationSet, 'hal_client/representation_set'
   autoload :CurieResolver, 'hal_client/curie_resolver'
   autoload :InvalidRepresentationError, 'hal_client/errors'
+  autoload :NotACollectionError, 'hal_client/errors'
 
   # Initializes a new client instance
   #
   # options - hash of configuration options
-  #   :accept - one or more content types that should be 
+  #   :accept - one or more content types that should be
   #     prepended to the `Accept` header field of each request.
+  #   :content_type - a single content type that should be
+  #     prepended to the `Content-Type` header field of each request.
   def initialize(options={})
     @default_accept = options.fetch(:accept, 'application/hal+json')
+    @default_content_type = options.fetch(:content_type, 'application/hal+json')
   end
 
   # Returns a `Representation` of the resource identified by `url`.
@@ -22,16 +27,38 @@ class HalClient
   # url - The URL of the resource of interest.
   # options - set of options to pass to `RestClient#get`
   def get(url, options={})
-    resp = RestClient.get url, rest_client_options(options)
+    resp = RestClient.get url, get_options(options)
     Representation.new hal_client: self, parsed_json: MultiJson.load(resp)
   end
 
+  # Post a `Representation` or `String` to the resource identified at `url`.
+  #
+  # url - The URL of the resource of interest.
+  # data - a `String` or an object that responds to `#to_hal`
+  # options - set of options to pass to `RestClient#post`
+  def post(url, data, options={})
+    resp = RestClient.post url, data, post_options(options)
+
+    begin
+      Representation.new hal_client: self, parsed_json: MultiJson.load(resp)
+    rescue MultiJson::ParseError, InvalidRepresentationError => e
+      resp
+    end
+  end
+
   protected
 
-  attr_reader :default_accept
+  attr_reader :default_accept, :default_content_type
 
-  def rest_client_options(overrides)
-    {accept: default_accept}.merge overrides
+  def get_options(overrides)
+    { accept: default_accept }.merge overrides
+  end
+
+  def post_options(overrides)
+    {
+      accept: default_accept,
+      content_type: default_content_type
+    }.merge overrides
   end
 
   module EntryPointCovenienceMethods
@@ -43,6 +70,15 @@ class HalClient
       default_client.get(url, options)
     end
 
+    # Post a `Representation` or `String` to the resource identified at `url`.
+    #
+    # url - The URL of the resource of interest.
+    # data - a `String` or an object that responds to `#to_hal`
+    # options - set of options to pass to `RestClient#get`
+    def post(url, data, options={})
+      default_client.post(url, data, options)
+    end
+
     protected
 
     def default_client

data/spec/hal_client/collection_spec.rb

@@ -0,0 +1,87 @@
+require_relative "../spec_helper"
+
+require 'hal_client/collection'
+
+describe HalClient::Collection do
+  describe "creation" do
+    subject { described_class }
+
+    specify do
+      expect { described_class.new(collection_page) }
+        .not_to raise_error
+    end
+
+    specify do
+      expect { described_class.new(non_collection_repr) }
+        .to raise_error HalClient::NotACollectionError
+    end
+
+    specify do
+      expect { described_class.new(non_first_page) }
+        .to raise_error ArgumentError, /first page/
+    end
+
+    let(:non_collection_repr) { repr({}) }
+    let(:non_first_page) { collection_page(prev_href: "http://example.com/p1") }
+  end
+
+  describe "multi-item, multi-page" do
+    subject(:collection) { described_class.new(first_page) }
+    let!(:second_page_req) { stub_request(:get, second_page.href)
+        .to_return body: second_page.to_json  }
+
+    it "fetches all the pages when iterating" do
+      collection.each do |it| end
+
+      expect(a_request(:get, second_page.href)).to have_been_made
+    end
+
+    it "iteration yields all the items" do
+      yielded = collection.map { |it| it.href }
+      expect(yielded).to eq ["foo", "bar", "baz"]
+    end
+
+    specify { expect { collection.count }.to raise_exception }
+
+
+    let(:first_page_href) { "http://example.com/p1" }
+    let(:first_page) { collection_page(next_href: second_page_href,
+                                       self_href: first_page_href,
+                                       items: ["foo", "bar"]) }
+
+    let(:second_page_href) { "http://example.com/p2" }
+    let(:second_page) { collection_page(items: ["baz"],
+                                        self_href: second_page_href,
+                                        prev_href: first_page_href) }
+  end
+
+  describe "multi-item, single page" do
+    subject(:collection) { described_class.new(only_page) }
+
+    specify { expect(collection.count).to eq 2 }
+
+    let(:only_page) { collection_page(self_href: "http://example.com/p1",
+                                       items: ["foo", "bar"]) }
+  end
+
+  let(:hal_client) { HalClient.new }
+
+  def collection_page(opts={})
+    next_href = opts[:next_href]
+    prev_href = opts[:prev_href]
+    self_href = opts.fetch(:self_href, "a_page")
+    items = opts.fetch(:items, [])
+      .map{|it| {"_links"=>{"self"=>{"href"=>it}}} }
+
+    full = {"_embedded"=>{"item"=>items},
+      "_links"=>{"self"=>{"href"=>self_href}}}
+    full["_links"]["next"] = {"href" => next_href} if next_href
+    full["_links"]["prev"] = {"href" => prev_href} if prev_href
+
+    repr full
+  end
+
+  def repr(a_hash)
+    HalClient::Representation.new parsed_json: a_hash, hal_client: hal_client
+  end
+end

data/spec/hal_client/representation_set_spec.rb

@@ -28,6 +28,7 @@ describe HalClient::RepresentationSet do
     it "returns true if there are any" do
       expect(subject.any?{|it| it == foo_repr }).to be_true
     end
+
     it "returns false if there aren't any" do
       expect(subject.any?{|it| false }).to be_false
     end
@@ -40,6 +41,7 @@ describe HalClient::RepresentationSet do
       it { should include_representation_of "http://example.com/bar-spouse" }
       it { should have(2).items }
     end
+
     context "multiple targets" do
       subject(:returned_val) { repr_set.related("sibling") }
       it { should include_representation_of "http://example.com/foo-brother" }
@@ -47,6 +49,7 @@ describe HalClient::RepresentationSet do
       it { should include_representation_of "http://example.com/bar-brother" }
       it { should have(3).items }
     end
+
     context "templated" do
       subject(:returned_val) { repr_set.related("cousin", distance: "first") }
       it { should include_representation_of "http://example.com/foo-first-cousin" }
@@ -56,6 +59,24 @@ describe HalClient::RepresentationSet do
     end
   end
 
+  describe "#post" do
+    context "with a single representation" do
+      subject(:repr_single_set) { described_class.new([foo_repr]) }
+      let!(:post_request) { stub_request(:post, "example.com/foo") }
+
+      before(:each) do
+        repr_single_set.post("abc")
+      end
+
+      it "makes an HTTP POST with the data within the representation" do
+        expect(
+          post_request.
+          with(:body => "abc", :headers => {'Content-Type' => 'application/hal+json'})
+          ).to have_been_made
+      end
+    end
+  end
+
   let(:a_client) { HalClient.new }
 
   let(:foo_repr) { HalClient::Representation.new hal_client: a_client, parsed_json: MultiJson.load(foo_hal)}
@@ -101,7 +122,6 @@ describe HalClient::RepresentationSet do
       to_return body: %Q|{"_links":{"self":{"href":#{url.to_json}}}}|
   end
 
-
   RSpec::Matchers.define(:include_representation_of) do |url|
     match { |repr_set|
       repr_set.any?{|it| it.href == url}

data/spec/hal_client/representation_spec.rb

@@ -23,6 +23,23 @@ HAL
   subject(:repr) { described_class.new(hal_client: a_client,
                                        parsed_json: MultiJson.load(raw_repr)) }
 
+  describe "#post" do
+    let!(:post_request) {
+      stub_request(:post, "example.com/bar")
+    }
+
+    before(:each) do
+      repr.related("link1").post("abc")
+    end
+
+    specify {
+      expect(
+        post_request.
+        with(:body => "abc", :headers => {'Content-Type' => 'application/hal+json'})
+      ).to have_been_made
+    }
+  end
+
   describe "#to_s" do
     subject(:return_val) { repr.to_s }
 
@@ -34,6 +51,7 @@ HAL
       subject { repr.property "prop1" }
       it { should eq 1 }
     end
+
     context "non-existent" do
       it "raises exception" do
         expect{repr.property 'wat'}.to raise_exception KeyError
@@ -48,6 +66,7 @@ HAL
       subject { repr.fetch "prop1" }
       it { should eq 1 }
     end
+
     context "for existent link" do
       subject { repr.fetch "link1" }
       it { should have(1).item }
@@ -55,6 +74,7 @@ HAL
         expect(subject.first.href).to eq "http://example.com/bar"
       end
     end
+
     context "for existent embedded" do
       subject { repr.fetch "embed1" }
       it { should have(1).item }
@@ -62,15 +82,18 @@ HAL
         expect(subject.first.href).to eq "http://example.com/baz"
       end
     end
+
     context "non-existent item w/o default" do
       it "raises exception" do
         expect{repr.fetch 'wat'}.to raise_exception KeyError
       end
     end
+
     context "non-existent item w/ default value" do
       subject { repr.fetch "wat", "whatevs" }
       it { should eq "whatevs" }
     end
+
     context "non-existent item w/ default value generator" do
       subject { repr.fetch("wat"){|key| key+"gen" } }
       it { should eq "watgen" }
@@ -82,16 +105,19 @@ HAL
       subject { repr["prop1"] }
       it { should eq 1 }
     end
+
     context "for existent link" do
       subject { repr["link1"] }
       it { should have(1).item }
       it { should include_representation_of "http://example.com/bar" }
     end
+
     context "for existent embedded" do
       subject { repr["embed1"] }
       it { should have(1).item }
       it { should include_representation_of "http://example.com/baz" }
     end
+
     context "non-existent item w/o default" do
       subject { repr["wat"] }
       it { should be_nil }
@@ -104,22 +130,26 @@ HAL
       it { should have(1).item }
       it { should include_representation_of "http://example.com/bar" }
     end
+
     context "for existent compound link" do
       subject { repr.related "link3" }
       it { should have(2).item }
       it { should include_representation_of "http://example.com/link3-a" }
       it { should include_representation_of "http://example.com/link3-b" }
     end
+
     context "for existent templated link" do
       subject { repr.related "link2", name: "bob" }
       it { should have(1).item }
       it { should include_representation_of "http://example.com/people?name=bob"  }
     end
+
     context "for existent embedded" do
       subject { repr.related "embed1" }
       it { should have(1).item }
       it { should include_representation_of "http://example.com/baz" }
     end
+
     context "non-existent item w/o default" do
       it "raises exception" do
         expect{repr.related 'wat'}.to raise_exception KeyError
@@ -133,11 +163,13 @@ HAL
       it { should have(1).item }
       it { should include "http://example.com/bar" }
     end
+
     context "for existent embedded" do
       subject { repr.related_hrefs "embed1" }
       it { should have(1).item }
       it { should include "http://example.com/baz" }
     end
+
     context "non-existent item w/o default" do
       it "raises exception" do
         expect{repr.related_hrefs 'wat'}.to raise_exception KeyError
@@ -146,6 +178,7 @@ HAL
   end
 
   specify { expect(subject.has_related? "link1").to be true }
+  specify { expect(subject.has_related? "link3").to be true }
   specify { expect(subject.has_related? "embed1").to be true }
 
   specify { expect(subject.has_related? "no-such-link").to be false }

data/spec/hal_client_spec.rb

@@ -39,7 +39,7 @@ describe HalClient do
     end
   end
 
-  describe ".get(<url>)" do 
+  describe ".get(<url>)" do
     let!(:return_val) { HalClient.get "http://example.com/foo" }
 
     it "returns a HalClient::Representation" do
@@ -57,6 +57,70 @@ describe HalClient do
     end
   end
 
+  describe "#post(<url>)" do
+    subject(:client) { HalClient.new }
+    let!(:return_val) { client.post "http://example.com/foo", post_data }
+
+    it "returns a HalClient::Representation" do
+      expect(return_val).to be_kind_of HalClient::Representation
+    end
+
+    describe "request" do
+      subject { post_request }
+      it("should have been made") { should have_been_made }
+
+      it "sends content type header" do
+        expect(post_request.with(headers: {'Content-Type' => 'application/hal+json'})).
+          to have_been_made
+      end
+    end
+
+    context "explicit content type" do
+      subject(:client) { HalClient.new content_type: 'app/test' }
+      it "sends specified content-type header" do
+        expect(post_request.with(headers: {'Content-Type' => 'app/test'})).
+          to have_been_made
+      end
+    end
+
+    context "with no response body" do
+      subject { empty_post_request }
+      let!(:return_val) { client.post "http://example.com/foo", nil }
+
+      it "returns a 2xx status code in the response" do
+        expect(return_val.code.to_s).to match(/^2../)
+      end
+    end
+  end
+
+  describe ".post(<url>)" do
+    let!(:return_val) { HalClient.post "http://example.com/foo", post_data }
+
+    it "returns a HalClient::Representation" do
+      expect(return_val).to be_kind_of HalClient::Representation
+    end
+
+    describe "request" do
+      subject { post_request }
+      it("should have been made") { should have_been_made }
+
+      it "sends accept header" do
+        expect(post_request.with(headers: {'Content-Type' => 'application/hal+json'})).
+          to have_been_made
+      end
+    end
+  end
+
+  let(:post_data) { "ABC" }
+
+  let!(:empty_post_request) { stub_request(:post, "http://example.com/foo").
+    with(:body => nil).
+    to_return body: nil }
+
+  let!(:post_request) { stub_request(:post, "http://example.com/foo").
+    with(:body => post_data).
+    to_return body: "{}" }
+
   let!(:request) { stub_request(:get, "http://example.com/foo").
     to_return body: "{}" }
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hal-client
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-15 00:00:00.000000000 Z
+date: 2014-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -62,10 +62,10 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '1.9'
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.8.0
+        version: 1.9.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -73,10 +73,10 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '1.9'
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.8.0
+        version: 1.9.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -175,11 +175,13 @@ files:
 - hal-client.gemspec
 - lib/hal-client.rb
 - lib/hal_client.rb
+- lib/hal_client/collection.rb
 - lib/hal_client/curie_resolver.rb
 - lib/hal_client/errors.rb
 - lib/hal_client/representation.rb
 - lib/hal_client/representation_set.rb
 - lib/hal_client/version.rb
+- spec/hal_client/collection_spec.rb
 - spec/hal_client/curie_resolver_spec.rb
 - spec/hal_client/representation_set_spec.rb
 - spec/hal_client/representation_spec.rb
@@ -200,7 +202,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2118316168271544208
+      hash: 2964904468148201420
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -209,7 +211,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2118316168271544208
+      hash: 2964904468148201420
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -217,6 +219,7 @@ signing_key:
 specification_version: 3
 summary: Use HAL APIs easily
 test_files:
+- spec/hal_client/collection_spec.rb
 - spec/hal_client/curie_resolver_spec.rb
 - spec/hal_client/representation_set_spec.rb
 - spec/hal_client/representation_spec.rb