API Entities¶
The Crossing Minds API Implements a basic hierarchy of entities involved. We present here the resources over which the API provides a direct control. Other “under the hood” entities like machine learning models, algorithms or embeddings are described in Under the Hood.
Organization¶
This entity will be created for you. It gathers everything belonging to your organization, and stores the parameters of your subscription such as the rate limit. You won’t have to interact with organization entities directly.
Database¶
This entity gathers the user data, the item data and the user/item interactions. You can create multiple databases for your organization, for instance for staging or test environments. However, different databases do not share anything: the information learned by a machine learning model in one database is not applicable to any other database. No transfer learning is applied, for example.
API Endpoint to create a new database: POST databases/
Account¶
At first you will have access to an individual root account.
Logging with this account grants all permissions, like creating other accounts or databases.
You can create multiple accounts, either “individual accounts” or “service accounts”.
Each account is linked to a unique email address for individual accounts,
and service name for service accounts.
See Authentication for more details on the authentication and login steps.
API Endpoint to create a new individual account: POST accounts/individual/
API Endpoint to create a new service account: POST accounts/service/
Item and Item Property¶
Items are abstract key/value objects, that are identified by their ID. Items are the entities you want to recommend to your users, such as movies or books. There is no hard-coded concept of “sub-item” (like an episode of a TV show), nor “item-group” (like a movie genre). In order to model such data, you can use the item-property system described below.
Item ID Type¶
Main page: Flexible Identifiers.
The Crossing Minds API supports various types to identify items, such as:
integer
url-safe string (e.g. hexadecimal, modified base64, UUID)
raw bytes
You need to configure the item ID type when creating a new database.
This choice is permanent and cannot be modified later for this database.
See item_id_type in POST databases/.
Item Property¶
Main page: Items and Users Properties.
Data in the key/value map is called “item properties”. All properties must be defined before any item can start using them. The API does not automatically create new properties if a new key is detected during an API request; instead it will raise an error. This feature prevents development errors as soon as they occur.
Item properties can be of various type:
integer
float
categorical
image URL
text
geo-location
Furthermore, a property may be “repeated”, meaning that items contain an array of many values for this property.
API Endpoint to create new item properties: POST items-properties/.
API Endpoint to create new items: PUT items/<str:item_id>/.
User and User Property¶
The above structure is replicated for users and users properties.
If you need to fully anonymize your user IDs, we recommend using a secret one-way hash function and configure the database to use raw bytes as user IDs.
API Endpoint to create new user properties: POST users-properties/.
API Endpoint to create new users: PUT users/<str:user_id>/.
Rating¶
In the current version, the Crossing Minds API only accepts blackbox user/item interactions, modeled by a floating point number from 1 (worst) to 10 (best). This real number may represent an explicit rating from the user to the item, or a virtual rating inferred from implicit feedback.
User/item interactions are the core data for Deep Collaborative Filtering. The conversion from implicit feedback to virtual ratings is a necessary step to obtain a successful recommender system. Which rules are optimal highly depends on your business and the type of implicit feedback (e.g. clicks or view history). Do not hesitate to contact us regarding these business rules: we’re here to help.
API Endpoint to create new user/item interactions: PUT users/<str:user_id>/ratings/<str:item_id>/.
Entities Relationship Diagram¶
You will find below a diagram of how the API entities are related together, using ER Crow’s foot notation.
