feat(specs): add transformations endpoints to ingestion (#3215)

specs/ingestion/common/parameters.yml

@@ -30,6 +30,14 @@ pathTaskID:
   schema:
     $ref: './schemas/common.yml#/taskID'
 
+pathTransformationID:
+  name: transformationID
+  in: path
+  required: true
+  description: Unique identifier of a transformation.
+  schema:
+    $ref: './schemas/common.yml#/transformationID'
+
 pathRunID:
   name: runID
   in: path
@@ -75,3 +83,17 @@ orderKeys:
   description: Ascending or descending sort order.
   default: desc
   enum: [asc, desc]
+
+sort:
+  name: sort
+  in: query
+  description: Property by which to sort the list.
+  required: false
+  schema:
+    $ref: '#/sortKeys'
+
+sortKeys:
+  type: string
+  description: Property by which to sort the list.
+  default: desc
+  enum: [name, type, updatedAt, createdAt]

specs/ingestion/common/schemas/common.yml

@@ -55,6 +55,12 @@ taskID:
   description: Universally unique identifier (UUID) of a task.
   example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
 
+transformationID:
+  type: string
+  # format: uuid
+  description: Universally unique identifier (UUID) of a transformation.
+  example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
+
 runID:
   type: string
   # format: uuid

specs/ingestion/common/schemas/transformation.yml

@@ -0,0 +1,122 @@
+Transformation:
+  type: object
+  additionalProperties: false
+  properties:
+    transformationID:
+      $ref: './common.yml#/transformationID'
+    code:
+      $ref: '#/Code'
+    name:
+      $ref: '#/Name'
+    description:
+      $ref: '#/Description'
+    createdAt:
+      $ref: './common.yml#/createdAt'
+    updatedAt:
+      $ref: './common.yml#/updatedAt'
+  required:
+    - transformationID
+    - code
+    - name
+    - description
+    - createdAt
+
+Code:
+  type: string
+  description: The source code of the transformation.
+
+Name:
+  type: string
+  description: The uniquely identified name of your transformation.
+
+Description:
+  type: string
+  description: A descriptive name for your transformation of what it does.
+
+TransformationCreate:
+  type: object
+  additionalProperties: false
+  description: API request body for creating a transformation.
+  properties:
+    code:
+      $ref: '#/Code'
+    name:
+      $ref: '#/Name'
+    description:
+      $ref: '#/Description'
+  required:
+    - code
+    - name
+    - description
+
+TransformationCreateResponse:
+  type: object
+  additionalProperties: false
+  description: API response for creating a transformation.
+  properties:
+    transformationID:
+      $ref: './common.yml#/transformationID'
+    createdAt:
+      $ref: './common.yml#/createdAt'
+  required:
+    - transformationID
+    - createdAt
+
+TransformationUpdateResponse:
+  type: object
+  description: API response for updating a transformation.
+  additionalProperties: false
+  properties:
+    transformationID:
+      $ref: './common.yml#/transformationID'
+    updatedAt:
+      $ref: './common.yml#/updatedAt'
+  required:
+    - transformationID
+    - updatedAt
+
+TransformationSearch:
+  type: object
+  additionalProperties: false
+  properties:
+    transformationsIDs:
+      type: array
+      items:
+        $ref: './common.yml#/transformationID'
+  required:
+    - transformationsIDs
+
+TransformationTry:
+  type: object
+  additionalProperties: false
+  properties:
+    code:
+      $ref: '#/Code'
+    sampleRecord:
+      description: The record to apply the given code to.
+      type: object
+  required:
+    - code
+    - sampleRecord
+
+TransformationTryResponse:
+  type: object
+  additionalProperties: false
+  properties:
+    payloads:
+      type: array
+      description: The array of records returned by the transformation service.
+      items:
+        type: object
+    error:
+      type: object
+      description: The error if the transformation failed.
+      properties:
+        code:
+          description: The error status code.
+          type: integer
+        message:
+          description: A descriptive message explaining the failure.
+          type: string
+  required:
+    - payloads

specs/ingestion/paths/transformations/transformationID.yml

@@ -0,0 +1,63 @@
+get:
+  tags:
+    - transformations
+  summary: Retrieve a transformation
+  description: Retrieves a transformation by its ID.
+  operationId: getTransformation
+  x-acl:
+    - addObject
+    - deleteIndex
+    - editSettings
+  parameters:
+    - $ref: '../../common/parameters.yml#/pathTransformationID'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '../../common/schemas/transformation.yml#/Transformation'
+    '400':
+      $ref: '../../../common/responses/BadRequest.yml'
+
+put:
+  tags:
+    - transformations
+  summary: Update a transformation
+  description: Updates a transformation by its ID.
+  operationId: updateTransformation
+  parameters:
+    - $ref: '../../common/parameters.yml#/pathTransformationID'
+  requestBody:
+    content:
+      application/json:
+        schema:
+          $ref: '../../common/schemas/transformation.yml#/TransformationCreate'
+    required: true
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '../../common/schemas/transformation.yml#/TransformationUpdateResponse'
+    '400':
+      $ref: '../../../common/responses/BadRequest.yml'
+
+delete:
+  tags:
+    - transformations
+  summary: Delete a transformation
+  description: Deletes a transformation by its ID.
+  operationId: deleteTransformation
+  parameters:
+    - $ref: '../../common/parameters.yml#/pathTransformationID'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '../../common/schemas/common.yml#/DeleteResponse'
+    '400':
+      $ref: '../../../common/responses/BadRequest.yml'

specs/ingestion/paths/transformations/transformations.yml

@@ -0,0 +1,58 @@
+get:
+  tags:
+    - transformations
+  summary: List transformations
+  description: Retrieves a list of transformations.
+  operationId: getTransformations
+  x-acl:
+    - addObject
+    - deleteIndex
+    - editSettings
+  parameters:
+    - $ref: '../../common/parameters.yml#/sort'
+    - $ref: '../../common/parameters.yml#/order'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            title: listTransformationsResponse
+            type: object
+            description: Configured transformations and pagination information.
+            additionalProperties: false
+            properties:
+              transformations:
+                type: array
+                items:
+                  $ref: '../../common/schemas/transformation.yml#/Transformation'
+              pagination:
+                $ref: '../../common/schemas/pagination.yml#/Pagination'
+            required:
+              - transformations
+              - pagination
+    '400':
+      $ref: '../../../common/responses/BadRequest.yml'
+
+post:
+  tags:
+    - transformations
+  summary: Create a transformation
+  description: Creates a new transformation.
+  operationId: createTransformation
+  requestBody:
+    description: Request body for creating a transformation.
+    content:
+      application/json:
+        schema:
+          $ref: '../../common/schemas/transformation.yml#/TransformationCreate'
+    required: true
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '../../common/schemas/transformation.yml#/TransformationCreateResponse'
+    '400':
+      $ref: '../../../common/responses/BadRequest.yml'

specs/ingestion/paths/transformations/transformationsSearch.yml

@@ -0,0 +1,28 @@
+post:
+  tags:
+    - transformations
+  summary: Search for transformations
+  description: Searches for transformations.
+  operationId: searchTransformations
+  x-acl:
+    - addObject
+    - deleteIndex
+    - editSettings
+  requestBody:
+    content:
+      application/json:
+        schema:
+          $ref: '../../common/schemas/transformation.yml#/TransformationSearch'
+    required: true
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            title: searchTransformationsResponse
+            type: array
+            items:
+              $ref: '../../common/schemas/transformation.yml#/Transformation'
+    '400':
+      $ref: '../../../common/responses/BadRequest.yml'

specs/ingestion/paths/transformations/transformationsTry.yml

@@ -0,0 +1,25 @@
+post:
+  tags:
+    - transformations
+  summary: Search for transformations
+  description: Searches for transformations.
+  operationId: tryTransformations
+  x-acl:
+    - addObject
+    - deleteIndex
+    - editSettings
+  requestBody:
+    content:
+      application/json:
+        schema:
+          $ref: '../../common/schemas/transformation.yml#/TransformationTry'
+    required: true
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '../../common/schemas/transformation.yml#/TransformationTryResponse'
+    '400':
+      $ref: '../../../common/responses/BadRequest.yml'

specs/ingestion/spec.yml

@@ -88,6 +88,10 @@ tags:
     description: |
       Tasks contain information how your data should be read from a source and stored in a destination.
       Tasks have _triggers_ which determine when the task should run.
+  - name: transformations
+    x-displayName: Transformations
+    description: |
+      Transformations allows you to transform a record before it gets indexed in Algolia.
 x-tagGroups:
   - name: Resources
     tags:
@@ -147,6 +151,16 @@ paths:
   /1/tasks/{taskID}/disable:
     $ref: 'paths/tasks/disableTask.yml'
 
+  # transformations API.
+  /1/transformations:
+    $ref: 'paths/transformations/transformations.yml'
+  /1/transformations/try:
+    $ref: 'paths/transformations/transformationsTry.yml'
+  /1/transformations/search:
+    $ref: 'paths/transformations/transformationsSearch.yml'
+  /1/transformations/{transformationID}:
+    $ref: 'paths/transformations/transformationID.yml'
+
   # observability API.
   /1/runs:
     $ref: 'paths/runs/runs.yml'

tests/CTS/requests/ingestion/createTransformation.json

@@ -0,0 +1,18 @@
+[
+  {
+    "parameters": {
+      "code": "foo",
+      "name": "bar",
+      "description": "baz"
+    },
+    "request": {
+      "path": "/1/transformations",
+      "method": "POST",
+      "body": {
+        "code": "foo",
+        "name": "bar",
+        "description": "baz"
+      }
+    }
+  }
+]