juicer-client 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 13438d05877e7471849d931789e96e8e07e7cec6
-  data.tar.gz: 4e6b4d2ede7e54a1710cb34a03cd3403e974f302
+  metadata.gz: 427f04d658cf29b4589b1fb322d51485742b6bb3
+  data.tar.gz: 7a1a2aa498ff8beaff557423f7caa996ea9cb3c5
 SHA512:
-  metadata.gz: 56dd21d839cb08779bfe8823e4281251193bafd34ae718f34888ff9c55dc4df7aef0b0a5d55393939d5cba33386d1b08a6befad947e1c0bf7981d3c1ba1150b6
-  data.tar.gz: cd0798958ba81451368e145b4285a1e5f02f605ff2c0aa331a738b294aed8afd348fb40a1b0ba1db50a817b5b3c2db82e9c1230c2ead7311d1255611b7ea27e9
+  metadata.gz: 2e7f86ddac59c84017c3bda094fc6689037ea6eef2b7969d59f32c11ecbfaec6560251efc10b39621c6b41ca06ec62378b3845b538da660794882d17fd2206b4
+  data.tar.gz: b4b550ea714f5c59c90681ea34c196aca66fcc0568d32cb251689ca85860aa66d96f30930ed5820922bcf045e73f9e400021f8413a1c16d22542e29d7ca66b48

data/README.md

