Support RecommendNextItems endpoint

Author: OndraFiedler

README.md

@@ -13,7 +13,7 @@ The client is available in the [Maven Central Repository](https://mvnrepository.
     <dependency>
         <groupId>com.recombee</groupId>
         <artifactId>api-client</artifactId>
-        <version>3.0.0</version>
+        <version>3.1.0</version>
     </dependency>
 ```
 
@@ -40,7 +40,7 @@ public class BasicExample {
 
         RecombeeClient client = new RecombeeClient("--my-database-id--", "--db-private-token--");
         try {
-            client.send(new ResetDatabase());
+
             final int NUM = 100;
             // Generate some random purchases of items by users
             final double PROBABILITY_PURCHASED = 0.1;
@@ -64,6 +64,11 @@ public class BasicExample {
             System.out.println("Recommended items:");
             for(Recommendation rec: recommendationResponse) System.out.println(rec.getId());
 
+            // User scrolled down - get next 3 recommended items
+            recommendationResponse = client.send(new RecommendNextItems(recommendationResponse.getRecommId(), 3));
+            System.out.println("Next recommended items:");
+            for(Recommendation rec: recommendationResponse) System.out.println(rec.getId());
+
         } catch (ApiException e) {
             e.printStackTrace();
             //use fallback

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.recombee</groupId>
     <artifactId>api-client</artifactId>
-    <version>3.0.0</version>
+    <version>3.1.0</version>
     <name>Recombee API Client</name>
     <description>A client library for easy use of the Recombee recommendation API</description>
     <url>http://recombee.com</url>
@@ -45,17 +45,17 @@
         <dependency>
             <groupId>com.fasterxml.jackson.core</groupId>
             <artifactId>jackson-core</artifactId>
-            <version>2.9.10</version>
+            <version>2.12.1</version>
         </dependency>
         <dependency>
             <groupId>com.fasterxml.jackson.core</groupId>
             <artifactId>jackson-databind</artifactId>
-            <version>2.9.10.1</version>
+            <version>2.12.1</version>
         </dependency>
         <dependency>
             <groupId>junit</groupId>
             <artifactId>junit</artifactId>
-            <version>4.12</version>
+            <version>4.13.1</version>
         </dependency>
         <dependency>
             <groupId>commons-lang</groupId>

src/main/java/com/recombee/api_client/RecombeeClient.java

@@ -1,6 +1,7 @@
 package com.recombee.api_client;
 
 import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.DeserializationFeature;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.core.type.TypeReference;
 
@@ -64,8 +65,9 @@
 import com.recombee.api_client.api_requests.ListItemViewPortions;
 import com.recombee.api_client.api_requests.ListUserViewPortions;
 import com.recombee.api_client.api_requests.RecommendItemsToUser;
-import com.recombee.api_client.api_requests.RecommendUsersToUser;
 import com.recombee.api_client.api_requests.RecommendItemsToItem;
+import com.recombee.api_client.api_requests.RecommendNextItems;
+import com.recombee.api_client.api_requests.RecommendUsersToUser;
 import com.recombee.api_client.api_requests.RecommendUsersToItem;
 import com.recombee.api_client.api_requests.SearchItems;
 import com.recombee.api_client.api_requests.UserBasedRecommendation;
@@ -86,7 +88,7 @@ public class RecombeeClient {
 
     final int BATCH_MAX_SIZE = 10000; //Maximal number of requests within one batch request
 
-    final String USER_AGENT = "recombee-java-api-client/3.0.0";
+    final String USER_AGENT = "recombee-java-api-client/3.1.0";
 
     private final OkHttpClient httpClient = new OkHttpClient();
 
@@ -96,6 +98,7 @@ public RecombeeClient(String databaseId, String token) {
         this.mapper = new ObjectMapper();
         SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
         this.mapper.setDateFormat(df);
+        this.mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
 
         if (System.getenv("RAPI_URI") != null)
             this.baseUri = System.getenv("RAPI_URI");
@@ -325,7 +328,7 @@ public RecommendationResponse send(RecommendItemsToUser request) throws ApiExcep
          return null;
     }
 
-    public RecommendationResponse send(RecommendUsersToUser request) throws ApiException {
+    public RecommendationResponse send(RecommendItemsToItem request) throws ApiException {
         String responseStr = sendRequest(request);
         try {
             return this.mapper.readValue(responseStr, RecommendationResponse.class);
@@ -335,7 +338,17 @@ public RecommendationResponse send(RecommendUsersToUser request) throws ApiExcep
          return null;
     }
 
-    public RecommendationResponse send(RecommendItemsToItem request) throws ApiException {
+    public RecommendationResponse send(RecommendNextItems request) throws ApiException {
+        String responseStr = sendRequest(request);
+        try {
+            return this.mapper.readValue(responseStr, RecommendationResponse.class);
+        } catch (IOException e) {
+            e.printStackTrace();
+         }
+         return null;
+    }
+
+    public RecommendationResponse send(RecommendUsersToUser request) throws ApiException {
         String responseStr = sendRequest(request);
         try {
             return this.mapper.readValue(responseStr, RecommendationResponse.class);
@@ -452,7 +465,8 @@ else if (request instanceof ListUsers)
                     else if ((request instanceof RecommendItemsToUser) ||
                             (request instanceof RecommendUsersToUser) ||
                             (request instanceof RecommendItemsToItem) ||
-                            (request instanceof RecommendUsersToItem))
+                            (request instanceof RecommendUsersToItem) ||
+                            (request instanceof RecommendNextItems))
                     {
                         parsedResponse = mapper.convertValue(parsedResponse, RecommendationResponse.class);
                     }
@@ -714,6 +728,7 @@ protected Recommendation[] sendDeprecatedRecomm(Request request) throws ApiExcep
         String responseStr = sendRequest(request);
 
         try {
+            this.mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, true); // Check exact match
             return this.mapper.readValue(responseStr, Recommendation[].class);
         } catch (IOException e) {
             //might have failed because it returned also the item properties
@@ -728,14 +743,18 @@ protected Recommendation[] sendDeprecatedRecomm(Request request) throws ApiExcep
             } catch (IOException e2) {
                 e2.printStackTrace();
             }
-         }
-         return null;
+        }
+        finally {
+            this.mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
+        }
+        return null;
     }
 
     public Item[] send(ListItems request) throws ApiException {
         String responseStr = sendRequest(request);
 
         try {
+            this.mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, true); // Check exact match
             return this.mapper.readValue(responseStr, Item[].class);
         } catch (IOException e) {
             //might have failed because it returned also the item properties
@@ -750,15 +769,19 @@ public Item[] send(ListItems request) throws ApiException {
             } catch (IOException e2) {
                 e2.printStackTrace();
             }
-         }
-         return null;
+        }
+        finally {
+            this.mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
+        }
+        return null;
     }
 
 
     public User[] send(ListUsers request) throws ApiException {
         String responseStr = sendRequest(request);
 
         try {
+            this.mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, true); // Check exact match
             return this.mapper.readValue(responseStr, User[].class);
         } catch (IOException e) {
             //might have failed because it returned also the user properties
@@ -773,8 +796,11 @@ public User[] send(ListUsers request) throws ApiException {
             } catch (IOException e2) {
                 e2.printStackTrace();
             }
-         }
-         return null;
+        }
+        finally {
+            this.mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
+        }
+        return null;
     }
 
     public String send(Request request) throws ApiException {

src/main/java/com/recombee/api_client/api_requests/RecommendItemsToItem.java

@@ -13,8 +13,11 @@
 
 /**
  * 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.
+ * The returned items are sorted by relevance (first item being the most relevant).
+ * Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to:
+ * - Let Recombee know that this recommendation was successful (e.g. user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui.html#reported-metrics).
+ * - Get subsequent recommended items when the user scrolls down (*infinite scroll*) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api.html#recommend-next-items).
  * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
- * The returned items are sorted by relevancy (first item being the most relevant).
  */
 public class RecommendItemsToItem extends Request {
 
@@ -78,7 +81,8 @@ public class RecommendItemsToItem extends Request {
      *             "url": "myshop.com/mixer-42"
      *           }
      *         }
-     *       ]
+     *       ],
+     *     "numberNextRecommsCalls": 0
      *   }
      * ```
      */
@@ -105,7 +109,8 @@ public class RecommendItemsToItem extends Request {
      *             "price": 39
      *           }
      *         }
