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. It must be between 1 and 15 characters.
engines	✓	Engines Object	Engines to use for the recommendations.
attributes		Array of Attributes	Attributes are used for modeling the data in your tables. See Attributes.

Note: The engine parameter is deprecated. Use engines and the default option to replace it.

The engines object can contain the following fields:

Field	Type	Description
default	String	Default engine, used when there is not a specific one assigned. It is a mandatory field, unless the other four fields are included.
items-to-user	String	Engine used for recommendations of items to a user
users-to-user	String	Engine used for recommendations of users to a user
users-to-item	String	Engine used for recommendations of users to a item
items-to-item	String	Engine used for recommendations of items to a item

Each of those fields can take one of the following values:

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.
fm: Uses a combination of collaborative and content-based filtering, analyzing numerical and categorical attributes and tags.
isvd: Uses collaborative filtering, analizing unary interactions.
popular: Uses unique user-item interaction counts.
ensemble: Uses a weighted combination of the previous engines as per setup.

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\",\"engines\":{\"default\":\"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
engines	✓	Engines Object	Engines to use for the recommendations. See Tables.

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"  \
-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  "{\"engines\":{\"default\":\"content_based\"}}"

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

Query parameters:

Parameter	Mandatory	Type	Description
trainConfig		Boolean	If true, training status for each interaction will be added to response on `trainConfig` node

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.

If training status is requested, trainConfig node will be included, which is a list of each interaction training configuration information.

Field	Type	Description
interactionId	String	Interaction ID
engineConfig	Array	Array with each engine configuration information used for interaction training

Each engine training configuration for an interaction will have:

Field	Type	Description
engine	String	Engine name
timestamp	Timestamp	Trained completed stamp
configuration	Map<String,Object>	Configuration object used for training. See training configuration.

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",
    "engines": {
        "default": "hybrid"
    }
}

Example 2
Get the recommender engine of the products table, with current interaction training configuration.

curl -X GET "https://recom.sherpa.ai/v2/recomm/tables/products?trainConfig=true"  \
-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",
    "engines": {
        "default": "hybrid"
    },
    "trainConfig": [
        {
            "interactionId": "rating",
            "engineConfig": [
                {
                    "engine": "content_based",
                    "timestamp": "2021-03-15T18:48:58.765",
                    "configuration": {
                        "before": "1615244400000",
                        "after": "1612825200000",
                        "userAttributes": "[attribute1, attribute2]",
                        "userFilter": "attribute3==1",
                        "itemFilter": "attribute4==0"
                    }
                },
                {
                    "engine": "hybrid",
                    "timestamp": "2021-03-15T18:28:19.026",
                    "configuration": {
                        "before": "1615244400000",
                        "after": "1612825200000",
                        "userFilter": "attribute3==1",
                        "itemFilter": "attribute4==0"
                    }
                }
            ]
        }
      ]
    }

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