Item Catalog
This section describes the available methods for building an item catalog. Items are organized in tables and can have any number of attributes. Moreover, users will be able to interact with items, following some defined interactions.
None of the IDs defined here can contain any of the following characters: [\$./<>:"#%&*?|{}]
.
Tables
All the data in the Sherpa.ai Custom Content Recommendation API must by organized in tables, which constitute the item catalog. The following methods allow management of the tables.
Add Table
Add a table. It also allows the ability to specify which recommender engine to use, when generating recommendations (see Recommendations for further details).
You can also add the attributes for modeling the data in your tables.
URL
POST /tables
Parameters
Fields to be included in the request body:
Field | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table to be created |
engine | String | Engine to use for the recommendations. One of the following: content_based : Uses content-based filtering, analyzing long text attributes. hybrid : Uses a combination of collaborative and content-based filtering, analyzing numerical and categorical attributes. | |
attributes | Array Attributes | Attributes are used for modeling the data in your tables. See Attributes. |
Response
Code | Name |
---|---|
201 | Created |
400 | Bad Request |
401 | Unauthorized |
409 | Conflict |
423 | Locked |
500 | Internal Server Error |
503 | Service Unavailable |
Example
Add a table that contains the product catalog and choose content_based
engine for the recommendations.
curl -X POST "https://recom.sherpa.ai/v2/recomm/tables/products" \
-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 "{\"tableId\":\"products\",\"engine\":\"content_based\", \"attributes\": [{ \"attributeId\":\"name\", \"type\" : \"string\"}]}"
Update Table
Update the recommender engine associated with a table.
URL
PATCH /tables/{tableId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table to be updated |
Fields to be included in the request body:
Field | Mandatory | Type | Description |
---|---|---|---|
engine | ✓ | String | Engine to use for the recommendations. One of the following: content_based - Uses content-based filtering, analyzing long text attributes. hybrid - Uses a combination of collaborative and content-based filtering, analyzing numerical and categorical attributes. |
Response
Code | Name |
---|---|
204 | No Content |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
500 | Internal Server Error |
503 | Service Unavailable |
Example
Update the recommender engine of the products
table to hybrid
.
curl -X PATCH "https://recom.sherpa.ai/v2/recomm/tables/products?engine=hybrid" \
-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 "{\"engine\":\"hybrid\"}"
Get Table
Get the recommender engine associated with a table.
URL
GET /tables/{tableId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
429 | Too Many Requests |
500 | Internal Server Error |
503 | Service Unavailable |
JSON with the information of the table.
Example
Get the recommender engine of the products
table.
curl -X GET "https://recom.sherpa.ai/v2/recomm/tables/products" \
-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******"
{
"tableId": "products",
"engine": "hybrid"
}
List Tables
Get a list of tables of items currently present in the catalog.
URL
GET /tables
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
429 | Too Many Requests |
500 | Internal Server Error |
503 | Service Unavailable |
JSON with the list of tables.
Example
Get all the tables.
curl -X GET "https://recom.sherpa.ai/v2/recomm/tables" \
-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******"
[
"restaurants",
"products"
]
Delete Table
Delete a table. All attributes, items, and interactions dependent on the table will also be deleted. Batch upload processes will be removed, as well.
URL
DELETE /tables/{tableId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table to be deleted |
Response
Code | Name |
---|---|
204 | No content |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
423 | Locked |
500 | Internal Server Error |
503 | Service Unavailable |
Example
Delete the products
table.
curl -X DELETE "https://recom.sherpa.ai/v2/recomm/tables/products" \
-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******"
Attributes
Attributes are used for modeling the data in your tables. They may be thought of as columns in a relational database table. The following methods allow the management of item attributes.
Default Attributes
All tables created in the catalog will contain the following attributes by default:
Field | Type | Description |
---|---|---|
expiration | Timestamp | UTC timestamp of item expiration as ISO8601-1 pattern or UTC epoch time. The default value is empty, so the items never expire. |
Whenever a new item is imported, these fields are automatically attached, if they are not given.
Add Item Attribute
Add an attribute to the table.
URL
POST /{tableId}/attributes
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
Fields to be included in the request body:
Field | Mandatory | Type | Description |
---|---|---|---|
attributes | ✓ | Array Attributes | Attributes are used for modeling the data in your tables. See Attributes. |
Attribute model
Field | Mandatory | Type | Description |
---|---|---|---|
attributeId | ✓ | String | ID of the attribute to be created |
type | ✓ | String | Type of attribute to be created. One of the following: int: Signed integer number double: Floating point number. It uses 64-bit base-2 format (IEEE 754 standard). string: UTF-8 string boolean: true / false timestamp: Value representing date and time as ISO8601-1 pattern or UTC epoch time set: Set of strings category: An attribute that can take on one of a limited, and usually fixed, number of possible values, assigning each individual attribute to a particular group or nominal category on the basis of some qualitative property. categoryList: An attribute that can take on one or more than one of a limited, and usually fixed, number of possible values, assigning each individual attribute to one or more than one particular group or nominal category, on the basis of some qualitative property. image: URL of an image (jpeg, png or gif) imageList: List of URLs that refer to images |
indexed | Boolean | Set this attribute as indexed. The default value is false. | |
values | Array | Values that an attribute of categorical type can have. |
Indexed Attributes
Indexed attributes allow fast filtering of recommendation queries. The recommendation queries whose filter and sort statements are composed only of indexed attributes will take less time to process and, therefore, will be delivered faster. A maximum of 32 attributes per table can be declared as indexed. Attributes with type SET
or IMAGELIST
cannot be declared as indexed.
Response
Code | Name |
---|---|
201 | Created |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
423 | Locked |
409 | Conflict |
500 | Internal Server Error |
503 | Service Unavailable |
Example
Add the price, currency and material of a product, which price is a double type, currency is string type and material is category type, as an attributes for products
.
curl -X POST "https://recom.sherpa.ai/v2/recomm/products/attributes" \
-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 "{\"attributes\":[{\"attributeId\":\"price\",\"type\":\"double\"},{\"attributeId\":\"currency\",\"type\":\"string\"},{\"attributeId\":\"material\",\"type\":\"category\",\"values\":[\"plastic\",\"steel\",\"aluminium\"]}]}"
Update Item Attribute
Update values that an item attribute of categorical type can have.
URL
PATCH /{tableId}/attributes/{attributeId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
attributeId | ✓ | String | ID of the attribute |
Fields to be included in the request body:
Field | Mandatory | Type | Description |
---|---|---|---|
values | ✓ | Array | Values that an attribute of categorical type can have. |
Response
Code | Name |
---|---|
204 | No Content |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
423 | Locked |
500 | Internal Server Error |
503 | Service Unavailable |
Example
Update the material attribute values.
curl -X PATCH "https://recom.sherpa.ai/v2/recomm/products/attributes/material" \
-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 "{\"values\":[\"plastic\",\"steel\",\"aluminium\"]}"
Get Item Attribute Info
Get information about a specified attribute.
URL
GET /{tableId}/attributes/{attributeId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
attributeId | ✓ | String | ID of the attribute about which the information is to be retrieved |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
429 | Too Many Requests |
500 | Internal Server Error |
503 | Service Unavailable |
JSON with the details of the attribute.
Example
Get information about the price
attribute.
curl -X GET "https://recom.sherpa.ai/v2/recomm/products/attributes/price" \
-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******"
{
"attributeId": "price",
"type": "double"
}
List Item Attributes
Get the list of all the attributes in a table.
URL
GET /{tableId}/attributes
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
429 | Too Many Requests |
500 | Internal Server Error |
503 | Service Unavailable |
JSON with the attributes (and details) of the table.
Example
Get the attributes defined for the products
table.
curl -X GET "https://recom.sherpa.ai/v2/recomm/products/attributes" \
-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******"
[
{
"attributeId": "name",
"type": "string"
},
{
"attributeId": "description",
"type": "string"
},
{
"attributeId": "expiration",
"type": "timestamp"
},
{
"attributeId": "quantity",
"type": "int"
},
{
"attributeId": "origin",
"type": "string"
},
{
"attributeId": "price",
"type": "double"
}
]
Delete Item Attribute
Delete a table attribute. Deleting an attribute is equivalent to removing a column from the table of items. Therefore, attribute values are also removed.
URL
DELETE /{tableId}/attributes/{attributeId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table. |
attributeId | ✓ | String | ID of the attribute to be deleted. |
Response
Code | Name |
---|---|
204 | No content |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
423 | Locked |
500 | Internal Server Error |
503 | Service Unavailable |
Example
Delete the price
attribute from the products
table.
curl -X DELETE "https://recom.sherpa.ai/v2/recomm/products/attributes/price" \
-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******"
Interactions
Interactions are used for modeling the activity between the users and the items in your tables. The following method allows adding, deleting, and listing the catalog of interactions for each table.
Add Interaction
Add an interaction to a table.
URL
POST /{tableId}/interactions
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
Fields to be included in the request body:
Field | Mandatory | Type | Description |
---|---|---|---|
interactionId | ✓ | String | ID of the interaction to be created |
weight | ✓ | Double | Value in the range of 0.0 to 10.0 that quantifies the relevance of the interaction |
cumulative | ✓ | Boolean | Whether multiple interactions of this kind can be cumulative, such as minutes spent reading an article or amount of claps; this can be helpful for some recommendation engines. |
type | ✓ | String | Type of value of each user-item-interaction related to an interaction. One of the following:unary - Interactions with one possible value. The values for maxValue and minValue must be the same. Default will be 1 for both values. binary - Interactions with two possible values. Default values will be 0 and 1. categorical - A set of finite integers in a range (both ends of the range are included). Defining a maxValue and minValue is mandatory. Both values must be integers. continuous - Any kind of decimal number between minValue and maxValue (both ends of the range are included). Default values will be -∞ and ∞. |
polarity | String | Whether the interaction expresses a user's interest in the item (recommendations of similar items are desirable) or disinterest (recommendations of similar items should be avoided). One of the following: positive (default) or negative. | |
maxValue | Double | The highest possible value for each user-item-interaction related to this interaction. Must be greater than or equal to minValue. | |
minValue | Double | The lowest possible value for each user-item-interaction related to this interaction. Must be less than or equal to maxValue. |
Response
Code | Name |
---|---|
201 | Created |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
423 | Locked |
409 | Conflict |
500 | Internal Server Error |
503 | Service Unavailable |
Example
Add the purchase
interaction, with 1.0 weight, to items in products
.
curl -X POST "https://recom.sherpa.ai/v2/recomm/products/interactions" \
-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 "{\"interactionId\":\"purchase\",\"weight\":1.0,\"cumulative\":true,\"type\":\"continuous\",\"minValue\":0.0}"
Update Interaction
Update the weight and interactionId of an existing interaction.
URL
PATCH /{tableId}/interactions/{interactionId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
interactionId | ✓ | String | ID of the interaction to be updated |
Fields to be included in the request body:
Field | Mandatory | Type | Description |
---|---|---|---|
weight | Double | Updated value in the 0.0 to 10.0 range that quantifies the relevance of the interaction | |
interactionId | String | New ID of the interaction |
It is mandatory that at least one of the body fields is sent.
Response
Code | Name |
---|---|
202 | Accepted |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
500 | Internal Server Error |
503 | Service Unavailable |
Example
Update the purchase
interaction weight and interactionId of the products
table.
curl -X PATCH "https://recom.sherpa.ai/v2/recomm/products/interactions/purchase" \
-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 "{\"weight\":5.0 , \"interactionId\": \"acquisition\"}"
Get Interaction Info
Get information about a specified interaction.
URL
GET /{tableId}/interactions/{interactionId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
interactionId | ✓ | String | ID of the interaction about which the information is to be retrieved |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
429 | Too Many Requests |
500 | Internal Server Error |
503 | Service Unavailable |
JSON with the details of the interaction.
Example
Get information about the purchase
attribute.
curl -X GET "https://recom.sherpa.ai/v2/recomm/products/interactions/purchase" \
-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******"
{
"interactionId": "purchase",
"type" : "continuous",
"cumulative" : true,
"weight" : 5.0,
"minValue" : 0.0
}
List Interactions
Get the list of all possible interactions in a table.
URL
GET /{tableId}/interactions
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
500 | Internal Server Error |
503 | Service Unavailable |
JSON with the interactions (and weights) of the table.
Example
List all possible interactions over items from the products
table.
curl -X GET "https://recom.sherpa.ai/v2/recomm/products/interactions" \
-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******"
[
{
"interactionId": "givestars",
"type" : "categorical",
"cumulative" : false,
"weight" : 2.3,
"minValue" : 1,
"maxValue" : 5,
},
{
"interactionId": "purchase",
"type" : "continuous",
"cumulative" : true,
"weight" : 5.0,
"minValue" : 0.0
}
]
Delete Interaction
Delete an interaction from a table. Every user-item-interaction
of this type will also be deleted.
URL
DELETE /{tableId}/interactions/{interactionId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
interactionId | ✓ | String | ID of the interaction to be deleted |
Response
Code | Name |
---|---|
204 | No content |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
423 | Locked |
500 | Internal Server Error |
503 | Service Unavailable |
Example
Delete the givestars
interaction from the products
table.
curl -X DELETE "https://recom.sherpa.ai/v2/recomm/products/interactions/givestars" \
-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******"
Delete All Interactions
Delete all interactions from a table. Every user-item-interactions
will be deleted.
URL
DELETE /{tableId}/interactions
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
Response
Code | Name |
---|---|
204 | No content |
400 | Bad Request |
401 | Unauthorized |
423 | Locked |
500 | Internal Server Error |
503 | Service Unavailable |
Example
Delete the all interactions from the products
table.
curl -X DELETE "https://recom.sherpa.ai/v2/recomm/products/interactions" \
-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******"
Items
The following methods allow you to maintain the set of items in the catalog.
Add Item
Add an item to a table. This will also add the values of the attributes, which need to be previously defined (see Item Attributes).
URL
POST /{tableId}/items
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
Fields to be included in the request body:
Field | Mandatory | Type | Description |
---|---|---|---|
itemId | ✓ | String | ID of the item to be created |
Other attributes | The values for the individual attributes |
Response
Code | Name |
---|---|
201 | Created |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
409 | Conflict |
500 | Internal Server Error |
503 | Service Unavailable |
Example
Add apples to products
. There are 10 apples and the price is 1.63.
curl -X POST "https://recom.sherpa.ai/v2/recomm/products/items/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 "{\"itemId\":\"item01\",\"name\":\"apple\",\"quantity\":10,\"price\":1.63}"
Get Item Info
Get information about the specified item.
URL
GET /{tableId}/items/{itemId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
itemId | ✓ | String | ID of the item about which information is to be retrieved |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
429 | Too Many Requests |
500 | Internal Server Error |
503 | Service Unavailable |
JSON with the value of the attributes of the item.
Example
Get information about apples, which are identified as item01
.
curl -X GET "https://recom.sherpa.ai/v2/recomm/products/items/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******"
{
"name": "apple",
"description": "",
"quantity": 10,
"price": 1.63
}
Update Item
Update the value of the attributes of an existing item.
URL
PATCH /{tableId}/items/{itemId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
itemId | ✓ | String | ID of the item to be updated |
Fields to be included in the request body:
Field | Mandatory | Type | Description |
---|---|---|---|
Other attributes | The values for the individual attributes |
Response
Code | Name |
---|---|
204 | No Content |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
500 | Internal Server Error |
503 | Service Unavailable |
Example
Update the price of the apples, which are identified as item01
, to 1.75. Include their origin (France), too.
curl -X PATCH "https://recom.sherpa.ai/v2/recomm/products/items/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 "{\"price\":1.75,\"origin\":\"France\"}"
List Items
Get a list of IDs of items currently present in a table and, optionally, their attributes. For a detailed description of filters, please refer to RSQL.
URL
GET /{tableId}/items
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
attributes | String | Allows the ability to specify which attributes will be returned. The set must be enclosed in parentheses. | |
filter | String | Boolean-returning RSQL expression, which allows you to filter the items to be listed. Only the items 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 |
503 | Service Unavailable |
JSON with the filtered items.
Example
Get the names and prices of the two items with the highest price below 1.0, sorted by name.
curl -X GET "https://recom.sherpa.ai/v2/recomm/products/items?attributes=("name","price")&filter=price=lt=1.0&limit=2&sort=name==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",
"name":"banana",
"price":0.92
},
{
"itemId":"item02",
"name":"orange",
"price":0.78
}
]
Get only the IDs of those same items.
curl -X GET "https://recom.sherpa.ai/v2/recomm/products/items?&filter=price=lt=1.0&limit=2&sort=name==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******"
[
"item03",
"item02"
]
Delete All Items
Delete all items. Every attribute value and user-item-interaction
associated with the items will also be deleted.
URL
DELETE /{tableId}/items
Response
Code | Name |
---|---|
202 | Accepted |
400 | Bad Request |
401 | Unauthorized |
423 | Locked |
500 | Internal Server Error |
503 | Service Unavailable |
Example
Remove all items from the products
table.
curl -X DELETE "https://recom.sherpa.ai/v2/recomm/products/items" \
-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******"
Delete Item
Delete an item from a table. Every attribute value and user-item-interaction
associated with the item will also be deleted.
URL
DELETE /{tableId}/items/{itemId}
Parameters
Field | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
itemId | ✓ | String | ID of the item to be deleted |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
500 | Internal Server Error |
503 | Service Unavailable |
Example
Remove apples, which are identified as item01
, from products
.
curl -X DELETE "https://recom.sherpa.ai/v2/recomm/products/items/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******"