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}"