feat(specs): predict segments (#1013)

algolia · Sep 15, 2022 · 07a2e93 · 07a2e93
1 parent f8a7722
commit 07a2e93
Show file tree

Hide file tree

Showing 13 changed files with 564 additions and 0 deletions.
diff --git a/specs/predict/common/parameters.yml b/specs/predict/common/parameters.yml
@@ -6,6 +6,21 @@ userID:
     type: string
   description: User ID for authenticated users or cookie ID for non-authenticated repeated users (visitors).
 
+segmentID:
+  name: segmentID
+  in: path
+  required: true
+  schema:
+    type: string
+  description: The ID of the Segment to fetch.
+
+type:
+  name: type
+  in: query
+  schema:
+    $ref: '../responses/Segment.yml#/segmentType'
+  description: The type of segments to fetch.
+
 modelID:
   name: modelID
   in: path

diff --git a/specs/predict/common/schemas/SegmentsParams.yml b/specs/predict/common/schemas/SegmentsParams.yml
@@ -0,0 +1,41 @@
+createSegmentParams:
+  type: object
+  required:
+    - name
+    - conditions
+  properties:
+    name:
+      $ref: '#/name'
+    conditions:
+      $ref: '#/conditions'
+
+updateSegmentParams:
+  oneOf:
+    - $ref: '#/segmentNameParam'
+    - $ref: '#/segmentConditionsParam'
+    - $ref: '#/allUpdateSegmentParams'
+
+allUpdateSegmentParams:
+  allOf:
+    - $ref: '#/segmentNameParam'
+    - $ref: '#/segmentConditionsParam'
+
+segmentNameParam:
+  type: object
+  properties:
+    name:
+      $ref: '#/name'
+
+segmentConditionsParam:
+  type: object
+  properties:
+    conditions:
+      $ref: '#/conditions'
+
+name:
+  type: string
+  description: The name or description of the segment.
+
+conditions:
+  type: string
+  description: The filters that define the segment, defined in the same way as filters for Rules.
diff --git a/specs/predict/paths/segments/allSegments.yml b/specs/predict/paths/segments/allSegments.yml
@@ -0,0 +1,48 @@
+get:
+  tags:
+    - segments
+  operationId: fetchAllSegments
+  description: Get the list of segments with their configuration.
+  summary: Get all segments.
+  parameters:
+    - $ref: '../../common/parameters.yml#/type'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '../../responses/Segment.yml#/fetchAllSegmentsResponse'
+    '404':
+      $ref: '../../../common/responses/IndexNotFound.yml'
+    '422':
+      $ref: '../../../common/responses/StatusUnprocessableEntity.yml'
+    '500':
+      $ref: '../../../common/responses/InternalError.yml'
+post:
+  tags:
+    - segments
+  operationId: createSegment
+  summary: Create a segment.
+  description: Create a new segment. All segments added by this endpoint will have a computed type. The endpoint receives a filters parameter, with a syntax similar to filters for Rules.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '../../common/schemas/SegmentsParams.yml#/createSegmentParams'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '../../responses/Segment.yml#/createSegmentResponse'
+    '400':
+      $ref: '../../../common/responses/IndexNotFound.yml'
+    '401':
+      $ref: '../../../common/responses/Unauthorized.yml'
+    '422':
+      $ref: '../../../common/responses/StatusUnprocessableEntity.yml'
+    '500':
+      $ref: '../../../common/responses/InternalError.yml'
diff --git a/specs/predict/paths/segments/segmentUsers.yml b/specs/predict/paths/segments/segmentUsers.yml
@@ -0,0 +1,31 @@
+post:
+  tags:
+    - segments
+  operationId: getSegmentUsers
+  summary: Get segment users.
+  description: Get the profiles of users that belong to a segment.
+  parameters:
+    - $ref: '../../common/parameters.yml#/segmentID'
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '../../common/schemas/Params.yml#/fetchAllUserProfilesParams'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '../../responses/Segment.yml#/getSegmentUsersResponse'
+    '400':
+      $ref: '../../../common/responses/BadRequest.yml'
+    '401':
+      $ref: '../../../common/responses/Unauthorized.yml'
+    '404':
+      $ref: '../../../common/responses/IndexNotFound.yml'
+    '422':
+      $ref: '../../../common/responses/UnprocessableEntity.yml'
+    '500':
+      $ref: '../../../common/responses/InternalError.yml'
diff --git a/specs/predict/paths/segments/singleSegment.yml b/specs/predict/paths/segments/singleSegment.yml
@@ -0,0 +1,81 @@
+get:
+  tags:
+    - segments
+  operationId: fetchSegment
+  description: Get the segment configuration.
+  summary: Get the segment configuration.
+  parameters:
+    - $ref: '../../common/parameters.yml#/segmentID'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            title: fetchSegmentResponse
+            $ref: '../../responses/Segment.yml#/segment'
+    '404':
+      $ref: '../../../common/responses/IndexNotFound.yml'
+    '422':
+      $ref: '../../../common/responses/StatusUnprocessableEntity.yml'
+    '500':
+      $ref: '../../../common/responses/InternalError.yml'
+
+post:
+  tags:
+    - segments
+  operationId: updateSegment
+  description: Update a segment’s configuration.
+  summary: Update segment.
+  parameters:
+    - $ref: '../../common/parameters.yml#/segmentID'
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '../../common/schemas/SegmentsParams.yml#/updateSegmentParams'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '../../responses/Segment.yml#/updateSegmentResponse'
+    '400':
+      $ref: '../../../common/responses/IndexNotFound.yml'
+    '401':
+      $ref: '../../../common/responses/Unauthorized.yml'
+    '404':
+      $ref: '../../../common/responses/IndexNotFound.yml'
+    '422':
+      $ref: '../../../common/responses/StatusUnprocessableEntity.yml'
+    '500':
+      $ref: '../../../common/responses/InternalError.yml'
+
+delete:
+  tags:
+    - segments
+  operationId: deleteSegment
+  summary: Delete a segment's configuration.
+  description: |
+    Delete the segment’s configuration. User intents (predictions) from the segment are not deleted. All segment types (computed or custom) can be deleted.
+    
+    When the query is successful, the HTTP response is 200 OK and returns the date until which you can safely consider the data as being deleted.
+  parameters:
+    - $ref: '../../common/parameters.yml#/segmentID'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '../../responses/Segment.yml#/deleteSegmentResponse'
+    '401':
+      $ref: '../../../common/responses/Unauthorized.yml'
+    '404':
+      $ref: '../../../common/responses/IndexNotFound.yml'
+    '422':
+      $ref: '../../../common/responses/StatusUnprocessableEntity.yml'
+    '500':
+      $ref: '../../../common/responses/InternalError.yml'
diff --git a/specs/predict/responses/Segment.yml b/specs/predict/responses/Segment.yml
@@ -0,0 +1,110 @@
+updateSegmentResponse:
+  title: updateSegmentResponse
+  type: object
+  required:
+    - segmentID
+    - updatedAt
+  properties:
+    segmentID:
+      $ref: '#/segmentID'
+    updatedAt:
+      $ref: '#/updatedAt'
+
+deleteSegmentResponse:
+  title: deleteSegmentResponse
+  type: object
+  required:
+    - segmentID
+    - deletedUntil
+  properties:
+    segmentID:
+      $ref: '#/segmentID'
+    deletedUntil:
+      $ref: '#/deletedUntil'
+
+getSegmentUsersResponse:
+  title: getSegmentUsersResponse
+  type: object
+  required:
+    - segmentID
+    - users
+  properties:
+    segmentID:
+      $ref: '#/segmentID'
+    users:
+      type: array
+      items:
+        $ref: 'UserProfile.yml#/userProfile'
+    previousPageToken:
+      $ref: '../common/schemas/Params.yml#/previousPageToken'
+    nextPageToken:
+      $ref: '../common/schemas/Params.yml#/nextPageToken'
+
+fetchSegmentResponse:
+  title: fetchSegmentResponse
+  $ref: '#/segment'
+
+fetchAllSegmentsResponse:
+  title: fetchAllSegmentsResponse
+  type: array
+  items:
+    $ref: '#/segment'
+
+createSegmentResponse:
+  title: createSegmentResponse
+  type: object
+  required:
+    - segmentID
+    - updatedAt
+  properties:
+    segmentID:
+      $ref: '#/segmentID'
+    updatedAt:
+      $ref: '#/updatedAt'
+
+segment:
+  type: object
+  required:
+    - segmentID
+    - name
+    - conditions
+    - segmentStatus
+    - type
+  properties:
+    segmentID:
+      $ref: '#/segmentID'
+    name:
+      type: string
+    conditions:
+      type: string
+    segmentStatus:
+      $ref: '#/segmentStatus'
+    type:
+      $ref: '#/segmentType'
+    errorMessage:
+      type: string
+
+segmentStatus:
+  type: string
+  enum:
+    - active
+    - pending
+    - failed
+
+segmentType:
+  type: string
+  enum:
+    - computed
+    - custom
+
+segmentID:
+  type: string
+  description: The ID of the segment.
+
+updatedAt:
+  type: string
+  description: The date and time at which the segment was last updated.
+
+deletedUntil:
+  type: string
+  description: The date and time at which the segment will be re-ingested.
diff --git a/specs/predict/spec.yml b/specs/predict/spec.yml
@@ -31,18 +31,25 @@ tags:
   - name: profiles
     x-displayName: Profiles
     description: Manage users' profiles.
+  - name: segments
+    x-displayName: Segments
+    description: Manage segments.
 x-tagGroups:
   - name: General
     tags:
       - profiles
       - models
+      - segments
 paths:
   # ######################
   # ### Custom request ###
   # ######################
   /1{path}:
     $ref: '../common/paths/customRequest.yml'
 
+  # ######################
+  # ### Users request ###
+  # ######################
   /1/users/{userID}/fetch:
     $ref: 'paths/users/fetch.yml'
 
@@ -66,3 +73,15 @@ paths:
 
   /1/predict/models/{modelID}/metrics:
     $ref: 'paths/models/getModelMetrics.yml'
+
+  # ########################
+  # ### Segments request ###
+  # ########################
+  /1/segments/{segmentID}/users:
+    $ref: 'paths/segments/segmentUsers.yml'
+
+  /1/segments/{segmentID}:
+    $ref: 'paths/segments/singleSegment.yml'
+
+  /1/segments:
+    $ref: 'paths/segments/allSegments.yml'
diff --git a/tests/CTS/methods/requests/predict/createSegment.json b/tests/CTS/methods/requests/predict/createSegment.json
@@ -0,0 +1,17 @@
+[
+  {
+    "testName": "create segment with required params",
+    "parameters": {
+      "name": "segment1",
+      "conditions": "predictions.order_value.value > 100 AND predictions.funnel_stage.score < 0.9"
+    },
+    "request": {
+      "path": "/1/segments",
+      "method": "POST",
+      "body": {
+        "name": "segment1",
+        "conditions": "predictions.order_value.value > 100 AND predictions.funnel_stage.score < 0.9"
+      }
+    }
+  }
+]