Use new recommendation endpoints

Author: OndraFiedler

README.md

@@ -29,7 +29,7 @@ Or install it yourself as:
 require 'recombee_api_client'
 include RecombeeApiClient
 
-client = RecombeeClient.new('client-test', 'jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L')
+client = RecombeeClient('--my-database-id--', '--my-secret-token--')
 
 # Generate some random purchases of items by users
 NUM = 100
@@ -55,7 +55,7 @@ begin
   client.send(Batch.new(purchases))
 
   # Get recommendations for user 'user-25'
-  recommended = client.send(UserBasedRecommendation.new('user-25', 5))
+  recommended = client.send(RecommendItemsToUser.new('user-25', 5))
   puts "Recommended items for user-25: #{recommended}"
 rescue APIError => e
   puts e
@@ -71,7 +71,7 @@ include RecombeeApiClient
 NUM = 100
 PROBABILITY_PURCHASED = 0.1
 
-client = RecombeeClient.new('client-test', 'jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L')
+client = RecombeeClient('--my-database-id--', '--my-secret-token--')
 client.send(ResetDatabase.new) # Clear everything from the database
 
 # We will use computers as items in this example
@@ -121,21 +121,19 @@ end
 client.send(Batch.new(requests))
 
 # Get 5 recommendations for user-42, who is currently viewing computer-6
-recommended = client.send(ItemBasedRecommendation.new('computer-6', 5, 'targetUserId' => 'user-42') )
+recommended = client.send(RecommendItemsToItem.new('computer-6', 'user-42', 5) )
 puts "Recommended items: #{recommended}"
 
-# Get 5 recommendations for user-42, but recommend only computers that
-# have at least 3 cores
+# Recommend only computers that have at least 3 cores
 recommended = client.send(
-  ItemBasedRecommendation.new('computer-6', 5, {'targetUserId' => 'user-42', 'filter' => "'num-cores'>=3"})
+  RecommendItemsToItem.new('computer-6', 'user-42', 5, {'filter' => "'num-cores'>=3"})
   )
 puts "Recommended items with at least 3 processor cores: #{recommended}"
 
-# Get 5 recommendations for user-42, but recommend only items that
-# are more expensive then currently viewed item (up-sell)
+# Recommend only items thatare more expensive then currently viewed item (up-sell)
 recommended = client.send(
-  ItemBasedRecommendation.new('computer-6', 5,
-    {'targetUserId' => 'user-42', 'filter' => "'price' > context_item[\"price\"]"})
+  RecommendItemsToItem.new('computer-6', 'user-42', 5,
+    {'filter' => "'price' > context_item[\"price\"]"})
   )
 puts "Recommended up-sell items: #{recommended}"
 ```
@@ -151,14 +149,14 @@ Example:
 
 begin
   recommended = client.send(
-  ItemBasedRecommendation.new('computer-6', 5,
-    {'targetUserId' => 'user-42', 'filter' => "'price' > context_item[\"price\"]"})
+    RecommendItemsToItem.new('computer-6', 'user-42', 5,
+    {'filter' => "'price' > context_item[\"price\"]"})
   )
 rescue ResponseError => e
-  #Handle errorneous request => use fallback
+  # Handle errorneous request => use fallback
 rescue ApiTimeout => e
-  #Handle timeout => use fallback
+  # Handle timeout => use fallback
 rescue APIError => e
-  #APIError is parent of both ResponseError and ApiTimeout
+  # APIError is parent of both ResponseError and ApiTimeout
 end
 ```

lib/recombee_api_client.rb

@@ -18,7 +18,7 @@ class RecombeeClient
     include HTTParty
 
     BATCH_MAX_SIZE = 10000
-    USER_AGENT = {'User-Agent' => 'recombee-ruby-api-client/1.6.0'}
+    USER_AGENT = {'User-Agent' => 'recombee-ruby-api-client/2.0.0'}
 
     ##
     #   - +account+ -> Name of your account at Recombee

lib/recombee_api_client/api/item_based_recommendation.rb

@@ -7,6 +7,8 @@ module RecombeeApiClient
   require_relative '../errors'
 
   ##
+  #Deprecated since version 2.0.0. Use RecommendItemsToItem request instead.
+  #
   #Recommends set of items that are somehow related to one given item, *X*. Typical scenario for using item-based recommendation is when user *A* is viewing *X*. Then you may display items to the user that he might be also interested in. Item-recommendation request gives you Top-N such items, optionally taking the target user *A* into account.
   #
   # It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.

lib/recombee_api_client/api/recommend_items_to_item.rb

@@ -7,8 +7,6 @@ module RecombeeApiClient
   require_relative '../errors'
 
   ##
-  #This feature is currently in beta.
-  #
   #Recommends set of items that are somehow related to one given item, *X*. Typical scenario  is when user *A* is viewing *X*. Then you may display items to the user that he might be also interested in. Recommend items to item request gives you Top-N such items, optionally taking the target user *A* into account.
   #
   #It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
@@ -34,8 +32,8 @@ class RecommendItemsToItem < ApiRequest
   #If you insist on not specifying the user, pass `null`
   #(`None`, `nil`, `NULL` etc. depending on language) to *targetUserId*.
   #Do not create some special dummy user for getting recommendations,
-  #as it could cause  mislead the recommendation models,
-  #leading to wrong recommendations.
+  #as it could mislead the recommendation models,
+  #and result in wrong recommendations.
   #
   #For anonymous/unregistered users it is possible to use for example their session ID.
   #