-     *       ]
+     *       ],
+     *     "numberNextRecommsCalls": 0
      *   }
      * ```
      */
@@ -136,7 +141,7 @@ public class RecommendItemsToItem extends Request {
      */
     protected Double diversity;
     /**
-     * **Expert option** If the *targetUserId* is provided:  Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevancy, and may return less than *count* items when there is not enough data to fulfill it.
+     * **Expert option** If the *targetUserId* is provided:  Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevance, and may return less than *count* items when there is not enough data to fulfill it.
      */
     protected String minRelevance;
     /**
@@ -225,7 +230,8 @@ public RecommendItemsToItem setCascadeCreate(boolean cascadeCreate) {
      *             "url": "myshop.com/mixer-42"
      *           }
      *         }
-     *       ]
+     *       ],
+     *     "numberNextRecommsCalls": 0
      *   }
      * ```
      */
@@ -256,7 +262,8 @@ public RecommendItemsToItem setReturnProperties(boolean returnProperties) {
      *             "price": 39
      *           }
      *         }
-     *       ]
+     *       ],
+     *     "numberNextRecommsCalls": 0
      *   }
      * ```
      */
@@ -311,7 +318,7 @@ public RecommendItemsToItem setDiversity(double diversity) {
     }
 
     /**
-     * @param minRelevance **Expert option** If the *targetUserId* is provided:  Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevancy, and may return less than *count* items when there is not enough data to fulfill it.
+     * @param minRelevance **Expert option** If the *targetUserId* is provided:  Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevance, and may return less than *count* items when there is not enough data to fulfill it.
      */
     public RecommendItemsToItem setMinRelevance(String minRelevance) {
          this.minRelevance = minRelevance;

src/main/java/com/recombee/api_client/api_requests/RecommendItemsToUser.java

@@ -14,8 +14,11 @@
 /**
  * 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.
  * The most typical use cases are recommendations at homepage, in some "Picked just for you" section or in email.
+ * The returned items are sorted by relevance (first item being the most relevant).
+ * Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to:
+ * - Let Recombee know that this recommendation was successful (e.g. user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui.html#reported-metrics).
+ * - Get subsequent recommended items when the user scrolls down (*infinite scroll*) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api.html#recommend-next-items).
  * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
- * The returned items are sorted by relevancy (first item being the most relevant).
  */
 public class RecommendItemsToUser extends Request {
 
@@ -63,7 +66,8 @@ public class RecommendItemsToUser extends Request {
      *             "url": "myshop.com/mixer-42"
      *           }
      *         }
-     *       ]
+     *       ],
+     *      "numberNextRecommsCalls": 0
      *   }
      * ```
      */