@@ -2,6 +2,10 @@
 
 The API client for the [BBC News Labs Juicer API](http://juicer.bbcnewslabs.co.uk).
 
+NOTE: the Juicer is an experiment run by the BBC News Labs. The API may change
+without notice, there are no uptime, reliability guarantees. Please take this
+as experimental sofware in front of experimental API.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -35,7 +39,8 @@ require 'juicer'
 juicer = Juicer.new("<your API key>")
 ```
 
-Have a look at the [documentation](http://bbc-news-labs.github.io/juicer-client/)
+Have a look at the
+[documentation](http://bbc-news-labs.github.io/juicer-client/Juicer.html)
 for the library on how to filter articles, find similar content, etc.
 
 ```ruby
@@ -66,7 +71,6 @@ juicer.similar_articles("news_web_0962731f8c375d5096590ca38cee96e0e408180d")
      "cps_id"=>"20038835",
      "created_at"=>"2012-10-23T12:58:45.247Z",
      "published_at"=>"2012-10-23T11:57:37Z",
-     "juicer_url"=>"http://juicer.bbcnewslabs.co.uk/articles/20038835.json",
      "url"=>"http://www.bbc.co.uk/news/business-20038835"},
     {...}]
 ```

data/lib/juicer.rb

@@ -8,7 +8,7 @@ class Juicer
   # Initialize the Juicer API client.
   #
   # @param api_key [String] API key obtained from Apigee.
-  # @return [Juicer] The API client.
+  # @return [Juicer] the API client.
   #
   def initialize(api_key)
     @client = Juicer::Client.new(api_key)
@@ -49,10 +49,10 @@ class Juicer
   #   Just a heads up when doing queries that potentially return a large number
   #   of results.
   #
-  # @param opts [Hash] A Hash of filter options.
+  # @param opts [Hash] a Hash of filter options.
   #   Possible keys are:
   #
-  #     * `text` - a search term, corresponds to Lucene syntax
+  #     * `text` - a search term, corresponds to Lucene syntax.
   #     * `product` - list of products to scope to. See {#products}.
   #     * `content_format` - list of content formats to scope to. See {#formats}.
   #     * `section` - list of sections to scope to. See {#sections}.
@@ -79,22 +79,36 @@ class Juicer
   # find semantically similar documents.
   #
   # @param cps_id [String] the `cps_id` of an article.
+  # @param opts [Hash] a Hash of query options
+  #   Possible keys are:
+  #
+  #     * `size` - how many results to return. Results are ordered by their
+  #       "match" score, i.e how similar they are to a given article, and the
+  #       top `size` results are returned.
+  #     * `product` - an [Array] of products to scope to. See {#products}.
   # @return [Array<Hash>] list of similar articles. Currently capped to 10 most
   #   similar.
   #
-  def similar_articles(cps_id)
-    @client.request(:get, "articles/#{cps_id}/similar")["results"]
+  def similar_articles(cps_id, opts = {})
+    @client.request(:get, "articles/#{cps_id}/similar", opts)["results"]
   end
 
   # Fetch articles related (similar) to an arbitrary blob of text. Uses tf-idf
   # algorithm to find semantically similar documents.
   #
   # @param text [String] a blob of text.
+  # @param opts [Hash] a Hash of query options
+  #   Possible keys are:
+  #
+  #     * `size` - how many results to return. Results are ordered by their
+  #       "match" score, i.e how similar they are to the given blob of text, and
+  #       the top `size` results are returned.
+  #     * `product` - an [Array] of products to scope to. See {#products}.
   # @return [Array<Hash>] list of similar articles. Currently capped to 10 most
   #   similar.
   #
-  def similar_to(text)
+  def similar_to(text, opts = {})
     body = { like_text: URI.encode(text) }.to_json
-    @client.request(:post, "similar_to", {}, body)["results"]
+    @client.request(:post, "similar_to", opts, body)["results"]
   end
 end

data/lib/juicer/client.rb

@@ -18,8 +18,8 @@ class Juicer
 
     # Initialize HTTP client
     #
-    # @param api_key [String] the API key from Apigee
-    # @return [Juicer::Client] HTTP client instance
+    # @param api_key [String] the API key from Apigee.
+    # @return [Juicer::Client] HTTP client instance.
     #
     def initialize(api_key)
       @api_key = api_key
@@ -33,7 +33,7 @@ class Juicer
     # @note The Juicer API currently only supports `:get` and `:post` values for
     #   the `method` param.
     # @param method [Symbol] HTTP method.
-    # @param path [String] an endpoint path
+    # @param path [String] an endpoint path.
     # @param query_params [Hash] a hash of query parameters. List values are
     #   handled "correctly" in the sense that values of [Array] type produce
     #   `key[]=foo&key[]=bar` style values, suitable for Rails.
@@ -54,8 +54,8 @@ class Juicer
 
     # Small helper method for sanitizing the `path` for `request` method.
     #
-    # @param path [String] a path to an endpoint
-    # @return [String] sanitized and fully constructed endpoint URL
+    # @param path [String] a path to an endpoint.
+    # @return [String] sanitized and fully constructed endpoint URL.
     #
     def api_url(path)
       path.sub!(/^\/+/, '')

data/lib/juicer/version.rb

@@ -1,3 +1,3 @@
 class Juicer
-  VERSION = "1.0.0".freeze
+  VERSION = "1.1.0".freeze
 end

data/spec/juicer_spec.rb

@@ -124,12 +124,28 @@ describe Juicer do
       stub_request(:get, "http://data.bbc.co.uk/bbcrd-juicer/articles/#{cps_id}/similar.json")
         .with(query: { apikey: api_key })
         .to_return(body: body.to_json)
+      stub_request(:get, "http://data.bbc.co.uk/bbcrd-juicer/articles/#{cps_id}/similar.json")
+        .with(query: { apikey: api_key, size: 5 })
+        .to_return(body: body.to_json)
+      stub_request(:get, "http://data.bbc.co.uk/bbcrd-juicer/articles/#{cps_id}/similar.json")
+        .with(query: { apikey: api_key, product: ["NewsWeb"] })
+        .to_return(body: body.to_json)
     end
 
-    it "queries the `similar` endpoint" do
+    it "queries the `similar` endpoint with defaults" do
       response = juicer.similar_articles(cps_id)
       expect(response).to eq(body["results"])
     end
+
+    it "queries the `similar` endpoint with `size`" do
+      response = juicer.similar_articles(cps_id, size: 5)
+      expect(response).to eq(body["results"])
+    end
+
+    it "queries the `similar` endpoint with `product`" do
+      response = juicer.similar_articles(cps_id, product: ["NewsWeb"])
+      expect(response).to eq(body["results"])
+    end
   end
 
   describe "#similar_to" do
@@ -144,11 +160,29 @@ describe Juicer do
         .with(query: { apikey: api_key },
               body: { like_text: URI.encode(text) }.to_json)
         .to_return(body: body.to_json)
+      stub_request(:post, "http://data.bbc.co.uk/bbcrd-juicer/similar_to.json")
+        .with(query: { apikey: api_key, size: 5 },
+              body: { like_text: URI.encode(text) }.to_json)
+        .to_return(body: body.to_json)
+      stub_request(:post, "http://data.bbc.co.uk/bbcrd-juicer/similar_to.json")
+        .with(query: { apikey: api_key, product: ["NewsWeb"] },
+              body: { like_text: URI.encode(text) }.to_json)
+        .to_return(body: body.to_json)
     end
 
-    it "queries the `similar_to` endpoint" do
+    it "queries the `similar_to` endpoint with defaults" do
       response = juicer.similar_to(text)
       expect(response).to eq(body["results"])
     end
+
+    it "queries the `similar_to` endpoint with `size`" do
+      response = juicer.similar_to(text, size: 5)
+      expect(response).to eq(body["results"])
+    end
+
+    it "queries the `similar_to` endpoint with `product`" do
+      response = juicer.similar_to(text, product: ["NewsWeb"])
+      expect(response).to eq(body["results"])
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: juicer-client
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Karl Sutt
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-14 00:00:00.000000000 Z
+date: 2014-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httpi