fix(specs): port recommend changes (#2476)

algolia · Jan 4, 2024 · ae6adfb · ae6adfb
1 parent f1eb132
commit ae6adfb
Show file tree

Hide file tree

Showing 14 changed files with 169 additions and 118 deletions.
diff --git a/specs/common/schemas/SearchParams.yml b/specs/common/schemas/SearchParams.yml
@@ -136,11 +136,7 @@ baseSearchParamsWithoutQuery:
       x-categories:
         - Personalization
     userToken:
-      type: string
-      description: Associates a [user token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken/) with the current search.
-      example: '123456'
-      x-categories:
-        - Personalization
+      $ref: '#/userToken'
     getRankingInfo:
       type: boolean
       description: Incidates whether the search response includes [detailed ranking information](https://www.algolia.com/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/#ranking-information).
@@ -209,6 +205,13 @@ paramsAsString:
   type: string
   default: ''
 
+userToken:
+  type: string
+  description: Associates a [user token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken/) with the current search.
+  example: '123456'
+  x-categories:
+    - Personalization
+
 query:
   type: string
   description: Text to search for in an index.

diff --git a/specs/recommend/common/parameters.yml b/specs/recommend/common/parameters.yml
@@ -18,3 +18,11 @@ ObjectID:
   type: string
   description: Unique Recommend rule identifier.
   example: 'a-recommend-rule-id'
+
+facetName:
+  type: string
+  description: Facet name for trending models.
+
+facetValue:
+  type: string
+  description: Facet value for trending models.
diff --git a/specs/recommend/common/schemas/RecommendationsQuery.yml b/specs/recommend/common/schemas/RecommendationsQuery.yml
@@ -1,7 +1,7 @@
 recommendationsQuery:
   allOf:
-    - $ref: '#/baseRecommendationsQuery'
     - $ref: './RecommendationsRequest.yml#/baseRecommendRequest'
+    - $ref: '#/baseRecommendationsQuery'
 
 baseRecommendationsQuery:
   type: object

diff --git a/specs/recommend/common/schemas/RecommendationsRequest.yml b/specs/recommend/common/schemas/RecommendationsRequest.yml
@@ -1,8 +1,9 @@
 recommendationsRequest:
   oneOf:
-    - $ref: './TrendingQuery.yml#/trendingItemsQuery'
-    - $ref: './TrendingQuery.yml#/trendingFacetsQuery'
+    - $ref: './TrendingItemsQuery.yml#/trendingItemsQuery'
+    - $ref: './TrendingFacetsQuery.yml#/trendingFacetsQuery'
     - $ref: './RecommendationsQuery.yml#/recommendationsQuery'
+    - $ref: './RecommendedForYouQuery.yml#/recommendedForYouQuery'
 
 baseRecommendRequest:
   type: object

diff --git a/specs/recommend/common/schemas/RecommendationsResponse.yml b/specs/recommend/common/schemas/RecommendationsResponse.yml
@@ -1,16 +1,16 @@
-recommendationsResponse:
+recommendationsResults:
   allOf:
     - $ref: '../../../search/common/schemas/SearchResponse.yml#/baseSearchResponse'
-    - $ref: '#/recommendHits'
+    - $ref: '#/recommendationsHits'
 
-recommendHits:
+recommendationsHits:
   type: object
   additionalProperties: false
   properties:
     hits:
       type: array
       items:
-        $ref: '#/recommendHit'
+        $ref: '#/recommendationsHit'
     query:
       $ref: '../../../common/schemas/SearchParams.yml#/query'    
     params:
@@ -20,6 +20,11 @@ recommendHits:
   required:
     - hits
 
+recommendationsHit:
+  oneOf:
+    - $ref: '#/recommendHit'
+    - $ref: '#/trendingFacetHit'
+
 recommendHit:
   type: object
   description: Recommend hit.
@@ -39,41 +44,26 @@ recommendHit:
     _distinctSeqID:
       $ref: '../../../search/common/schemas/Hit.yml#/_distinctSeqID'
     _score:
-      type: number
-      format: double
-      minimum: 0
-      maximum: 100
-      description: Recommendation score.
+      $ref: '#/recommendScore'
 
-ruleResponse:
+trendingFacetHit:
   type: object
-  description: Rule object.
-  additionalProperties: false
-  properties:
-    _metadata:
-      type: object
-      properties:
-        lastUpdate:
-          $ref: '../../../common/responses/common.yml#/updatedAt'
-    objectID:
-      type: string
-      description: Unique identifier for a rule object.
-      example: 'hide-12345'
-    conditions:
-      type: array
-      description: >
-        [Conditions](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/#conditions) required to activate a rule. You can use up to 25 conditions per rule.
-      items:
-        $ref: '../../../search/paths/rules/common/schemas.yml#/condition'
-    consequence:
-      $ref: '../../../search/paths/rules/common/schemas.yml#//consequence'
-    description:
-      type: string
-      description: Description of the rule's purpose. This can be helpful for display in the Algolia dashboard.
-      example: 'Display a promotional banner'
-    enabled:
-      type: boolean
-      default: true
-      description: Indicates whether to enable the rule. If it isn't enabled, it isn't applied at query time.
+  description: Trending facet hit.
   required:
-    - objectID
+    - _score
+    - facetName
+    - facetValue
+  properties:
+    _score:
+      $ref: '#/recommendScore'
+    facetName:
+      $ref: '../parameters.yml#/facetName'
+    facetValue:
+      $ref: '../parameters.yml#/facetValue'
+
+recommendScore:
+  type: number
+  format: double
+  minimum: 0
+  maximum: 100
+  description: Recommendation score.
diff --git a/specs/recommend/common/schemas/RecommendedForYouQuery.yml b/specs/recommend/common/schemas/RecommendedForYouQuery.yml
@@ -0,0 +1,35 @@
+recommendedForYouQuery:
+  allOf:
+    - $ref: './RecommendationsRequest.yml#/baseRecommendRequest'
+    - $ref: '#/baseRecommendedForYouQuery'
+
+recommendedForYouQueryParameters:
+  allOf:
+    - $ref: '../../../common/schemas/SearchParams.yml#/searchParamsObject'
+    - $ref: '#/baseRecommendedForYouQueryParameters'
+
+baseRecommendedForYouQueryParameters:
+  type: object
+  properties:
+    userToken:
+      $ref: '../../../common/schemas/SearchParams.yml#/userToken'
+  required:
+    - userToken
+
+baseRecommendedForYouQuery:
+  type: object
+  additionalProperties: false
+  properties:
+    model:
+      $ref: '#/recommendedForYouModel'
+    queryParameters:
+      $ref: '#/recommendedForYouQueryParameters'
+    fallbackParameters:
+      $ref: '#/recommendedForYouQueryParameters'
+  required:
+    - model
+
+recommendedForYouModel:
+  description: Recommended for you model.
+  type: string
+  enum: [recommended-for-you]
diff --git a/specs/recommend/common/schemas/RuleResponse.yml b/specs/recommend/common/schemas/RuleResponse.yml
@@ -0,0 +1,31 @@
+type: object
+description: Rule object.
+additionalProperties: false
+properties:
+  _metadata:
+    type: object
+    properties:
+      lastUpdate:
+        $ref: '../../../common/responses/common.yml#/updatedAt'
+  objectID:
+    type: string
+    description: Unique identifier for a rule object.
+    example: 'hide-12345'
+  conditions:
+    type: array
+    description: >
+      [Conditions](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/#conditions) required to activate a rule. You can use up to 25 conditions per rule.
+    items:
+      $ref: '../../../search/paths/rules/common/schemas.yml#/condition'
+  consequence:
+    $ref: '../../../search/paths/rules/common/schemas.yml#//consequence'
+  description:
+    type: string
+    description: Description of the rule's purpose. This can be helpful for display in the Algolia dashboard.
+    example: 'Display a promotional banner'
+  enabled:
+    type: boolean
+    default: true
+    description: Indicates whether to enable the rule. If it isn't enabled, it isn't applied at query time.
+required:
+  - objectID
diff --git a/specs/recommend/common/schemas/TrendingFacetsQuery.yml b/specs/recommend/common/schemas/TrendingFacetsQuery.yml
@@ -0,0 +1,20 @@
+trendingFacetsQuery:
+  allOf:
+    - $ref: './RecommendationsRequest.yml#/baseRecommendRequest'
+    - $ref: '#/baseTrendingFacetsQuery'
+
+baseTrendingFacetsQuery:
+  type: object
+  additionalProperties: false
+  properties:
+    facetName:
+      $ref: '../parameters.yml#/facetName'
+    model:
+      $ref: '#/trendingFacetsModel'
+  required:
+    - facetName
+
+trendingFacetsModel:
+  description: Trending facets model.
+  type: string
+  enum: [trending-facets]
diff --git a/specs/recommend/common/schemas/TrendingItemsQuery.yml b/specs/recommend/common/schemas/TrendingItemsQuery.yml
@@ -0,0 +1,24 @@
+trendingItemsQuery:
+  allOf:
+    - $ref: './RecommendationsRequest.yml#/baseRecommendRequest'
+    - $ref: '#/baseTrendingItemsQuery'
+
+baseTrendingItemsQuery:
+  type: object
+  additionalProperties: false
+  properties:
+    facetName:
+      $ref: '../parameters.yml#/facetName'
+    facetValue:
+      $ref: '../parameters.yml#/facetValue'
+    model:
+      $ref: '#/trendingItemsModel'
+    queryParameters:
+      $ref: '../../../common/schemas/SearchParams.yml#/searchParamsObject'
+    fallbackParameters:
+      $ref: '../../../common/schemas/SearchParams.yml#/searchParamsObject'
+
+trendingItemsModel:
+  description: Trending items model.
+  type: string
+  enum: [trending-items]
diff --git a/specs/recommend/common/schemas/TrendingQuery.yml b/specs/recommend/common/schemas/TrendingQuery.yml
diff --git a/specs/recommend/paths/getRecommendations.yml b/specs/recommend/paths/getRecommendations.yml
@@ -40,7 +40,7 @@ post:
               results:
                 type: array
                 items:
-                  $ref: '../common/schemas/RecommendationsResponse.yml#/recommendationsResponse'
+                  $ref: '../common/schemas/RecommendationsResponse.yml#/recommendationsResults'
     '400':
       $ref: '../../common/responses/BadRequest.yml'
     '402':

diff --git a/specs/recommend/paths/recommendRule.yml b/specs/recommend/paths/recommendRule.yml
@@ -14,7 +14,7 @@ get:
       content:
         application/json:
           schema:
-            $ref: '../common/schemas/RecommendationsResponse.yml#/ruleResponse'
+            $ref: '../common/schemas/RuleResponse.yml'
     '400':
       $ref: '../../common/responses/BadRequest.yml'
     '402':
@@ -44,4 +44,4 @@ delete:
     '403':
       $ref: '../../common/responses/MethodNotAllowed.yml'
     '404':
-      $ref: '../../common/responses/IndexNotFound.yml'
+      $ref: '../../common/responses/IndexNotFound.yml'
diff --git a/specs/recommend/paths/searchRecommendRules.yml b/specs/recommend/paths/searchRecommendRules.yml
@@ -33,14 +33,6 @@ post:
               nullable: true
               default: null
               description: Restricts responses to enabled rules. When absent (default), _all_ rules are retrieved.
-            requestOptions:
-              type: array
-              description: Request options to send with the API call.
-              example: >
-                {timeouts:{read:20}}
-              items:
-                type: object
-                description: Request option.
   responses:
     '200':
       description: OK
@@ -60,21 +52,18 @@ post:
                 type: array
                 description: Fetched rules.
                 items:
-                  $ref: '../common/schemas/RecommendationsResponse.yml#/ruleResponse'
+                  $ref: '../common/schemas/RuleResponse.yml'
               nbHits:
-                type: integer
-                description: Number of fetched rules.
+                $ref: '../../search/common/schemas/SearchResponse.yml#/nbHits'
               page:
-                type: integer
-                description: Current page.
+                $ref: '../../common/schemas/SearchParams.yml#/page'
               nbPages:
-                type: integer
-                description: Number of pages.
+                $ref: '../../search/common/schemas/SearchResponse.yml#/nbPages'
     '400':
       $ref: '../../common/responses/BadRequest.yml'
     '402':
       $ref: '../../common/responses/FeatureNotEnabled.yml'
     '403':
       $ref: '../../common/responses/MethodNotAllowed.yml'
     '404':
-      $ref: '../../common/responses/IndexNotFound.yml'
+      $ref: '../../common/responses/IndexNotFound.yml'