diff --git a/specs/ingestion/common/parameters.yml b/specs/ingestion/common/parameters.yml index 1fdc660e04..fb89ff4556 100644 --- a/specs/ingestion/common/parameters.yml +++ b/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] diff --git a/specs/ingestion/common/schemas/common.yml b/specs/ingestion/common/schemas/common.yml index e6c483a0b1..d6075e3ba5 100644 --- a/specs/ingestion/common/schemas/common.yml +++ b/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 diff --git a/specs/ingestion/common/schemas/transformation.yml b/specs/ingestion/common/schemas/transformation.yml new file mode 100644 index 0000000000..3d0ed5aacf --- /dev/null +++ b/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 diff --git a/specs/ingestion/paths/transformations/transformationID.yml b/specs/ingestion/paths/transformations/transformationID.yml new file mode 100644 index 0000000000..58e3468aff --- /dev/null +++ b/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' diff --git a/specs/ingestion/paths/transformations/transformations.yml b/specs/ingestion/paths/transformations/transformations.yml new file mode 100644 index 0000000000..fb3d09c383 --- /dev/null +++ b/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' diff --git a/specs/ingestion/paths/transformations/transformationsSearch.yml b/specs/ingestion/paths/transformations/transformationsSearch.yml new file mode 100644 index 0000000000..955a0196f7 --- /dev/null +++ b/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' diff --git a/specs/ingestion/paths/transformations/transformationsTry.yml b/specs/ingestion/paths/transformations/transformationsTry.yml new file mode 100644 index 0000000000..5364239984 --- /dev/null +++ b/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' diff --git a/specs/ingestion/spec.yml b/specs/ingestion/spec.yml index bd34e8ba5e..67c852c71b 100644 --- a/specs/ingestion/spec.yml +++ b/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' diff --git a/tests/CTS/requests/ingestion/createTransformation.json b/tests/CTS/requests/ingestion/createTransformation.json new file mode 100644 index 0000000000..716380117e --- /dev/null +++ b/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" + } + } + } +] diff --git a/tests/CTS/requests/ingestion/deleteTransformation.json b/tests/CTS/requests/ingestion/deleteTransformation.json new file mode 100644 index 0000000000..352cccf3d4 --- /dev/null +++ b/tests/CTS/requests/ingestion/deleteTransformation.json @@ -0,0 +1,12 @@ +[ + { + "testName": "deleteTransformation", + "parameters": { + "transformationID": "6c02aeb1-775e-418e-870b-1faccd4b2c0f" + }, + "request": { + "path": "/1/transformations/6c02aeb1-775e-418e-870b-1faccd4b2c0f", + "method": "DELETE" + } + } +] diff --git a/tests/CTS/requests/ingestion/getTransformation.json b/tests/CTS/requests/ingestion/getTransformation.json new file mode 100644 index 0000000000..5d0bec12e2 --- /dev/null +++ b/tests/CTS/requests/ingestion/getTransformation.json @@ -0,0 +1,12 @@ +[ + { + "testName": "getTransformation", + "parameters": { + "transformationID": "6c02aeb1-775e-418e-870b-1faccd4b2c0f" + }, + "request": { + "path": "/1/transformations/6c02aeb1-775e-418e-870b-1faccd4b2c0f", + "method": "GET" + } + } +] diff --git a/tests/CTS/requests/ingestion/getTransformations.json b/tests/CTS/requests/ingestion/getTransformations.json new file mode 100644 index 0000000000..35ffa3d0ea --- /dev/null +++ b/tests/CTS/requests/ingestion/getTransformations.json @@ -0,0 +1,10 @@ +[ + { + "testName": "getTransformations", + "parameters": {}, + "request": { + "path": "/1/transformations", + "method": "GET" + } + } +] diff --git a/tests/CTS/requests/ingestion/searchTransformations.json b/tests/CTS/requests/ingestion/searchTransformations.json new file mode 100644 index 0000000000..cafdad6ad2 --- /dev/null +++ b/tests/CTS/requests/ingestion/searchTransformations.json @@ -0,0 +1,23 @@ +[ + { + "testName": "searchTransformations", + "parameters": { + "transformationsIDs": [ + "6c02aeb1-775e-418e-870b-1faccd4b2c0f", + "947ac9c4-7e58-4c87-b1e7-14a68e99699a", + "76ab4c2a-ce17-496f-b7a6-506dc59ee498" + ] + }, + "request": { + "path": "/1/transformations/search", + "method": "POST", + "body": { + "transformationsIDs": [ + "6c02aeb1-775e-418e-870b-1faccd4b2c0f", + "947ac9c4-7e58-4c87-b1e7-14a68e99699a", + "76ab4c2a-ce17-496f-b7a6-506dc59ee498" + ] + } + } + } +] diff --git a/tests/CTS/requests/ingestion/tryTransformations.json b/tests/CTS/requests/ingestion/tryTransformations.json new file mode 100644 index 0000000000..103d16b676 --- /dev/null +++ b/tests/CTS/requests/ingestion/tryTransformations.json @@ -0,0 +1,20 @@ +[ + { + "parameters": { + "code": "foo", + "sampleRecord": { + "bar": "baz" + } + }, + "request": { + "path": "/1/transformations/try", + "method": "POST", + "body": { + "code": "foo", + "sampleRecord": { + "bar": "baz" + } + } + } + } +] diff --git a/tests/CTS/requests/ingestion/updateTransformation.json b/tests/CTS/requests/ingestion/updateTransformation.json new file mode 100644 index 0000000000..afd8bbed62 --- /dev/null +++ b/tests/CTS/requests/ingestion/updateTransformation.json @@ -0,0 +1,22 @@ +[ + { + "testName": "updateTransformation", + "parameters": { + "transformationID": "6c02aeb1-775e-418e-870b-1faccd4b2c0f", + "transformationCreate": { + "code": "foo", + "name": "bar", + "description": "baz" + } + }, + "request": { + "path": "/1/transformations/6c02aeb1-775e-418e-870b-1faccd4b2c0f", + "method": "PUT", + "body": { + "code": "foo", + "name": "bar", + "description": "baz" + } + } + } +]