User Catalog

This section describes the available methods for building the user catalog.

None of the IDs defined here can contain any of the following characters: [\$./<>:"#%&*?|{}].

Attributes

User attributes are used for modeling users. The following methods allow the definition of user properties. The properties may be thought of as columns in a relational database table.

Add User Attribute

Add a user attribute.

URL
POST /users/attributes

Parameters

Fields to be included in the request body:

FieldMandatoryTypeDescription
attributeIdStringID of the attribute to be created
typeStringType 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
categorical - 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.
image - URL of an image (jpeg, png, or gif)
imageList - List of URLs that refer to images
indexedBooleanSet this attribute as indexed. The default value is false.

Indexed attributes
Indexed attributes allow fast filtering of recommendation queries. The recommendation queries whose filter and sort statements are composed of only by indexed attributes will take less time to process and, therefore, will be delivered faster. You can declare a maximum of 32 user attributes as indexed. Attributes of type SET or IMAGELIST can not be declared as indexed.

Response

CodeName
201Created
400Bad Request
401Unauthorized
409Conflict
423Locked
500Internal Server Error
503Service Unavailable

Example
Add the age of a user, which is an integer, as an attribute for users.

curl -X POST "https://recom.sherpa.ai/v2/recomm/users/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  "{\"attributeId\":\"age\",\"type\":\"int\"}"

Get User Attribute Info

Get information about a specified user attribute.

URL
GET /users/attributes/{attributeId}

Parameters

URL parameters:

ParameterMandatoryTypeDescription
attributeIdStringID of the attribute about which the information is to be retrieved

Response

CodeName
200OK
400Bad Request
401Unauthorized
404Not Found
429Too Many Requests
500Internal Server Error
503Service Unavailable

JSON with the details of the attribute.

Example
Get information about the attribute age.

curl -X GET "https://recom.sherpa.ai/v2/recomm/users/attributes/age" \
-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": "age",
    "type": "int"
}

List User Attributes

Get the list of all the user attributes.

URL
GET /users/attributes

Response

CodeName
200OK
400Bad Request
401Unauthorized
429Too Many Requests
500Internal Server Error
503Service Unavailable

JSON with the attributes (and details) of users.

Example
Get the attributes defined for users.

curl -X GET "https://recom.sherpa.ai/v2/recomm/users/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": "interests",
        "type": "set"
    },
    {
        "attributeId": "name",
        "type": "string"
    },
    {
        "attributeId": "age",
        "type": "int"
    },
    {
        "attributeId": "country",
        "type": "string"
    }
]

Delete User Attribute

Delete a user attribute.

URL
DELETE /users/attributes/{attributeId}

Parameters

URL parameters:

FieldMandatoryTypeDescription
attributeIdStringID of the attribute to be deleted

Response

CodeName
202Accepted
400Bad Request
401Unauthorized
404Not Found
423Locked
500Internal Server Error
503Service Unavailable

Example
Delete the users' age attribute.

curl -X DELETE "https://recom.sherpa.ai/v2/recomm/users/attributes/age" \
-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******"

Users

The following methods allow you to manage your users.

Add User

Add a user and their attributes. This will also add the values of the attributes, which must be previously defined (see User Attributes)

URL
POST /users

Parameters

Fields to be included in the request body:

FieldMandatoryTypeDescription
userIdStringID of the user to be created
Other attributesThe values for the individual attributes

Response

CodeName
201Created
400Bad Request
401Unauthorized
409Conflict
500Internal Server Error
503Service Unavailable

Example
Add the 35-year-old user Katherine Johnson, who is interested in science, technology, and travel.

curl -X POST "https://recom.sherpa.ai/v2/recomm/users" \
-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 "{\"userId\":\"user01\",\"name\":\"Katherine Johnson\",\"interests\":[\"science\",\"technology\",\"travel\"],\"age\":35}"

Get User Info

Get information about the specified user.

URL
GET /users/{userId}

Parameters

URL parameters:

ParameterMandatoryTypeDescription
userIdStringID of the user about which the nformation is to be retrieved

Response

CodeName
200OK
400Bad Request
401Unauthorized
404Not Found
429Too Many Requests
500Internal Server Error
503Service Unavailable

JSON with the value of the attributes of the user.

Example
Get information about Katherine Johnson, who has ID user01.

curl -X GET "https://recom.sherpa.ai/v2/recomm/users/user01" \
-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******"
{
    "interests": [
        "science",
        "technology",
        "travel"
    ],
    "name": "Katherine Johnson",
    "age": 35
}

Update User

Update the attribute values of an existing user.

URL
PATCH /users/{userId}

Parameters

URL parameters:

FieldMandatoryTypeDescription
userIdStringID of the user to be updated

Fields to be included in the request body:

FieldMandatoryTypeDescription
Other attributesThe values for the individual attributes

Response

CodeName
204No Content
400Bad Request
401Unauthorized
404Not Found
500Internal Server Error
503Service Unavailable

Example
Update the age of Katherine Johnson, who has ID user01, to 51. Add her country, USA, too.

