[TRANSLATION ERROR] There are no messages for this key

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:

ParameterMandatoryTypeDescription
tableIdStringID of the table
interactionIdStringID of the interaction that the user has performed
userIdStringID of the user who has performed the interaction
itemIdStringID of the item with which the user has interacted

Fields to be included in the request body:

FieldMandatoryTypeDescription
timestampTimestampUTC timestamp of the interaction as epoch time in milliseconds. The default value is the current time.
valueDoubleValue that indicates the magnitude of the interaction. This parameter is mandatory for every interaction type, except for the unary type.

Response

CodeName
201Created
400Bad Request
401Unauthorized
404Not Found
500Internal 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:

ParameterMandatoryTypeDescription
tableIdStringID of the table
itemIdStringID of the item with which the users interacted
interactionIdStringID of the interaction that the users carried out
filterStringBoolean-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.
limitStringMax. number of rows to be returned
afterIdStringID of the last element of the current page, so the elements to be returned will start with the next ID. Useful for implementing pagination.
sortStringRSQL expression used to sort the result list

Response

CodeName
200OK
400Bad Request
401Unauthorized
404Not Found
429Too Many Requests
500Internal 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:

ParameterMandatoryTypeDescription
tableIdStringID of the table
userIdStringID of the user
interactionIdStringID of the interaction carried out by the user
filterStringBoolean-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.
limitStringMax. number of rows to be returned
afterIdStringID of the last element of the current page, so the elements to be returned will start with the next ID. Useful for implementing pagination.
sortStringRSQL expression used to sort the result list

Response

CodeName
200OK
400Bad Request
401Unauthorized
404Not Found
429Too Many Requests
500Internal 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:

ParameterMandatoryTypeDescription
tableIdStringID of the table
interactionIdStringID of the interactions carried out by the user
userIdStringID of the user who performed the interaction
itemIdStringID of the item with which the user interacted

Fields to be included in the request body:

FieldMandatoryTypeDescription
timestampTimestampUTC timestamp of the interaction as epoch time in milliseconds

Response

CodeName
204No content
400Bad Request
401Unauthorized
404Not Found
500Internal 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}"