User-Item Interactions
This section describes the available methods to manage the interactions that occur between users and items.
Add User-Item Interaction
Add a user interaction.
URL
POST /{tableId}/interactions/{interactionId}/{userId}/{itemId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
interactionId | ✓ | String | ID of the interaction that the user has performed |
userId | ✓ | String | ID of the user who has performed the interaction |
itemId | ✓ | String | ID of the item with which the user has interacted |
Fields to be included in the request body:
Field | Mandatory | Type | Description |
---|---|---|---|
timestamp | Timestamp | UTC timestamp of the interaction as epoch time in milliseconds. The default value is the current time. | |
value | Double | Value that indicates the magnitude of the interaction. This parameter is mandatory for every interaction type, except for the unary type. |
Response
Code | Name |
---|---|
201 | Created |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
500 | Internal Server Error |
Example
Add that user user01
has rated item item01
from the products
table with 4 stars (interaction with ID givestars
).
curl -X POST "https://recom.sherpa.ai/v2/recomm/products/interactions/givestars/user01/item01" \
-H "Content-Type: application/json" \
-H "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H "X-Sherpa-timestamp: 1548084514112" \
-H "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-d "{\"value\":4}"
Get Interactions Over Item
List all the interactions ever carried out over a given item by different users. For a detailed description of filters, please refer to RSQL.
URL
GET /{tableId}/items/{itemId}/{interactionId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
itemId | ✓ | String | ID of the item with which the users interacted |
interactionId | ✓ | String | ID of the interaction that the users carried out |
filter | String | Boolean-returning RSQL expression, which allows you to filter the interaction to be listed. Only the interaction for which the expression is true will be returned. | |
limit | String | Max. number of rows to be returned | |
afterId | String | ID of the last element of the current page, so the elements to be returned will start with the next ID. Useful for implementing pagination. | |
sort | String | RSQL expression used to sort the result list |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
429 | Too Many Requests |
500 | Internal Server Error |
JSON with the filtered user interactions.
Examples
List all 4- or 5-star interactions carried out by users over item01
from the products
table, sorted chronologically.
curl -X GET "https://recom.sherpa.ai/v2/recomm/products/items/item01/givestars?filter=value=ge=4&sort=timestamp==ASC" \
-H "Content-Type: application/json" \
-H "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H "X-Sherpa-timestamp: 1548084514112" \
-H "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H "X-Sherpa-hmac: xxxxyyyyyyy***signature******"
[
{
"userId": "user01",
"timestamp": 1514815652000,
"value": 4
},
{
"userId": "user02",
"timestamp": 1514860987000,
"value": 5
},
{
"userId": "user03",
"timestamp": 1514906718000,
"value": 4
}
]
Get Interactions by User
List all the interactions ever carried out by a given user, over different items. For a detailed description of filters, please refer to RSQL.
URL
GET /{tableId}/users/{userId}/{interactionId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
userId | ✓ | String | ID of the user |
interactionId | ✓ | String | ID of the interaction carried out by the user |
filter | String | Boolean-returning RSQL expression, which allows you to filter the interactions to be listed. Only the interactions for which the expression is true will be returned. | |
limit | String | Max. number of rows to be returned | |
afterId | String | ID of the last element of the current page, so the elements to be returned will start with the next ID. Useful for implementing pagination. | |
sort | String | RSQL expression used to sort the result list |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
429 | Too Many Requests |
500 | Internal Server Error |
JSON with the filtered item interactions.
Examples
List all 4- or 5- star interactions carried out by user01
over items from the products
table, sorted chronologically.
curl -X GET "https://recom.sherpa.ai/v2/recomm/products/users/user01/givestars?filter=value=ge=4&sort=timestamp==ASC" \
-H "Content-Type: application/json" \
-H "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H "X-Sherpa-timestamp: 1548084514112" \
-H "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H "X-Sherpa-hmac: xxxxyyyyyyy***signature******"
[
{
"itemId": "item03",
"timestamp": 1514866318000,
"value": 4
},
{
"itemId": "item01",
"timestamp": 1514915652000,
"value": 4
}
]
Delete User-Item Interaction
Delete an existing interaction uniquely specified by the ID of the user, the ID of the item, and the timestamp.
URL
DELETE /{tableId}/interactions/{interactionId}/{userId}/{itemId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
interactionId | ✓ | String | ID of the interactions carried out by the user |
userId | ✓ | String | ID of the user who performed the interaction |
itemId | ✓ | String | ID of the item with which the user interacted |
Fields to be included in the request body:
Field | Mandatory | Type | Description |
---|---|---|---|
timestamp | ✓ | Timestamp | UTC timestamp of the interaction as epoch time in milliseconds |
Response
Code | Name |
---|---|
204 | No content |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
500 | Internal Server Error |
Example
Remove thegivestars
interaction by user01
over item01
from the products
table with the timestamp 1514915652000.
curl -X DELETE "https://recom.sherpa.ai/v2/recomm/products/interactions/givestars/user01/item01" \
-H "Content-Type: application/json" \
-H "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H "X-Sherpa-timestamp: 1548084514112" \
-H "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H "X-Sherpa-hmac: xxxxyyyyyyy***signature******"
-d "{\"timestamp\":1514915652000}"