curl -X PATCH "https://recom.sherpa.ai/v2/recomm/users/user01" \
-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  "{\"age\":51,\"country\":\"USA\"}"

List Users

Get a list of user IDs currently present in the catalog and, optionally, their attributes. For a detailed description of filters, please refer to RSQL.

URL
GET /users

Parameters

Fields to be included in the request body:

FieldMandatoryTypeDescription
attributesStringAllows the ability to specify which attributes will be returned. The set must be enclosed in parentheses.
filterStringBoolean-returning RSQL expression, which allows the ability to filter users to be listed. Only the users 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
503Service Unavailable

JSON with the filtered users.

Examples
Get the names and interests of users that are not from the UK, sorted by name.

curl -X GET "https://recom.sherpa.ai/v2/recomm/users?attributes=("name","interests")&filter=country!=UK&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******"
[
    {
        "userId":"user01",
        "name": "Katherine Johnson",
        "interests": [
                "science",
                "technology",
                "travel"
            ]
    },
    {
        "userId":"user03",
        "name": "Sophie Germain",
        "interests": [
                "science",
                "society",
                "culture"
            ]
    }
]

Get only the IDs of those same users.

curl -X GET "https://recom.sherpa.ai/v2/recomm/users?filter=country!=UK&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******"
[
    "user01",
    "user03"
]

Delete All Users

Delete all users. Every attribute value and user-item-interaction associated with the users will also be deleted.

URL
DELETE /users

Response

CodeName
202Accepted
400Bad Request
401Unauthorized
423Locked
500Internal Server Error
503Service Unavailable

Example
Remove all users.

curl -X DELETE "https://recom.sherpa.ai/v2/recomm/users" \
-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 User

Delete a user. Every attribute value and user-item-interaction associated with the user will also be deleted.

URL
DELETE /users/{userId}

Parameters

FieldMandatoryTypeDescription
userIdStringID of the user to be deleted

Response

CodeName
200OK
400Bad Request
401Unauthorized
404Not Found
500Internal Server Error
503Service Unavailable

Example
Remove Katherine Johnson, who has ID user01.

curl -X DELETE "https://recom.sherpa.ai/v2/recomm/users/user01" \
-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******"

User Keywords

When there are new users who do not have any interactions registered yet, each of said users can be provided with a set of keywords representing user preferences over items. In the case of news for a user who reads mostly sports news, their keywords could be, for example: “nfl”, “superbowl”, “new york giants”, “nba”, “kobe bryant”.

Add User Keywords

Add user keywords.

URL
POST /users/{userId}/warmup

Parameters

URL parameters:

ParameterMandatoryTypeDescription
userIdStringID of the user

Fields to be included in the request body:

FieldMandatoryTypeDescription
keywordsArrayKeywords representing user preferences over items

Response

CodeName
204No Content
400Bad Request
401Unauthorized
404Not Found
500Internal Server Error
503Service Unavailable

Example
Add keywords for user01, who usually interacts with news related to US sports.

curl -X POST "https://recom.sherpa.ai/v2/recomm/users/user01/warmup" \
-H  "Content-Type: application/json" \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H  "X-Sherpa-timestamp: 1548084514112" \
-d  "{\"keywords\":[\"nfl\",\"nhl\",\"nba\"]}"

Get User Keywords

Get the keywords of a specific user.

URL
GET /users/{userId}/warmup/keywords

Parameters

URL parameters:

ParameterMandatoryTypeDescription
userIdStringID of the user whose keywords are to be returned

Response

CodeName
200OK
400Bad Request
401Unauthorized
404Not Found
429Too Many Requests
500Internal Server Error
503Service Unavailable

JSON with the user's keywords.

Example
Get keywords for user user01.

curl -X GET "https://recom.sherpa.ai/v2/recomm/users/user01/warmup/keywords" \
-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******"
[
    "nfl",
    "nhl",
    "nba"
]

Delete User Keywords

Delete all the keywords associated with a specific user.

URL
DELETE /users/{userId}/warmup/keywords

Parameters

URL parameters:

ParameterMandatoryTypeDescription
userIdStringID of the user whose keywords are to be deleted

Response

CodeName
204No Content
400Bad Request
401Unauthorized
404Not Found
500Internal Server Error
503Service Unavailable

Example
Remove the keywords associated with user01.

curl -X DELETE "https://recom.sherpa.ai/v2/recomm/users/user01/warmup/keywords" \
-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-RAMDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******"

Delete User Keyword

Delete a keyword from a specific user's set of keywords.

URL
DELETE /users/{userId}/warmup/keywords

Parameters

URL parameters:

ParameterMandatoryTypeDescription
userIdStringID of the user from whom a keyword is to be deleted

Fields to be included in the request body:

FieldMandatoryTypeDescription
keywordsArrayKeywords to be deleted

Response

CodeName
204No Content
400Bad Request
401Unauthorized
404Not Found
500Internal Server Error
503Service Unavailable

Example
Remove the keyword "nfl" from the set of keywords associated with user01.

curl -X DELETE "https://recom.sherpa.ai/v2/recomm/users/user01/warmup?keyword=nfl" \
-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  "{\"keywords\":[\"nfl\"]}"