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. | |
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 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, gender and occupation of a user, which age is an integer, gender is a String and occupation is category type, 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\"},{\"attributeId\":\"occupation\",\"type\":\"category\",\"values\":[\"teacher\",\"actor\"]}]}"
Update User Attribute
Update values that an user 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 ocuppation attribute values.
curl -X PATCH "https://recom.sherpa.ai/v2/recomm/users/attributes/occupation" \
-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\":[\"engineer\",\"lawyer\",\"journalist\"]}"
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 | Mandatory | 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\"]}"