feat(specs): query suggestions

specs/query-suggestions/common/enums.yml

@@ -1,4 +1,13 @@
-logLevel:
+LogLevel:
+  title: level
   type: string
-  enum: [INFO, SKIP, ERROR]
-  description: type of the record, can be one of three values (INFO, SKIP or ERROR).
+  description: |
+    The type of log entry. 
+
+    - `SKIP`. A query is skipped because it doesn't match the conditions for successful inclusion. For example, when a query doesn't generate enough search results.
+    - `INFO`. An informative log entry.
+    - `ERROR`. The Query Suggestions process encountered an error.
+  enum:
+    - SKIP
+    - INFO
+    - ERROR

specs/query-suggestions/common/parameters.yml

@@ -1,114 +1,7 @@
-SourceIndex:
-  type: object
-  additionalProperties: false
-  required:
-    - indexName
-  properties:
-    indexName:
-      $ref: '#/indexName'
-    analyticsTags:
-      $ref: '#/analyticsTags'
-    facets:
-      $ref: '#/facets'
-    minHits:
-      $ref: '#/minHits'
-    minLetters:
-      $ref: '#/minLetters'
-    generate:
-      $ref: '#/generate'
-    external:
-      $ref: '#/external'
-
-SourceIndexExternal:
-  type: object
-  additionalProperties: false
-  required:
-    - query
-    - count
-  properties:
-    query:
-      type: string
-      description: The suggestion you would like to add.
-    count:
-      type: integer
-      description: The measure of the suggestion relative popularity.
-
-SourceIndices:
-  type: array
-  items:
-    $ref: '#/SourceIndex'
-  description: List of source indices used to generate a Query Suggestions index.
-
-QuerySuggestionsIndexParam:
-  type: object
-  additionalProperties: false
-  required:
-    - sourceIndices
-  properties:
-    sourceIndices:
-      $ref: '../common/parameters.yml#/SourceIndices'
-    languages:
-      type: array
-      items:
-        type: string
-      description: De-duplicate singular and plural suggestions. For example, let's say your index contains English content, and that two suggestions “shoe” and “shoes” end up in your Query Suggestions index. If the English language is configured, only the most popular of those two suggestions would remain.
-    exclude:
-      type: array
-      items:
-        type: string
-      description: List of words and patterns to exclude from the Query Suggestions index.
-
-QuerySuggestionsIndexWithIndexParam:
-  allOf:
-    - $ref: '#/QuerySuggestionsIndexParam'
-    - type: object
-      title: IndexName
-      additionalProperties: false
-      required:
-        - indexName
-      properties:
-        indexName:
-          type: string
-          description: Index name to target.
-
-indexName:
-  type: string
-  description: Source index name.
-
-analyticsTags:
-  type: array
-  items:
-    type: string
-  default: []
-  description: List of analytics tags to filter the popular searches per tag.
-
-facets:
-  type: array
-  items:
-    type: object
-  default: []
-  description: List of facets to define as categories for the query suggestions.
-
-minHits:
-  type: integer
-  description: Minimum number of hits (e.g., matching records in the source index) to generate a suggestions.
-
-minLetters:
-  type: integer
-  description: Minimum number of required letters for a suggestion to remain.
-
-generate:
-  type: array
-  items:
-    type: array
-    items:
-      type: string
-  default: []
-  description: List of facet attributes used to generate Query Suggestions. The resulting suggestions are every combination of the facets in the nested list (e.g., (facetA and facetB) and facetC).
-  example: '[[facetA, facetB], [facetC]]'
-
-external:
-  type: array
-  items:
-    $ref: '#/SourceIndexExternal'
-  description: List of external indices to use to generate custom Query Suggestions.
+IndexName:
+  name: indexName
+  in: path
+  required: true
+  description: Query Suggestions index name.
+  schema:
+    $ref: './schemas/QuerySuggestionsIndexName.yml'

specs/query-suggestions/common/responses/BadRequest.yml

@@ -0,0 +1,32 @@
+description: Bad Request.
+content:
+  application/json:
+    schema:
+      $ref: '../schemas/BaseResponse.yml'
+    examples:
+      IndexNameRequired:
+        summary: Index name required.
+        value: {'status': 400, 'message': 'IndexName cannot be empty'}
+      SourceIndicesRequired:
+        summary: Source indices required.
+        value:
+          'status': 400
+          'message': 'Invalid body "sourceIndices needs to contain at least one index".'
+
+      SourceIndexNameRequired:
+        summary: Source index name required.
+        value:
+          'status': 400
+          'message': 'Invalid body "every source index must have an `indexName`".'
+
+      MinHitsPositive:
+        summary: MinHits must be positive.
+        value:
+          'status': 400
+          'message': 'Invalid body "every source index `minHits` must be positive".'
+
+      MinLettersPositive:
+        summary: MinLetters must be positive.
+        value:
+          'status': 400
+          'message': 'Invalid body "every source index `minLetters` must be positive".'

specs/query-suggestions/common/responses/InternalError.yml