@@ -90,7 +94,8 @@ public class RecommendItemsToUser extends Request {
      *             "price": 39
      *           }
      *         }
-     *       ]
+     *       ],
+     *     "numberNextRecommsCalls": 0
      *   }
      * ```
      */
@@ -117,7 +122,7 @@ public class RecommendItemsToUser extends Request {
      */
     protected Double diversity;
     /**
-     * **Expert option** Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevancy, and may return less than *count* items when there is not enough data to fulfill it.
+     * **Expert option** Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevance, and may return less than *count* items when there is not enough data to fulfill it.
      */
     protected String minRelevance;
     /**
@@ -192,7 +197,8 @@ public RecommendItemsToUser setCascadeCreate(boolean cascadeCreate) {
      *             "url": "myshop.com/mixer-42"
      *           }
      *         }
-     *       ]
+     *       ],
+     *      "numberNextRecommsCalls": 0
      *   }
      * ```
      */
@@ -223,7 +229,8 @@ public RecommendItemsToUser setReturnProperties(boolean returnProperties) {
      *             "price": 39
      *           }
      *         }
-     *       ]
+     *       ],
+     *     "numberNextRecommsCalls": 0
      *   }
      * ```
      */
@@ -270,7 +277,7 @@ public RecommendItemsToUser setDiversity(double diversity) {
     }
 
     /**
-     * @param minRelevance **Expert option** Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevancy, and may return less than *count* items when there is not enough data to fulfill it.
+     * @param minRelevance **Expert option** Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevance, and may return less than *count* items when there is not enough data to fulfill it.
      */
     public RecommendItemsToUser setMinRelevance(String minRelevance) {
          this.minRelevance = minRelevance;