fix(specs): Personalization API (#2982)

Co-authored-by: Clément Vannicatte <vannicattec@gmail.com>
Co-authored-by: Pierre Millot <pierre.millot@algolia.com>

Author: 3 people

generators/src/main/java/com/algolia/codegen/AlgoliaSwiftGenerator.java

@@ -57,6 +57,7 @@ public class AlgoliaSwiftGenerator extends Swift5ClientCodegen {
     "edit",
     "edittype",
     "errorbase",
+    "eventtype",
     "exactonsinglewordquery",
     "exhaustive",
     "facetfilters",
@@ -68,8 +69,8 @@ public class AlgoliaSwiftGenerator extends Swift5ClientCodegen {
     "ignoreplurals",
     "indexsettingsassearchparams",
     "languages",
-    "matchlevel",
     "matchedgeolocation",
+    "matchlevel",
     "mixedsearchfilters",
     "mode",
     "numericfilters",
@@ -81,14 +82,14 @@ public class AlgoliaSwiftGenerator extends Swift5ClientCodegen {
     "promoteobjectids",
     "querytype",
     "rankinginfo",
-    "rerankingapplyfilter",
     "redirect",
     "redirectruleindexmetadata",
     "redirectruleindexmetadatadata",
     "region",
     "removestopwords",
     "removewordsifnoresults",
     "renderingcontent",
+    "rerankingapplyfilter",
     "searchparams",
     "searchparamsobject",
     "searchparamsquery",

specs/personalization/common/parameters.yml

@@ -3,11 +3,6 @@ UserToken:
   name: userToken
   in: path
   required: true
-  description: userToken representing the user for which to fetch the Personalization profile.
+  description: Unique identifier representing a user for which to fetch the personalization profile.
   schema:
-    type: string
-
-# misc
-userToken:
-  type: string
-  description: userToken representing the user for which to fetch the Personalization profile.
+    $ref: '../../common/schemas/SearchParams.yml#/userToken'

specs/personalization/common/schemas/eventScoring.yml

@@ -10,7 +10,15 @@ eventScoring:
       $ref: 'personalizationStrategy.yml#/score'
     eventName:
       type: string
-      description: The name of the event.
+      description: Event name.
     eventType:
-      type: string
-      description: The type of the event.
+      $ref: '#/EventType'
+
+EventType:
+  title: eventType
+  type: string
+  description: Event type.
+  enum:
+    - click
+    - conversion
+    - view

specs/personalization/common/schemas/facetScoring.yml

@@ -9,4 +9,4 @@ facetScoring:
       $ref: 'personalizationStrategy.yml#/score'
     facetName:
       type: string
-      description: The name of the facet.
+      description: Facet attribute name.

specs/personalization/common/schemas/personalizationStrategy.yml

@@ -8,19 +8,30 @@ personalizationStrategyParams:
   properties:
     eventScoring:
       type: array
-      description: Scores associated with the events.
+      description: |
+        Scores associated with each event.
+
+        The higher the scores, the higher the impact of those events on the personalization of search results.
       items:
         $ref: 'eventScoring.yml#/eventScoring'
     facetScoring:
       type: array
-      description: Scores associated with the facets.
+      description: |
+        Scores associated with each facet.
+
+        The higher the scores, the higher the impact of those events on the personalization of search results.
       items:
         $ref: 'facetScoring.yml#/facetScoring'
     personalizationImpact:
       type: integer
-      description: 'The impact that personalization has on search results: a number between 0 (personalization disabled) and 100 (personalization fully enabled).'
+      minimum: 0
+      maximum: 100
+      description: |
+        Impact of personalization on the search results.
+
+        If set to 0, personalization has no impact on the search results.
 
 # misc
 score:
   type: integer
-  description: The score for the event.
+  description: Event score.

specs/personalization/paths/deleteUserProfile.yml

@@ -6,11 +6,9 @@ delete:
     - recommendation
   summary: Delete a user profile.
   description: |
-    Delete the user profile and all its associated data.
+    Deletes a user profile.
 
-    Returns, as part of the response, a date until which the data can safely be considered as deleted for the given user. This means if you send events for the given user before this date, they will be ignored. Any data received after the deletedUntil date will start building a new user profile.
-
-    It might take a couple hours for the deletion request to be fully processed.
+    The response includes a date and time when the user profile can safely be considered deleted.
   parameters:
     - $ref: '../common/parameters.yml#/UserToken'
   responses:
@@ -27,10 +25,12 @@ delete:
               - deletedUntil
             properties:
               userToken:
-                $ref: '../common/parameters.yml#/userToken'
+                $ref: '../../common/schemas/SearchParams.yml#/userToken'
               deletedUntil:
                 type: string
-                description: A date until which the data can safely be considered as deleted for the given user. Any data received after the `deletedUntil` date will start building a new user profile.
+                description: |
+                  Date and time when the user profile can be safely considered to be deleted.
+                  Any events received after the `deletedUntil` date start a new user profile.
     '400':
       $ref: '../../common/responses/BadRequest.yml'
     '402':

specs/personalization/paths/getUserTokenProfile.yml

@@ -4,11 +4,8 @@ get:
   operationId: getUserTokenProfile
   x-acl:
     - recommendation
-  summary: Get a user profile.
-  description: |
-    Get the user profile built from Personalization strategy.
-
-    The profile is structured by facet name used in the strategy. Each facet value is mapped to its score. Each score represents the user affinity for a specific facet value given the userToken past events and the Personalization strategy defined. Scores are bounded to 20. The last processed event timestamp is provided using the ISO 8601 format for debugging purposes.
+  summary: Retrieve a user profile.
+  description: Retrieves a user profile and their affinities for different facets.
   parameters:
     - $ref: '../common/parameters.yml#/UserToken'
   responses:
@@ -26,13 +23,17 @@ get:
               - lastEventAt
             properties:
               userToken:
-                $ref: '../common/parameters.yml#/userToken'
+                $ref: '../../common/schemas/SearchParams.yml#/userToken'
               lastEventAt:
                 type: string
-                description: Date of last event update. (ISO-8601 format).
+                description: Date and time of the last event from this user, in RFC 3339 format.
               scores:
                 type: object
-                description: The userToken scores.
+                description: |
+                  Scores for different facet values.
+
+                  Scores represent the user affinity for a user profile towards specific facet values,
+                  given the personalization strategy and past events.
     '400':
       $ref: '../../common/responses/BadRequest.yml'
     '402':

specs/personalization/paths/personalizationStrategy.yml

@@ -4,8 +4,8 @@ get:
   operationId: getPersonalizationStrategy
   x-acl:
     - recommendation
-  summary: Get the current strategy.
-  description: The strategy contains information on the events and facets that impact user profiles and personalized search results.
+  summary: Retrieve the personalization strategy.
+  description: Retrieves the current personalization strategy.
   responses:
     '200':
       description: OK
@@ -28,8 +28,8 @@ post:
   operationId: setPersonalizationStrategy
   x-acl:
     - recommendation
-  summary: Set a new strategy.
-  description: A strategy defines the events and facets that impact user profiles and personalized search results.
+  summary: Define the personalization strategy.
+  description: Creates a new personalization strategy.
   requestBody:
     required: true
     content:
@@ -51,6 +51,7 @@ post:
               message:
                 type: string
                 description: A message confirming the strategy update.
+                example: Strategy was successfully updated.
     '400':
       $ref: '../../common/responses/BadRequest.yml'
     '402':

specs/personalization/spec.yml

@@ -1,8 +1,50 @@
 openapi: 3.0.2
 info:
   title: Personalization API
-  description: API powering the Personalization feature of Algolia.
+  description: |
+    The Personalization API lets you access user profiles built from the personalization strategy.
+
+    ## Base URLs
+
+    The base URLs for requests to the Personalization API are:
+
+    - `https://personalization.us.algolia.com`
+    - `https://personalization.eu.algolia.com`
+
+    Use the URL that matches your [analytics region](https://dashboard.algolia.com/account/infrastructure/analytics).
+
+    **All requests must use HTTPS.**
+
+    ## Authentication
+
+    To authenticate your API requests, add these headers:
+
+    - `x-algolia-application-id`. Your Algolia application ID.
+    - `x-algolia-api-key`. An API key with the necessary permissions to make the request.
+      The required access control list (ACL) to make a request is listed in each endpoint's reference.
+
+    You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account).
+
+    ## Request format
+
+    Request bodies must be JSON objects.
+
+    ## Response status and errors
+
+    The Personalization API returns JSON responses.
+    Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response.
+
+    Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status.
+    Error responses have a `message` property with more information.
+
+    ## Version
+
+    The current version of the Personalization API is version 1, as indicated by the `/1/` in each endpoint's URL.
   version: 1.0.0
+externalDocs:
+  url: https://www.algolia.com/doc/guides/personalization/what-is-personalization/
+  description: |
+    Related guide: Algolia Personalization.
 components:
   securitySchemes:
     appId:
@@ -23,10 +65,15 @@ security:
 tags:
   - name: profiles
     x-displayName: Profiles
-    description: Manage users' profiles.
+    description: |
+      User profiles represent the affinities each user profile has for the different facets in your index.
+      The more a user viewed and clicked search results with a specific facet,
+      the higher the affinity for that facet.
   - name: strategies
     x-displayName: Strategies
-    description: Manage personalization strategies.
+    description: |
+      The personalization strategy defines how personalization should affect the search results,
+      and how much each facet and event type impact the personalization.
 x-tagGroups:
   - name: General
     tags:

tests/CTS/requests/personalization/setPersonalizationStrategy.json

@@ -6,7 +6,7 @@
         {
           "score": 42,
           "eventName": "Algolia",
-          "eventType": "Event"
+          "eventType": "click"
         }
       ],
       "facetScoring": [
@@ -25,7 +25,7 @@
           {
             "score": 42,
             "eventName": "Algolia",
-            "eventType": "Event"
+            "eventType": "click"
           }
         ],
         "facetScoring": [