@@ -0,0 +1,9 @@
+description: Internal Server Error.
+content:
+  application/json:
+    schema:
+      $ref: '../schemas/BaseResponse.yml'
+    examples:
+      Error:
+        description: This error can happen if you use a non-existing `indexName` as a path parameter when trying to update or delete a Query Suggestions configuration.
+        value: {'status': 500, 'message': 'Internal Server Error'}

specs/query-suggestions/common/responses/NotFound.yml

@@ -0,0 +1,9 @@
+description: Not Found.
+content:
+  application/json:
+    schema:
+      $ref: '../schemas/BaseResponse.yml'
+    examples:
+      NotFound:
+        summary: Index not found.
+        value: {'status': 404, 'message': 'Not Found'}

specs/query-suggestions/common/responses/Unauthorized.yml

@@ -0,0 +1,25 @@
+description: Unauthorized
+content:
+  application/json:
+    schema:
+      $ref: '../schemas/BaseResponse.yml'
+    examples:
+      Unauthorized:
+        summary: Wrong region.
+        description: |
+          Make sure to make your request to the server corresponding to your region.  
+
+          You can check the region for your application in the [Algolia dashboard](https://dashboard.algolia.com/account/infrastructure/analytics).
+        value:
+          'status': 401
+          'message': 'The log processing region does not match'
+
+      InvalidCredentials:
+        summary: Invalid credentials.
+        description: Your application ID or API key is wrong.
+        value: {'status': 401, 'message': 'Invalid credentials'}
+      WrongAPIKey:
+        summary: Admin API key required.
+        description: Your API key is not the Admin API key for your application.
+        value:
+          {'status': 401, 'message': 'The admin API key is required'}

specs/query-suggestions/common/responses/UnprocessableEntity.yml

@@ -0,0 +1,11 @@
+description: Unprocessable Entity.
+content:
+  application/json:
+    schema:
+      $ref: '../schemas/BaseResponse.yml'
+    examples:
+      UnprocessableEntity:
+        summary: Configuration already exists.
+        value: 
+          'status': 422
+          'message': 'Configuration already exists for index: test-qs'

specs/query-suggestions/common/schemas/BaseResponse.yml

@@ -0,0 +1,9 @@
+type: object
+additionalProperties: false
+properties:
+  status:
+    type: integer
+    description: HTTP status code.
+  message:
+    type: string
+    description: Details about the response, such as error messages.

specs/query-suggestions/common/schemas/Facet.yml

@@ -0,0 +1,11 @@
+title: facet
+description: Facet to use as category.
+type: object
+additionalProperties: false
+properties:
+  attribute:
+    type: string
+    description: Facet name.
+  amount:
+    type: integer
+    description: Number of suggestions.

specs/query-suggestions/common/schemas/Languages.yml

@@ -0,0 +1,10 @@
+title: languages
+description: |
+  Set the language for deduplicating singular and plural suggestions.
+  If specified, only the more popular form is included.
+oneOf:
+  - type: array
+    items:
+      type: string
+  - type: boolean
+    default: false

specs/query-suggestions/common/schemas/QuerySuggestionsConfiguration.yml

@@ -0,0 +1,24 @@
+type: object
+description: Query Suggestions configuration.
+additionalProperties: false
+required:
+  - sourceIndices
+properties:
+  sourceIndices:
+    $ref: './SourceIndices.yml'
+  languages:
+    $ref: './Languages.yml'
+  exclude:
+    type: array
+    description: Patterns to exclude from query suggestions.
+    nullable: true
+    items:
+      type: string
+  enablePersonalization:
+    type: boolean
+    default: false
+    description: Turn on personalized query suggestions.
+  allowSpecialCharacters:
+    type: boolean
+    default: false
+    description: Allow suggestions with special characters.

specs/query-suggestions/common/schemas/QuerySuggestionsConfigurationResponse.yml

@@ -0,0 +1,19 @@
+type: object
+allOf:
+  - type: object
+    additionalProperties: false
+    properties:
+      appId:
+        type: string
+        description: Your Algolia application ID.
+      sourceIndicesAPIKey:
+        type: string
+        description: API key used to read from your source index.
+      suggestionsIndicesAPIKey:
+        type: string
+        description: API key used to write and configure your Query Suggestions index.
+      externalIndicesAPIKey:
+        type: string
+        default: ''
+        description: API key used to read from external Algolia indices.
+  - $ref: './QuerySuggestionsConfigurationWithIndex.yml'

specs/query-suggestions/common/schemas/QuerySuggestionsConfigurationWithIndex.yml

@@ -0,0 +1,14 @@
+type: object
+description: Query Suggestions configuration.
+required:
+  - indexName
+  - sourceIndices
+allOf:
+  - type: object
+    additionalProperties: false
+    required:
+      - indexName
+    properties:
+      indexName:
+        $ref: './QuerySuggestionsIndexName.yml'
+  - $ref: './QuerySuggestionsConfiguration.yml'

specs/query-suggestions/common/schemas/QuerySuggestionsIndexName.yml

@@ -0,0 +1,4 @@
+title: indexName
+type: string
+description: Query Suggestions index name.
+example: products_query_suggestions