diff --git a/specs/ingestion/common/parameters.yml b/specs/ingestion/common/parameters.yml index d6bdfe9e465..62e4a3ee873 100644 --- a/specs/ingestion/common/parameters.yml +++ b/specs/ingestion/common/parameters.yml @@ -83,3 +83,11 @@ orderKeys: description: Ascending or descending sort order. default: desc enum: [asc, desc] + +watch: + name: watch + in: query + description: When provided, the push operation will be synchronous and the API will wait for the ingestion to be finished before responding. + required: false + schema: + type: boolean diff --git a/specs/ingestion/common/schemas/task.yml b/specs/ingestion/common/schemas/task.yml index 4c0817646dc..22d1b5b2b40 100644 --- a/specs/ingestion/common/schemas/task.yml +++ b/specs/ingestion/common/schemas/task.yml @@ -606,3 +606,33 @@ Policies: type: integer minimum: 1 maximum: 10 + +PushTaskPayload: + title: pushTaskPayload + type: object + properties: + action: + $ref: '#/action' + records: + type: array + items: + title: pushTaskRecords + type: object + additionalProperties: true + required: + - objectID + properties: + objectID: + $ref: '../../../common/parameters.yml#/objectID' + required: + - action + - records + +action: + type: string + enum: + - addObject + - updateObject + - partialUpdateObject + - partialUpdateObjectNoCreate + description: Type of indexing operation. diff --git a/specs/ingestion/paths/push.yml b/specs/ingestion/paths/push.yml new file mode 100644 index 00000000000..99befc0e2bb --- /dev/null +++ b/specs/ingestion/paths/push.yml @@ -0,0 +1,37 @@ +post: + summary: Pushes records to be transformed through the Pipeline, directly to an index + description: > + Pushes records through the Pipeline, directly to an index. You can make the call synchronous by providing the `watch` parameter, + for asynchronous calls, you can use the observability endpoints and/or debugger dashboard to see the status of your task. + + If you want to leverage the [pre-indexing data transformation](https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/how-to/transform-your-data/), this is the recommended way of ingesting your records. + + This method is similar to `pushTask`, but requires an `indexName` instead of a `taskID`. If zero or many tasks are found, + an error will be returned. + operationId: push + x-acl: + - addObject + - deleteIndex + - editSettings + x-timeouts: + connect: 180000 + read: 180000 + write: 180000 + parameters: + - $ref: '../../common/parameters.yml#/IndexName' + - $ref: '../common/parameters.yml#/watch' + requestBody: + content: + application/json: + schema: + $ref: '../common/schemas/task.yml#/PushTaskPayload' + required: true + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '../common/schemas/common.yml#/WatchResponse' + '400': + $ref: '../../common/responses/BadRequest.yml' diff --git a/specs/ingestion/paths/tasks/v2/pushTask.yml b/specs/ingestion/paths/tasks/v2/pushTask.yml index b689a9721d8..16dfe0a85cb 100644 --- a/specs/ingestion/paths/tasks/v2/pushTask.yml +++ b/specs/ingestion/paths/tasks/v2/pushTask.yml @@ -1,8 +1,14 @@ post: tags: - tasks - summary: Push a `batch` request payload through the Pipeline - description: Push a `batch` request payload through the Pipeline. You can check the status of task pushes with the observability endpoints. + summary: Pushes records to be transformed through the Pipeline, directly to an index + description: > + Pushes records through the Pipeline, directly to an index. You can make the call synchronous by providing the `watch` parameter, + for asynchronous calls, you can use the observability endpoints and/or debugger dashboard to see the status of your task. + + If you want to leverage the [pre-indexing data transformation](https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/how-to/transform-your-data/), this is the recommended way of ingesting your records. + + This method is similar to `push`, but requires a `taskID` instead of a `indexName`, which is useful when many `destinations` target the same `indexName`. operationId: pushTask x-acl: - addObject @@ -14,36 +20,12 @@ post: write: 180000 parameters: - $ref: '../../../common/parameters.yml#/pathTaskID' - - name: watch - in: query - description: When provided, the push operation will be synchronous and the API will wait for the ingestion to be finished before responding. - required: false - schema: - type: boolean + - $ref: '../../../common/parameters.yml#/watch' requestBody: - description: Request body of a Search API `batch` request that will be pushed in the Connectors pipeline. content: application/json: schema: - title: pushTaskPayload - type: object - properties: - action: - $ref: '../../../../common/schemas/Batch.yml#/action' - records: - type: array - items: - title: pushTaskRecords - type: object - additionalProperties: true - required: - - objectID - properties: - objectID: - $ref: '../../../../common/parameters.yml#/objectID' - required: - - action - - records + $ref: '../../../common/schemas/task.yml#/PushTaskPayload' required: true responses: '200': diff --git a/specs/ingestion/spec.yml b/specs/ingestion/spec.yml index 9f42fe8ac9d..9d7a3cb6825 100644 --- a/specs/ingestion/spec.yml +++ b/specs/ingestion/spec.yml @@ -112,6 +112,9 @@ paths: /{path}: $ref: '../common/paths/customRequest.yml' + /1/push/{indexName}: + $ref: 'paths/push.yml' + # authentications API. /1/authentications: $ref: 'paths/authentications/authentications.yml' diff --git a/tests/CTS/requests/ingestion/push.json b/tests/CTS/requests/ingestion/push.json new file mode 100644 index 00000000000..9858fef2bd1 --- /dev/null +++ b/tests/CTS/requests/ingestion/push.json @@ -0,0 +1,86 @@ +[ + { + "testName": "global push", + "parameters": { + "indexName": "foo", + "pushTaskPayload": { + "action": "addObject", + "records": [ + { + "key": "bar", + "foo": "1", + "objectID": "o" + }, + { + "key": "baz", + "foo": "2", + "objectID": "k" + } + ] + } + }, + "request": { + "path": "/1/push/foo", + "method": "POST", + "body": { + "action": "addObject", + "records": [ + { + "key": "bar", + "foo": "1", + "objectID": "o" + }, + { + "key": "baz", + "foo": "2", + "objectID": "k" + } + ] + } + } + }, + { + "testName": "global push with watch mode", + "parameters": { + "indexName": "bar", + "pushTaskPayload": { + "action": "addObject", + "records": [ + { + "key": "bar", + "foo": "1", + "objectID": "o" + }, + { + "key": "baz", + "foo": "2", + "objectID": "k" + } + ] + }, + "watch": true + }, + "request": { + "path": "/1/push/bar", + "method": "POST", + "queryParameters": { + "watch": "true" + }, + "body": { + "action": "addObject", + "records": [ + { + "key": "bar", + "foo": "1", + "objectID": "o" + }, + { + "key": "baz", + "foo": "2", + "objectID": "k" + } + ] + } + } + } +]