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:

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.

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

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

Example
Add the age and gender of a user, which age is an integer and gender is a String, as an attributes 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  "{\"attributes\":[{\"attributeId\":\"age\",\"type\":\"int\"},{\"attributeId\":\"gender\",\"type\":\"string\"}]}"

Get User Attribute Info

Get information about a specified user attribute.

URL
GET /users/attributes/{attributeId}

Parameters

URL parameters:

Parameter	Mandatory	Type	Description
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 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

Code	Name
200	OK
400	Bad Request
401	Unauthorized
429	Too Many Requests
500	Internal Server Error
503	Service 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:

Field	Mandatory	Type	Description
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 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:

Field	Mandatory	Type	Description
userId	✓	String	ID of the user to be created
Other attributes			The values for the individual attributes

Response

Code	Name
201	Created
400	Bad Request
401	Unauthorized
409	Conflict
500	Internal Server Error
503	Service 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:

Parameter	Mandatory	Type	Description
userId	✓	String	ID of the user about which the nformation 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 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:

Field	Mandatory	Type	Description
userId	✓	String	ID of the user 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 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:

Field	Type	Description
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 the ability to filter users to be listed. Only the users 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 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

Code	Name
202	Accepted
400	Bad Request
401	Unauthorized
423	Locked
500	Internal Server Error
503	Service 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

Field	Mandatory	Type	Description
userId	✓	String	ID of the user 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 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:

Parameter	Mandatory	Type	Description
userId	✓	String	ID of the user

Fields to be included in the request body:

Field	Mandatory	Type	Description
keywords	✓	Array	Keywords representing user preferences over items

Response

Code	Name
204	No Content
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Server Error
503	Service 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:

Parameter	Mandatory	Type	Description
userId	✓	String	ID of the user whose keywords are to be returned

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 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:

Parameter	Mandatory	Type	Description
userId	✓	String	ID of the user whose keywords are to be deleted

Response

Code	Name
204	No Content
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Server Error
503	Service 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:

Parameter	Mandatory	Type	Description
userId	✓	String	ID of the user from whom a keyword is to be deleted

Fields to be included in the request body:

Field	Mandatory	Type	Description
keywords	✓	Array	Keywords to be deleted

Response

Code	Name
204	No Content
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Server Error
503	Service 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\"]}"