@@ -53,7 +51,7 @@ class RecommendItemsToItem < ApiRequest
   #Example response:
   #```
   #  {
-  #    "recommId": "8ac80708afe9148130528757ebf6aaba",
+  #    "recommId": "0c6189e7-dc1a-429a-b613-192696309361",
   #    "recomms":
   #      [
   #        {
@@ -83,7 +81,7 @@ class RecommendItemsToItem < ApiRequest
   #Example response for `includedProperties=description,price`:
   #```
   #  {
-  #    "recommId": "c7dbfc503d262b80b77b4949ee9855fb",
+  #    "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80",
   #    "recomms": 
   #      [
   #        {

lib/recombee_api_client/api/recommend_items_to_user.rb

@@ -7,8 +7,6 @@ module RecombeeApiClient
   require_relative '../errors'
 
   ##
-  #This feature is currently in beta.
-  #
   #Based on user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for a given user.
   #
   #It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
@@ -33,7 +31,7 @@ class RecommendItemsToUser < ApiRequest
   #Example response:
   #```
   #  {
-  #    "recommId": "1644e7b31759a08480da5f3b0a13045b",
+  #    "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
   #    "recomms": 
   #      [
   #        {
@@ -63,7 +61,7 @@ class RecommendItemsToUser < ApiRequest
   #Example response for `includedProperties=description,price`:
   #```
   #  {
-  #    "recommId": "e3ba43af1a4e59dd08a00adced1729a7",
+  #    "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b",
   #    "recomms":
   #      [
   #        {

lib/recombee_api_client/api/recommend_users_to_item.rb

@@ -7,8 +7,6 @@ module RecombeeApiClient
   require_relative '../errors'
 
   ##
-  #This feature is currently in beta.
-  #
   #Recommend users that are likely to be interested in a given item.
   #
   #It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
@@ -33,7 +31,7 @@ class RecommendUsersToItem < ApiRequest
   #Example response:
   #```
   #  {
-  #    "recommId": "9eeebc318508302529e3241f4570834d",
+  #    "recommId": "039b71dc-b9cc-4645-a84f-62b841eecfce",
   #    "recomms":
   #      [
   #        {
@@ -59,7 +57,7 @@ class RecommendUsersToItem < ApiRequest
   #Example response for `includedProperties=country`:
   #```
   #  {
-  #    "recommId": "d4c826635efc3e01a83470008c5697f1",
+  #    "recommId": "b2b355dd-972a-4728-9c6b-2dc229db0678",
   #    "recomms":
   #      [
   #        {
@@ -95,7 +93,7 @@ def initialize(item_id, count, optional = {})
       @diversity = optional['diversity']
       @expert_settings = optional['expertSettings']
       @optional = optional
-      @timeout = 3000
+      @timeout = 50000
       @ensure_https = false
       @optional.each do |par, _|
         fail UnknownOptionalParameter.new(par) unless ["filter","booster","cascadeCreate","scenario","returnProperties","includedProperties","diversity","expertSettings"].include? par

lib/recombee_api_client/api/recommend_users_to_user.rb

@@ -7,8 +7,6 @@ module RecombeeApiClient
   require_relative '../errors'
 
   ##
-  #This feature is currently in beta.
-  #
   #Get similar users as some given user, based on the user's past interactions (purchases, ratings, etc.) and values of properties.
   #
   #It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
@@ -33,7 +31,7 @@ class RecommendUsersToUser < ApiRequest
   #Example response:
   #```
   #  {
-  #    "recommId": "32fc671480eb29d843e47def43503992",
+  #    "recommId": "9cb9c55d-50ba-4478-84fd-ab456136156e",
   #    "recomms": 
   #      [
   #        {
@@ -59,7 +57,7 @@ class RecommendUsersToUser < ApiRequest
   #Example response for `includedProperties=country`:
   #```
   #  {
-  #    "recommId": "27d81ade643621f45cc6ba5d30d7d683",
+  #    "recommId": "b326d82d-5d57-4b45-b362-c9d6f0895855",
   #    "recomms":
   #      [
   #        {
@@ -104,7 +102,7 @@ def initialize(user_id, count, optional = {})
       @rotation_time = optional['rotationTime']
       @expert_settings = optional['expertSettings']
       @optional = optional
-      @timeout = 3000
+      @timeout = 50000
       @ensure_https = false
       @optional.each do |par, _|
         fail UnknownOptionalParameter.new(par) unless ["filter","booster","cascadeCreate","scenario","returnProperties","includedProperties","diversity","minRelevance","rotationRate","rotationTime","expertSettings"].include? par

lib/recombee_api_client/api/user_based_recommendation.rb

@@ -7,6 +7,8 @@ module RecombeeApiClient
   require_relative '../errors'
 
   ##
+  #Deprecated since version 2.0.0. Use RecommendItemsToUser request instead.
+  #
   #Based on user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for a given user.
   #
   #It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.

lib/recombee_api_client/version.rb

@@ -1,3 +1,3 @@
 module RecombeeApiClient
-  VERSION = '1.6.0'
+  VERSION = '2.0.0'
 end

spec/api/add_entity.rb

@@ -13,7 +13,7 @@
   end
 
   it 'fails with invalid entity id' do
-    req = described_class.new('...not_valid...')
+    req = described_class.new('$$$not_valid$$$')
     expect { @client.send(req) }.to raise_exception { |exception|
        expect(exception).to be_a(RecombeeApiClient::ResponseError)
        expect(exception.status_code).to eq 400