From b153b397e298d84efc2daecfb7cb4a8ec25201ec Mon Sep 17 00:00:00 2001 From: Kai Welke Date: Thu, 28 Mar 2024 13:51:19 +0100 Subject: [PATCH] fix(specs): ingestion api reference (#2918) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Clément Vannicatte --- .../algolia/codegen/AlgoliaJavaGenerator.java | 2 + .../cts/tests/ParametersWithDataType.java | 3 + .../common/authenticationParameters.yml | 11 +- .../common/destinationParameters.yml | 10 +- .../common/observabilityParameters.yml | 17 +-- specs/ingestion/common/parameters.yml | 25 ++-- .../common/schemas/authentication.yml | 97 ++++++++----- specs/ingestion/common/schemas/common.yml | 38 ++--- .../ingestion/common/schemas/destination.yml | 48 ++++--- specs/ingestion/common/schemas/event.yml | 4 +- specs/ingestion/common/schemas/pagination.yml | 21 ++- specs/ingestion/common/schemas/run.yml | 17 ++- specs/ingestion/common/schemas/source.yml | 136 +++++++++++------- specs/ingestion/common/schemas/task.yml | 132 +++++++++++------ specs/ingestion/common/sourceParameters.yml | 13 +- specs/ingestion/common/taskParameters.yml | 17 +-- .../authentications/authenticationID.yml | 12 +- .../paths/authentications/authentications.yml | 8 +- .../authentications/searchAuthentications.yml | 4 +- .../paths/destinations/destinationID.yml | 8 +- .../paths/destinations/destinations.yml | 6 +- .../paths/destinations/searchDestinations.yml | 4 +- specs/ingestion/paths/runs/events/eventID.yml | 4 +- specs/ingestion/paths/runs/events/events.yml | 8 +- specs/ingestion/paths/runs/runID.yml | 4 +- specs/ingestion/paths/runs/runs.yml | 8 +- specs/ingestion/paths/sources/discover.yml | 11 +- .../ingestion/paths/sources/searchSources.yml | 4 +- specs/ingestion/paths/sources/sourceID.yml | 8 +- specs/ingestion/paths/sources/sources.yml | 6 +- specs/ingestion/paths/tasks/disableTask.yml | 2 +- specs/ingestion/paths/tasks/enableTask.yml | 2 +- specs/ingestion/paths/tasks/runTask.yml | 2 +- specs/ingestion/paths/tasks/searchTasks.yml | 4 +- specs/ingestion/paths/tasks/taskID.yml | 8 +- specs/ingestion/paths/tasks/tasks.yml | 10 +- specs/ingestion/spec.yml | 80 ++++++++++- templates/java/api.mustache | 3 +- 38 files changed, 508 insertions(+), 289 deletions(-) diff --git a/generators/src/main/java/com/algolia/codegen/AlgoliaJavaGenerator.java b/generators/src/main/java/com/algolia/codegen/AlgoliaJavaGenerator.java index 594c6c223a..36df47d1fb 100644 --- a/generators/src/main/java/com/algolia/codegen/AlgoliaJavaGenerator.java +++ b/generators/src/main/java/com/algolia/codegen/AlgoliaJavaGenerator.java @@ -121,6 +121,8 @@ public String toEnumVarName(String value, String datatype) { return "GREATER_THAN"; case ">=": return "GREATER_EQUALS"; + case "mappingkit/v1": + return "MAPPINGKIT_V1"; } if (!value.matches("[A-Z0-9_]+")) { diff --git a/generators/src/main/java/com/algolia/codegen/cts/tests/ParametersWithDataType.java b/generators/src/main/java/com/algolia/codegen/cts/tests/ParametersWithDataType.java index bb1cb3a067..e548bbdebb 100644 --- a/generators/src/main/java/com/algolia/codegen/cts/tests/ParametersWithDataType.java +++ b/generators/src/main/java/com/algolia/codegen/cts/tests/ParametersWithDataType.java @@ -598,6 +598,9 @@ private void transferPrimitiveData(IJsonSchemaValidationProperties spec, Map +
search
+
Data is stored in an Algolia index.
+
insights
+
Data is recorded as user events in the Insights API.
+ . + enum: [search, insights] DestinationIndexPrefix: type: object @@ -111,7 +119,7 @@ DestinationIndexPrefix: properties: indexPrefix: type: string - description: The prefix of the final index name. + description: String added to the beginning of all indices created by this destination. required: - indexPrefix @@ -121,7 +129,7 @@ DestinationIndexName: properties: indexName: type: string - description: The index name to store data in. + description: Algolia index name. recordType: $ref: '#/RecordType' attributesToExclude: @@ -131,19 +139,21 @@ DestinationIndexName: RecordType: type: string - description: Determines the indexing strategy to use for a given e-commerce source. - enum: ['product', 'variant'] + description: Record type for ecommerce sources. + enum: [product, variant] AttributesToExclude: type: array - description: > - Determines the attributes to exclude from an Algolia record. + description: | + Attributes from your source to exclude from Algolia records. + + Not all your data attributes will be useful for searching. + Keeping your Algolia records small increases indexing and search performance. - To remove nested element, you can separate the path to the element with dots (`.`): - - "foo.bar": will remove `bar` from `foo`. - To remove elements from an array, you can use the following: - - "foo.[0].bar": will only remove `bar` from the first element of `foo`. - - "foo.[*].bar": will remove `bar` from every elements of `foo`. + - Exclude nested attributes with `.` notation. For example, `foo.bar` indexes the `foo` attribute and all its children **except** the `bar` attribute. + - Exclude attributes from arrays with `[i]`, where `i` is the index of the array element. + For example, `foo.[0].bar` only excludes the `bar` attribute from the first element of the `foo` array, but indexes the complete `foo` attribute for all other elements. + Use `*` as wildcard: `foo.[*].bar` excludes `bar` from all elements of the `foo` array. items: type: string diff --git a/specs/ingestion/common/schemas/event.yml b/specs/ingestion/common/schemas/event.yml index ce8f356924..ec193682ba 100644 --- a/specs/ingestion/common/schemas/event.yml +++ b/specs/ingestion/common/schemas/event.yml @@ -36,8 +36,8 @@ Event: EventStatus: type: string - enum: ['created', 'started', 'retried', 'failed', 'succeeded', 'critical'] + enum: [created, started, retried, failed, succeeded, critical] EventType: type: string - enum: ['fetch', 'record', 'log', 'transform'] + enum: [fetch, record, log, transform] diff --git a/specs/ingestion/common/schemas/pagination.yml b/specs/ingestion/common/schemas/pagination.yml index 6e673519f2..9e60cbc092 100644 --- a/specs/ingestion/common/schemas/pagination.yml +++ b/specs/ingestion/common/schemas/pagination.yml @@ -1,17 +1,34 @@ Pagination: type: object + description: Paginated API response. additionalProperties: false properties: nbPages: type: integer + minimum: 1 + description: Number of pages in the API response. page: - type: integer + $ref: '#/page' nbItems: type: integer + minimum: 0 + description: Number of items in the API response. itemsPerPage: - type: integer + $ref: '#/itemsPerPage' required: - nbPages - page - nbItems - itemsPerPage + +itemsPerPage: + type: integer + description: Number of items per page. + minimum: 1 + maximum: 100 + default: 10 + +page: + type: integer + minimum: 1 + description: Page of the API response to retrieve. diff --git a/specs/ingestion/common/schemas/run.yml b/specs/ingestion/common/schemas/run.yml index 48bcaf0665..a85c4e3aba 100644 --- a/specs/ingestion/common/schemas/run.yml +++ b/specs/ingestion/common/schemas/run.yml @@ -1,7 +1,7 @@ RunResponse: type: object additionalProperties: false - description: The response from the run task API, containing an Observability Run ID and the time it was created at. + description: API response for running a task. properties: runID: $ref: './common.yml#/runID' @@ -54,7 +54,7 @@ Run: $ref: './task.yml#/failureThreshold' reason: type: string - description: 'Explains the result of outcome.' + description: More information about the task run's outcome. reasonCode: $ref: '#/RunReasonCode' type: @@ -75,18 +75,21 @@ Run: RunStatus: type: string - enum: ['created', 'started', 'idled', 'finished', 'skipped'] + description: Task run status. + enum: [created, started, idled, finished, skipped] RunOutcome: type: string - enum: ['success', 'failure', 'processing'] + description: Task run outcome. + enum: [success, failure, processing] RunType: type: string - enum: ['reindex', 'update', 'discover'] + description: Task run type. + enum: [reindex, update, discover] RunReasonCode: type: string - description: 'An identifier that pairs with the outcome reason.' + description: A code for the task run's outcome. A readable description of the code is included in the `reason` response property. enum: - ['internal', 'critical', 'no_events', 'too_many_errors', 'ok', 'discarded', 'blocking'] + [internal, critical, no_events, too_many_errors, ok, discarded, blocking] diff --git a/specs/ingestion/common/schemas/source.yml b/specs/ingestion/common/schemas/source.yml index dbdc0b90af..24fa87cc19 100644 --- a/specs/ingestion/common/schemas/source.yml +++ b/specs/ingestion/common/schemas/source.yml @@ -31,6 +31,7 @@ SourceCreate: $ref: '#/SourceType' name: type: string + description: Descriptive name of the source. input: $ref: '#/SourceInput' authenticationID: @@ -48,6 +49,7 @@ SourceCreateResponse: $ref: './common.yml#/sourceID' name: type: string + description: Descriptive name of the source. createdAt: $ref: './common.yml#/createdAt' required: @@ -61,6 +63,7 @@ SourceUpdate: properties: name: type: string + description: Descriptive name of the source. input: $ref: '#/SourceUpdateInput' authenticationID: @@ -74,6 +77,7 @@ SourceUpdateResponse: $ref: './common.yml#/sourceID' name: type: string + description: Descriptive name of the source. updatedAt: $ref: './common.yml#/updatedAt' required: @@ -95,29 +99,34 @@ SourceSearch: SourceType: type: string enum: - - 'bigcommerce' - - 'commercetools' - - 'json' - - 'csv' - - 'bigquery' - - 'docker' - - 'ga4BigqueryExport' - + - bigcommerce + - bigquery + - commercetools + - csv + - docker + - ga4BigqueryExport + - json + - shopify + - sfcc + SourceCommercetools: + title: Commercetools type: object additionalProperties: false properties: storeKeys: type: array items: - description: Unique and immutable key of the referenced Store. + description: Unique and immutable key of the referenced store. type: string locales: type: array - description: > - Array of locales that must match the following pattern: ^[a-z]{2}(-[A-Z]{2})?$. For example ["fr-FR", "en"]. + description: Locales for your commercetools stores. items: type: string + pattern: '^[a-z]{2}(-[A-Z]{2})?$' + description: Locale specfied as combination of a two-letter language code and an optional two-letter country code. + example: 'fr-FR' url: type: string projectKey: @@ -125,8 +134,8 @@ SourceCommercetools: fallbackIsInStockValue: type: boolean default: true - description: > - Determines the value that will be stored in the Algolia record if there's no inventory information on the product. + description: | + Whether a fallback value is stored in the Algolia record if there's no inventory information about the product. customFields: $ref: '#/CommercetoolsCustomFields' required: @@ -138,37 +147,41 @@ SourceCommercetools: CommercetoolsCustomFields: type: object additionalProperties: false - description: Custom fields from Commercetools to index in the records (see https://docs.commercetools.com/tutorials/custom-types). + description: | + Custom fields from commercetools to add to the records. + + For more information, see [Using Custom Types and Custom Fields](https://docs.commercetools.com/tutorials/custom-types). properties: inventory: oneOf: - type: array + description: Inventory custom fields. items: type: string - description: Inventory custom fields. - type: 'null' price: oneOf: - type: array + description: Price custom fields. items: type: string - description: Price custom fields. - type: 'null' category: oneOf: - type: array + description: Category custom fields. items: type: string - description: Category custom fields. - type: 'null' SourceBigCommerce: + title: BigCommerce type: object additionalProperties: false properties: storeHash: type: string - description: The store hash identifying the store the shopper is signing in to. + description: Store hash identifying your BigCommerce store. channel: $ref: '#/BigCommerceChannel' customFields: @@ -194,10 +207,10 @@ BigCommerceMetafield: properties: namespace: type: string - description: The namespace of the metafield. + description: Namespace of the metafield. key: type: string - description: The key identifier of the metafield. + description: Key identifier of the metafield. required: - namespace - key @@ -208,32 +221,35 @@ BigCommerceChannel: properties: id: type: integer - description: The ID of the bigcommerce channel. + description: ID of the BigCommerce channel. currencies: type: array - description: An array of currencies for the given channel `ID`, a currency is a trigram string that represents the currency code. - example: ['usd', 'eur'] + description: Currencies for the given channel. + example: [usd, eur] items: type: string - example: 'usd' + description: Three-letter code for the currency. + example: usd required: - id MethodType: type: string - enum: ['GET', 'POST'] + description: HTTP method to be used for retrieving your data. + enum: [GET, POST] UniqueIDColumn: type: string - description: The name of the column that contains the unique ID, used as `objectID` in Algolia. + description: Name of a column that contains a unique ID which will be used as `objectID` in Algolia. SourceJSON: + title: JSON type: object additionalProperties: false properties: url: type: string - description: The URL of the file. + description: URL of the file. uniqueIDColumn: $ref: '#/UniqueIDColumn' method: @@ -243,21 +259,23 @@ SourceJSON: MappingTypeCSV: type: string - enum: ['string', 'integer', 'float', 'boolean', 'json'] + enum: [string, integer, float, boolean, json] SourceCSV: + title: CSV type: object additionalProperties: false properties: url: type: string - description: The URL of the file. + description: URL of the file. uniqueIDColumn: $ref: '#/UniqueIDColumn' mapping: type: object - description: > - Mapping of type for every column. For example {"myColumn": "boolean", "myOtherColumn": "json"}. + description: | + Key-value pairs of column names and their expected types. + x-additionalPropertyName: column name additionalProperties: $ref: '#/MappingTypeCSV' method: @@ -272,18 +290,20 @@ SourceCSV: - url SourceGA4BigQueryExport: + title: GA4 BigQuery export type: object additionalProperties: false properties: projectID: type: string - description: GCP project ID that the BigQuery Export writes to. + description: GCP project ID that the BigQuery export writes to. datasetID: type: string - description: BigQuery dataset ID that the BigQuery Export writes to. + description: BigQuery dataset ID that the BigQuery export writes to. tablePrefix: type: string - description: Prefix of the tables that the BigQuery Export writes to (i.e. events_intraday_ for streaming, events_ for daily). + description: Prefix of the tables that the BigQuery Export writes to. + example: events_intraday_ required: - projectID - datasetID @@ -294,23 +314,24 @@ SourceGA4BigQueryExport: - tablePrefix SourceBigQuery: + title: BigQuery type: object additionalProperties: false properties: projectID: type: string - description: Project ID of the BigQuery Source. + description: Project ID of the BigQuery source. datasetID: type: string - description: Dataset ID of the BigQuery Source. + description: Dataset ID of the BigQuery source. dataType: $ref: '#/BigQueryDataType' table: type: string - description: Table name (for default BQ). + description: Table name for the BigQuery export. tablePrefix: type: string - description: Table prefix (for Google Analytics). + description: Table prefix for a Google Analytics 4 data export to BigQuery. customSQLRequest: type: string description: Custom SQL request to extract data from the BigQuery table. @@ -324,9 +345,10 @@ SourceBigQuery: BigQueryDataType: type: string - enum: ['ga4', 'ga360'] + enum: [ga4, ga360] SourceDocker: + title: Docker type: object additionalProperties: false properties: @@ -336,15 +358,16 @@ SourceDocker: $ref: '#/DockerRegistry' image: type: string - description: The name of the image to pull. + description: Docker image name. example: algolia/zendesk version: type: string - description: The version of the image, defaults to `latest`. + description: Docker image version. + default: latest example: v2.1.0 configuration: type: object - description: The configuration of the spec. + description: Configuration of the spec. required: - registry - image @@ -359,27 +382,28 @@ SourceUpdateDocker: $ref: '#/DockerRegistry' image: type: string - description: The name of the image to pull. + description: Docker image name. example: algolia/zendesk version: type: string - description: The version of the image, defaults to `latest`. + description: Docker image version. + default: latest example: v2.1.0 configuration: type: object - description: The configuration of the spec. + description: Configuration of the spec. required: - configuration DockerRegistry: type: string - enum: ['dockerhub', 'ghcr'] - description: The registry where the image is stored. + description: Container registry name from where to pull the image. + enum: [dockerhub, ghcr] DockerImageType: type: string - enum: ['singer', 'custom', 'airbyte'] - description: The type of the image. + enum: [singer, custom, airbyte] + description: Image type. SourceInput: oneOf: @@ -397,21 +421,23 @@ SourceUpdateCommercetools: properties: storeKeys: type: array - description: Unique and immutable key of the referenced Store. items: + description: Unique and immutable key of the referenced store. type: string locales: type: array - description: > - Array of locales that must match the following pattern: ^[a-z]{2}(-[A-Z]{2})?$. For example ["fr-FR", "en"]. + description: Locales for your commercetools stores. items: type: string + pattern: '^[a-z]{2}(-[A-Z]{2})?$' + description: Locale specfied as combination of a two-letter language code and an optional two-letter country code. + example: 'fr-FR' url: type: string fallbackIsInStockValue: type: boolean - description: > - Determines the value that will be stored in the Algolia record if there's no inventory information on the product. + description: | + Whether a fallback value is stored in the Algolia record if there's no inventory information about the product. customFields: $ref: '#/CommercetoolsCustomFields' @@ -426,4 +452,4 @@ SourceUpdateInput: DockerSourceStream: type: object - description: A stream definition (see the Singer specification for details). + description: Stream definition (see the Singer specification for details). diff --git a/specs/ingestion/common/schemas/task.yml b/specs/ingestion/common/schemas/task.yml index 1be07fa3be..edd407a09a 100644 --- a/specs/ingestion/common/schemas/task.yml +++ b/specs/ingestion/common/schemas/task.yml @@ -15,7 +15,7 @@ Task: enabled: type: boolean default: true - description: Whether the task is enabled or not. + description: Whether the task is enabled. failureThreshold: $ref: '#/failureThreshold' action: @@ -37,6 +37,7 @@ Task: - createdAt Trigger: + description: Trigger that runs the task. oneOf: - $ref: '#/OnDemandTrigger' - $ref: '#/ScheduleTrigger' @@ -46,7 +47,7 @@ Trigger: TaskCreate: type: object additionalProperties: false - description: The payload for a task creation. + description: API request body for creating a task. properties: sourceID: $ref: './common.yml#/sourceID' @@ -58,7 +59,7 @@ TaskCreate: $ref: '#/ActionType' enabled: type: boolean - description: Whether the task is enabled or not. + description: Whether the task is enabled. failureThreshold: $ref: '#/failureThreshold' input: @@ -82,7 +83,7 @@ TaskCreateTrigger: TaskCreateResponse: type: object additionalProperties: false - description: The response from the API after a task creation. + description: API response for creating a task. properties: taskID: $ref: './common.yml#/taskID' @@ -95,7 +96,7 @@ TaskCreateResponse: TaskUpdate: type: object additionalProperties: false - description: The payload for a task update. + description: API request body for updating a task. properties: destinationID: $ref: './common.yml#/destinationID' @@ -105,13 +106,13 @@ TaskUpdate: $ref: '#/TaskInput' enabled: type: boolean - description: Whether the task is enabled or not. + description: Whether the task is enabled. failureThreshold: $ref: '#/failureThreshold' TaskUpdateResponse: type: object - description: The response from the API after a task update. + description: API response for updating a task. additionalProperties: false properties: taskID: @@ -129,16 +130,17 @@ TaskSearch: taskIDs: type: array items: - type: string + $ref: './common.yml#/taskID' required: - taskIDs ActionType: type: string - description: The action to perform on the Algolia index. - enum: ['replace', 'save', 'partial', 'append'] + description: Action to perform on the Algolia index. + enum: [replace, save, partial, append] TaskInput: + description: Configuration of the task, depending on its type. oneOf: - $ref: '#/OnDemandDateUtilsInput' - $ref: '#/ScheduleDateUtilsInput' @@ -147,7 +149,7 @@ TaskInput: TriggerInput: type: object additionalProperties: false - description: The trigger input of a task. + description: Trigger for a task. properties: type: $ref: '#/TriggerType' @@ -157,7 +159,7 @@ TriggerInput: TriggerUpdateInput: type: object additionalProperties: false - description: The trigger input for a task update. + description: Trigger for a task update. properties: cron: $ref: '#/Cron' @@ -166,34 +168,62 @@ TriggerUpdateInput: TriggerType: type: string - description: > - The type of the task reflect how it can be used: - - onDemand: a task that runs manually - - schedule: a task that runs regularly, following a given cron expression - - subscription: a task that runs after a subscription event is received from an integration (e.g. Webhook). - - streaming: a task that runs continuously. - enum: ['onDemand', 'schedule', 'subscription', 'streaming'] + description: | + Task trigger, describing when a task should run. + +
+
onDemand
+
+ + Manually trigger the task with the `/run` endpoint. + +
+
schedule
+
+ + Regularly trigger the task on a `cron` schedule. + +
+ +
subscription
+ +
+ + Trigger the task after an event is received, such as, a webhook. + +
+ +
streaming
+ +
+ + Run the task continuously. + +
+
. + enum: [onDemand, schedule, subscription, streaming] # schedule trigger LastRun: - description: The last time the scheduled task ran (RFC3339 format). + description: The last time the scheduled task ran in RFC3339 format. type: string Cron: type: string - description: A cron expression that represent at which regularity the task should run. + description: Cron expression for the task's schedule. example: '* * 1 * *' ScheduleTriggerType: type: string - description: A task which is triggered by a schedule (cron expression). - enum: ['schedule'] + description: Task runs on a schedule. + enum: [schedule] ScheduleTriggerInput: + title: Schedule type: object additionalProperties: false - description: The trigger input for a task of type 'schedule'. + description: Trigger input for scheduled tasks. properties: type: $ref: '#/ScheduleTriggerType' @@ -206,7 +236,7 @@ ScheduleTriggerInput: ScheduleTrigger: type: object additionalProperties: false - description: The trigger information for a task of type 'schedule'. + description: Trigger information for scheduled tasks. properties: type: $ref: '#/ScheduleTriggerType' @@ -215,7 +245,7 @@ ScheduleTrigger: lastRun: $ref: '#/LastRun' nextRun: - description: The next scheduled run of the task (RFC3339 format). + description: The next scheduled run of the task in RFC3339 format. type: string required: - type @@ -226,13 +256,14 @@ ScheduleTrigger: OnDemandTriggerType: type: string - description: A task which is manually executed via the run task endpoint. - enum: ['onDemand'] + description: Task is run manually, with the `/run` endpoint. + enum: [onDemand] OnDemandTriggerInput: + title: On demand type: object additionalProperties: false - description: The trigger information of a task of type `onDemand`. + description: Trigger information for manually-triggered tasks. properties: type: $ref: '#/OnDemandTriggerType' @@ -242,7 +273,7 @@ OnDemandTriggerInput: OnDemandTrigger: type: object additionalProperties: false - description: The trigger information of a task of type `onDemand`. + description: Trigger information for manually-triggered tasks. properties: type: $ref: '#/OnDemandTriggerType' @@ -255,13 +286,14 @@ OnDemandTrigger: SubscriptionTriggerType: type: string - description: A task which is triggered by an external subscription (e.g. Webhook). - enum: ['subscription'] + description: Task runs after receiving subscribed event. + enum: [subscription] SubscriptionTrigger: + title: Subscription type: object additionalProperties: false - description: The trigger input for a task of type 'subscription'. + description: Trigger input for subscription tasks. properties: type: $ref: '#/SubscriptionTriggerType' @@ -272,13 +304,14 @@ SubscriptionTrigger: StreamingTriggerType: type: string - description: A task that runs continuously. - enum: ['streaming'] + description: Task runs continuously. + enum: [streaming] StreamingTrigger: + title: Streaming type: object additionalProperties: false - description: The trigger input for a task of type 'streaming'. + description: Trigger input for continuously running tasks. properties: type: $ref: '#/StreamingTriggerType' @@ -326,14 +359,18 @@ MappingKitAction: - trigger - fieldDirectives +MappingFormatSchema: + type: string + description: Mapping format schema. + enum: ['mappingkit/v1'] + MappingInput: type: object additionalProperties: false - description: Transformations to apply to source, serialized as a JSON string. + description: Transformations to apply to the source, serialized as a JSON string. properties: format: - description: Name of the mapping format schema, `mappingkit/v1` is currently the only supported format. - type: string + $ref: '#/MappingFormatSchema' actions: type: array items: @@ -343,15 +380,16 @@ MappingInput: - actions OnDemandDateUtilsInput: + title: On demand date range type: object additionalProperties: false - description: The input for an `onDemand` task whose source is of type `bigquery` and for which extracted data spans a given time range. + description: Input for a manually-triggered task whose source is of type `bigquery` and for which extracted data spans a given time range. properties: startDate: - description: The start date of the extraction (RFC3339 format). + description: Earliest date in RFC3339 format of the extracted data from Big Query. type: string endDate: - description: The end date of the extraction (RFC3339 format). + description: Latest date in RFC3339 format of the extracted data from Big Query. type: string mapping: $ref: '#/MappingInput' @@ -360,12 +398,13 @@ OnDemandDateUtilsInput: - endDate ScheduleDateUtilsInput: + title: Schedule dates type: object additionalProperties: false - description: The input for a `schedule` task whose source is of type `bigquery` and for which extracted data spans a fixed number of days. + description: Input for scheduled tasks whose source is of type `bigquery` and for which extracted data spans a fixed number of days. properties: timeframe: - description: The timeframe of the extraction, in number of days from today. + description: Number of days in the past until the current day for which to extract Big Query data. type: integer minimum: 1 maximum: 30 @@ -375,9 +414,10 @@ ScheduleDateUtilsInput: - timeframe StreamingUtilsInput: + title: Streaming input type: object additionalProperties: false - description: The input for a `streaming` task whose source is of type `ga4BigqueryExport` and for which extracted data is continuously streamed. + description: Input for a `streaming` task whose source is of type `ga4BigqueryExport` and for which extracted data is continuously streamed. properties: mapping: $ref: '#/MappingInput' @@ -388,4 +428,4 @@ failureThreshold: type: integer minimum: 0 maximum: 100 - description: A percentage representing the accepted failure threshold to determine if a `run` succeeded or not. + description: Maximum accepted percentage of failures for a task run to finish successfully. diff --git a/specs/ingestion/common/sourceParameters.yml b/specs/ingestion/common/sourceParameters.yml index 9a12b1e36b..52880c6f1f 100644 --- a/specs/ingestion/common/sourceParameters.yml +++ b/specs/ingestion/common/sourceParameters.yml @@ -1,7 +1,7 @@ type: name: type in: query - description: The type of the sources to retrieve. + description: Source type. Some sources require authentication. required: false style: form explode: false @@ -14,9 +14,9 @@ type: authenticationID: name: authenticationID in: query - description: > - The authenticationIDs of the sources to retrieve. - 'none' returns sources that doesn't have an authentication. + description: | + Authentication IDs of the sources to retrieve. + 'none' returns sources that doesn't have an authentication resource. required: false style: form explode: false @@ -29,12 +29,13 @@ authenticationID: sort: name: sort in: query - description: The key by which the list should be sorted. + description: Property by which to sort the list of sources. required: false schema: $ref: '#/sourceSortKeys' sourceSortKeys: type: string - description: Used to sort the Source list endpoint. + description: Property by which to sort the list of sources. + default: createdAt enum: [name, type, updatedAt, createdAt] diff --git a/specs/ingestion/common/taskParameters.yml b/specs/ingestion/common/taskParameters.yml index 383260d908..11783e9bfd 100644 --- a/specs/ingestion/common/taskParameters.yml +++ b/specs/ingestion/common/taskParameters.yml @@ -1,7 +1,7 @@ enabled: name: enabled in: query - description: Whether the task is enabled or not. + description: Whether to filter the list of tasks by the `enabled` status. required: false schema: type: boolean @@ -10,12 +10,12 @@ action: name: action in: query required: false - description: The action of the tasks to retrieve. + description: Actions for filtering the list of tasks. style: form explode: false schema: type: array - description: An array of actions to perform on the Algolia index. + description: Actions to perform on the Algolia index. items: $ref: './schemas/task.yml#/ActionType' example: save,replace,partial,append @@ -23,7 +23,7 @@ action: sourceID: name: sourceID in: query - description: The sourceIDs of the tasks to retrieve. + description: Source IDs for filtering the list of tasks. required: false style: form explode: false @@ -35,7 +35,7 @@ sourceID: destinationID: name: destinationID in: query - description: The destinationIDs of the tasks to retrieve. + description: Destination IDs for filtering the list of tasks. required: false style: form explode: false @@ -47,7 +47,7 @@ destinationID: triggerType: name: triggerType in: query - description: The trigger type of the task. + description: Type of task trigger for filtering the list of tasks. required: false style: form explode: false @@ -60,12 +60,13 @@ triggerType: sort: name: sort in: query - description: The key by which the list should be sorted. + description: Property by which to sort the list of tasks. required: false schema: $ref: '#/taskSortKeys' taskSortKeys: type: string - description: Used to sort the Task list endpoint. + description: Property by which to sort the list of tasks. + default: createdAt enum: [enabled, triggerType, action, updatedAt, createdAt] diff --git a/specs/ingestion/paths/authentications/authenticationID.yml b/specs/ingestion/paths/authentications/authenticationID.yml index 2827e5da37..3641bef0bd 100644 --- a/specs/ingestion/paths/authentications/authenticationID.yml +++ b/specs/ingestion/paths/authentications/authenticationID.yml @@ -1,8 +1,8 @@ get: tags: - authentications - summary: Get a authentication. - description: Get the authentication of the given authenticationID. + summary: Retrieve an authentication resource. + description: Retrieves an authentication resource by its ID. operationId: getAuthentication x-acl: - addObject @@ -23,8 +23,8 @@ get: patch: tags: - authentications - summary: Update a authentication. - description: Update the authentication of the given authenticationID. + summary: Update an authentication resource. + description: Updates an authentication resource. operationId: updateAuthentication x-acl: - addObject @@ -51,8 +51,8 @@ patch: delete: tags: - authentications - summary: Delete a authentication. - description: Soft delete the authentication of the given authenticationID. + summary: Delete an authentication resource. + description: Deletes an authentication resource. You can't delete authentication resources that are used by a source or a destination. operationId: deleteAuthentication x-acl: - addObject diff --git a/specs/ingestion/paths/authentications/authentications.yml b/specs/ingestion/paths/authentications/authentications.yml index 7a998bb01d..589243f95e 100644 --- a/specs/ingestion/paths/authentications/authentications.yml +++ b/specs/ingestion/paths/authentications/authentications.yml @@ -1,8 +1,8 @@ get: tags: - authentications - summary: Get a list of authentications. - description: Get a list of authentications for the given query parameters, with pagination details. + summary: List authentication resources. + description: Retrieves a list of all authentication resources. operationId: getAuthentications x-acl: - addObject @@ -40,8 +40,8 @@ get: post: tags: - authentications - summary: Create a authentication. - description: Create a authentication. + summary: Create an authentication resource. + description: Creates a new authentication resource. operationId: createAuthentication x-acl: - addObject diff --git a/specs/ingestion/paths/authentications/searchAuthentications.yml b/specs/ingestion/paths/authentications/searchAuthentications.yml index 5f9bd588e2..0c5e8e5941 100644 --- a/specs/ingestion/paths/authentications/searchAuthentications.yml +++ b/specs/ingestion/paths/authentications/searchAuthentications.yml @@ -1,8 +1,8 @@ post: tags: - authentications - summary: Search among authentications. - description: Search among authentications with a defined set of parameters. + summary: Search for authentication resources. + description: Searches for authentication resources. operationId: searchAuthentications x-acl: - addObject diff --git a/specs/ingestion/paths/destinations/destinationID.yml b/specs/ingestion/paths/destinations/destinationID.yml index a1eb95a95d..20e0c5dae2 100644 --- a/specs/ingestion/paths/destinations/destinationID.yml +++ b/specs/ingestion/paths/destinations/destinationID.yml @@ -1,8 +1,8 @@ get: tags: - destinations - summary: Get a destination. - description: Get the destination of the given destinationID. + summary: Retrieve a destination. + description: Retrieves a destination by its ID. operationId: getDestination x-acl: - addObject @@ -24,7 +24,7 @@ patch: tags: - destinations summary: Update a destination. - description: Update the destination of the given destinationID. + description: Updates the destination by its ID. operationId: updateDestination x-acl: - addObject @@ -52,7 +52,7 @@ delete: tags: - destinations summary: Delete a destination. - description: Soft delete the destination of the given destinationID. + description: Deletes a destination by its ID. You can't delete destinations that are referenced in tasks. operationId: deleteDestination x-acl: - addObject diff --git a/specs/ingestion/paths/destinations/destinations.yml b/specs/ingestion/paths/destinations/destinations.yml index 6dea60efdc..a3d940e4c9 100644 --- a/specs/ingestion/paths/destinations/destinations.yml +++ b/specs/ingestion/paths/destinations/destinations.yml @@ -1,8 +1,8 @@ get: tags: - destinations - summary: Get a list of destinations. - description: Get a list of destinations for the given query parameters, with pagination details. + summary: List destinations. + description: Retrieves a list of destinations. operationId: getDestinations x-acl: - addObject @@ -41,7 +41,7 @@ post: tags: - destinations summary: Create a destination. - description: Create a destination. + description: Creates a new destination. operationId: createDestination x-acl: - addObject diff --git a/specs/ingestion/paths/destinations/searchDestinations.yml b/specs/ingestion/paths/destinations/searchDestinations.yml index 2702bd45a0..338309bf0d 100644 --- a/specs/ingestion/paths/destinations/searchDestinations.yml +++ b/specs/ingestion/paths/destinations/searchDestinations.yml @@ -1,8 +1,8 @@ post: tags: - destinations - summary: Search among destinations. - description: Search among destinations with a defined set of parameters. + summary: Search for destinations. + description: Searches for destinations. operationId: searchDestinations x-acl: - addObject diff --git a/specs/ingestion/paths/runs/events/eventID.yml b/specs/ingestion/paths/runs/events/eventID.yml index 257854c8a9..952ee70336 100644 --- a/specs/ingestion/paths/runs/events/eventID.yml +++ b/specs/ingestion/paths/runs/events/eventID.yml @@ -1,8 +1,8 @@ get: tags: - observability - summary: Get an event. - description: Get a single event for a specific runID. + summary: Retrieve a task run event. + description: Retrieves a single task run event by its ID. operationId: getEvent x-acl: - addObject diff --git a/specs/ingestion/paths/runs/events/events.yml b/specs/ingestion/paths/runs/events/events.yml index b8f70513d3..d995a8c310 100644 --- a/specs/ingestion/paths/runs/events/events.yml +++ b/specs/ingestion/paths/runs/events/events.yml @@ -1,8 +1,8 @@ get: tags: - observability - summary: Get a list of events. - description: Get a list of events associated to the given runID, for the given query parameters. + summary: List task run events. + description: Retrieves a list of events for a task run, identified by it's ID. operationId: getEvents x-acl: - addObject @@ -18,12 +18,12 @@ get: - $ref: '../../../common/parameters.yml#/order' - name: startDate in: query - description: The start date (in RFC3339 format) of the events fetching window. Defaults to 'now'-3 hours if omitted. + description: Date and time in RFC3339 format for the earliest events to retrieve. By default, the current time minus three hours is used. schema: type: string - name: endDate in: query - description: The end date (in RFC3339 format) of the events fetching window. Defaults to 'now' days if omitted. + description: Date and time in RFC3339 format for the latest events to retrieve. By default, the current time is used. schema: type: string responses: diff --git a/specs/ingestion/paths/runs/runID.yml b/specs/ingestion/paths/runs/runID.yml index 6a1fe8dcb6..039fe47b93 100644 --- a/specs/ingestion/paths/runs/runID.yml +++ b/specs/ingestion/paths/runs/runID.yml @@ -1,8 +1,8 @@ get: tags: - observability - summary: Get a run. - description: Get a single run for the given ID. + summary: Retrieve a task run. + description: Retrieve a single task run by its ID. operationId: getRun x-acl: - addObject diff --git a/specs/ingestion/paths/runs/runs.yml b/specs/ingestion/paths/runs/runs.yml index 5fca9a09df..b739cb9a58 100644 --- a/specs/ingestion/paths/runs/runs.yml +++ b/specs/ingestion/paths/runs/runs.yml @@ -1,8 +1,8 @@ get: tags: - observability - summary: Get a list of runs. - description: Get a list of runs for the given query parameters, with pagination details. + summary: List task runs. + description: Retrieve a list of task runs. operationId: getRuns x-acl: - addObject @@ -17,12 +17,12 @@ get: - $ref: '../../common/parameters.yml#/order' - name: startDate in: query - description: The start date (in RFC3339 format) of the runs fetching window. Defaults to 'now'-7 days if omitted. + description: Date in RFC3339 format for the earliest run to retrieve. By default, the current day minus seven days is used. schema: type: string - name: endDate in: query - description: The end date (in RFC3339 format) of the runs fetching window. Defaults to 'now' days if omitted. + description: Date in RFC3339 format for the latest run to retrieve. By default, the current day is used. schema: type: string responses: diff --git a/specs/ingestion/paths/sources/discover.yml b/specs/ingestion/paths/sources/discover.yml index 33fae7f4d5..f03f9a57dc 100644 --- a/specs/ingestion/paths/sources/discover.yml +++ b/specs/ingestion/paths/sources/discover.yml @@ -2,7 +2,10 @@ get: tags: - sources summary: Retrieve a stream listing. - description: Retrieve a stream listing for a given Singer specification compatible docker type source ID. + description: | + Retrieves a stream listing for a source. + + Listing streams only works with sources with `type: docker` and `imageType: singer`. operationId: getDockerSourceStreams x-acl: - addObject @@ -32,8 +35,10 @@ get: post: tags: - sources - summary: Trigger a stream listing request. - description: Trigger a stream listing request for a Singer specification compatible docker type source. + summary: Trigger a stream-listing request. + description: | + Triggers a stream-listing request for a source. + Triggering stream-listing requests only works with sources with `type: docker` and `imageType: singer`. operationId: triggerDockerSourceDiscover x-acl: - addObject diff --git a/specs/ingestion/paths/sources/searchSources.yml b/specs/ingestion/paths/sources/searchSources.yml index a02be00fb8..cf3ebecaa1 100644 --- a/specs/ingestion/paths/sources/searchSources.yml +++ b/specs/ingestion/paths/sources/searchSources.yml @@ -1,8 +1,8 @@ post: tags: - sources - summary: Search among sources. - description: Search among sources with a defined set of parameters. + summary: Search for sources. + description: Searches for sources. operationId: searchSources x-acl: - addObject diff --git a/specs/ingestion/paths/sources/sourceID.yml b/specs/ingestion/paths/sources/sourceID.yml index a8d200d91b..b44fb098e6 100644 --- a/specs/ingestion/paths/sources/sourceID.yml +++ b/specs/ingestion/paths/sources/sourceID.yml @@ -1,8 +1,8 @@ get: tags: - sources - summary: Get a source. - description: Get the source of the given sourceID. + summary: Retrieve a source. + description: Retrieve a source by its ID. operationId: getSource x-acl: - addObject @@ -24,7 +24,7 @@ patch: tags: - sources summary: Update a source. - description: Update the source of the given sourceID. + description: Updates a source by its ID. operationId: updateSource x-acl: - addObject @@ -52,7 +52,7 @@ delete: tags: - sources summary: Delete a source. - description: Soft delete the source of the given sourceID. + description: Deletes a source by its ID. You can't delete sources that are referenced in tasks. operationId: deleteSource x-acl: - addObject diff --git a/specs/ingestion/paths/sources/sources.yml b/specs/ingestion/paths/sources/sources.yml index 7cf432d487..21f32b0605 100644 --- a/specs/ingestion/paths/sources/sources.yml +++ b/specs/ingestion/paths/sources/sources.yml @@ -1,8 +1,8 @@ get: tags: - sources - summary: Get a list of sources. - description: Get a list of sources for the given query parameters, with pagination details. + summary: List sources. + description: Retrieves a list of sources. operationId: getSources x-acl: - addObject @@ -41,7 +41,7 @@ post: tags: - sources summary: Create a source. - description: Create a source. + description: Creates a new source. operationId: createSource x-acl: - addObject diff --git a/specs/ingestion/paths/tasks/disableTask.yml b/specs/ingestion/paths/tasks/disableTask.yml index 9c8759ffe0..3c332b0731 100644 --- a/specs/ingestion/paths/tasks/disableTask.yml +++ b/specs/ingestion/paths/tasks/disableTask.yml @@ -2,7 +2,7 @@ put: tags: - tasks summary: Disable a task. - description: Disable the task of the given taskID. + description: Disables a task. operationId: disableTask x-acl: - addObject diff --git a/specs/ingestion/paths/tasks/enableTask.yml b/specs/ingestion/paths/tasks/enableTask.yml index 0e6d7a7e79..633516dca0 100644 --- a/specs/ingestion/paths/tasks/enableTask.yml +++ b/specs/ingestion/paths/tasks/enableTask.yml @@ -2,7 +2,7 @@ put: tags: - tasks summary: Enable a task. - description: Enable the task of the given taskID. + description: Enables a task. operationId: enableTask x-acl: - addObject diff --git a/specs/ingestion/paths/tasks/runTask.yml b/specs/ingestion/paths/tasks/runTask.yml index c8186979b4..4043cf83db 100644 --- a/specs/ingestion/paths/tasks/runTask.yml +++ b/specs/ingestion/paths/tasks/runTask.yml @@ -2,7 +2,7 @@ post: tags: - tasks summary: Run a task. - description: Run the task of the given taskID. + description: Runs a task. You can check the status of task runs with the observability endpoints. operationId: runTask x-acl: - addObject diff --git a/specs/ingestion/paths/tasks/searchTasks.yml b/specs/ingestion/paths/tasks/searchTasks.yml index b70b786c4e..8b370be690 100644 --- a/specs/ingestion/paths/tasks/searchTasks.yml +++ b/specs/ingestion/paths/tasks/searchTasks.yml @@ -1,8 +1,8 @@ post: tags: - tasks - summary: Search among tasks. - description: Search among tasks with a defined set of parameters. + summary: Search for tasks. + description: Searches for tasks. operationId: searchTasks x-acl: - addObject diff --git a/specs/ingestion/paths/tasks/taskID.yml b/specs/ingestion/paths/tasks/taskID.yml index ca8ea8e6b9..45189035d6 100644 --- a/specs/ingestion/paths/tasks/taskID.yml +++ b/specs/ingestion/paths/tasks/taskID.yml @@ -1,8 +1,8 @@ get: tags: - tasks - summary: Get a task. - description: Get the task of the given taskID. + summary: Retrieve a task. + description: Retrieves a task by its ID. operationId: getTask x-acl: - addObject @@ -24,7 +24,7 @@ patch: tags: - tasks summary: Update a task. - description: Update the task of the given taskID. + description: Updates a task by its ID. operationId: updateTask parameters: - $ref: '../../common/parameters.yml#/pathTaskID' @@ -48,7 +48,7 @@ delete: tags: - tasks summary: Delete a task. - description: Soft delete the task of the given taskID. + description: Deletes a task by its ID. operationId: deleteTask parameters: - $ref: '../../common/parameters.yml#/pathTaskID' diff --git a/specs/ingestion/paths/tasks/tasks.yml b/specs/ingestion/paths/tasks/tasks.yml index 2456834f3c..5988c855db 100644 --- a/specs/ingestion/paths/tasks/tasks.yml +++ b/specs/ingestion/paths/tasks/tasks.yml @@ -1,8 +1,8 @@ get: tags: - tasks - summary: Get a list of tasks. - description: Get a list of tasks for the given query parameters, with pagination details. + summary: List tasks. + description: Retrieves a list of tasks. operationId: getTasks x-acl: - addObject @@ -26,7 +26,7 @@ get: schema: title: listTasksResponse type: object - description: A list of tasks with pagination details. + description: Configured tasks and pagination information. additionalProperties: false properties: tasks: @@ -45,10 +45,10 @@ post: tags: - tasks summary: Create a task. - description: Create a task. + description: Creates a new task. operationId: createTask requestBody: - description: '' + description: Request body for creating a task. content: application/json: schema: diff --git a/specs/ingestion/spec.yml b/specs/ingestion/spec.yml index 5f7298ad79..891cfa3831 100644 --- a/specs/ingestion/spec.yml +++ b/specs/ingestion/spec.yml @@ -1,8 +1,59 @@ openapi: 3.0.2 info: title: Ingestion API - description: API powering the Data Ingestion connectors of Algolia. - version: '1.0' + description: | + The Ingestion API lets you connect third-party services and platforms with Algolia and schedule tasks to ingest your data. + The Ingestion API powers the no-code [data connectors](https://dashboard.algolia.com/connectors). + + # Base URLs + + The base URLs for making requests to the Ingestion API are: + + - `https://data.us.algolia.com` + - `https://data.eu.algolia.com` + + Use the URL that matches your [analytics region](https://dashboard.algolia.com/account/infrastructure/analytics). + + **All requests must use HTTPS.** + + # Authentication + + To authenticate your API requests, add these headers: + +
+
x-algolia-application-id
+
Your Algolia application ID.
+
x-algolia-api-key
+
+ An API key with the necessary permissions to make the request. + The required access control list (ACL) to make a request is listed in each endpoint's reference. +
+
+ + You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account). + + # Request format + + Request bodies must be JSON objects. + + # Response status and errors + + Response bodies are JSON objects. + Deleting a user token returns an empty response body with rate-limiting information as headers. + + Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status. + Error responses have a `message` property with more information. + + The Insights API doesn't validate if the event parameters such as `indexName`, `objectIDs`, or `userToken`, + correspond to anything in the Search API. It justs checks if they're formatted correctly. + Check the [Events](https://dashboard.algolia.com/events/health) health section, + whether your events can be used for Algolia features such as Analytics, or Dynamic Re-Ranking. + + # Version + + The current version of the Insights API is version 1, as indicated by the `/1/` in each endpoint's URL. + + version: 1.0.0 components: securitySchemes: appId: @@ -23,19 +74,34 @@ security: tags: - name: authentications x-displayName: Authentications - description: An authentication describe the way we connect to Algolia, or any supported connector. + description: Authentication resources describe how to connect to a source or destination. - name: destinations x-displayName: Destinations - description: A destination refers to an Algolia product (Search, Insight, Recommend, ...). + description: | + Destinations are Algolia products or features where your data should be used, such as a search index or events. + Algolia destinations require authentication with the `algolia` type. + You can reference authentications by their ID when creating destinations. - name: observability x-displayName: Observability - description: The observability API associates a run to a task execution. + description: Check the status and details of your task runs. A run is one instance of a configured task. - name: sources x-displayName: Sources - description: A source describe the platform informations. + description: | + Sources are third-party platforms or services from where you want to ingest your data. + Sources may require authentication. To interact with such sources, you can reference an authentication resource by its ID. - name: tasks x-displayName: Tasks - description: A Task describe how we fetch the data (onDemand, schedule, subscription) from a source and how we index it on the Algolia side. + 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. +x-tagGroups: + - name: Resources + tags: + - authentications + - sources + - destinations + - tasks + - observability paths: # ###################### # ### Custom request ### diff --git a/templates/java/api.mustache b/templates/java/api.mustache index d9a64b61c8..72d0ce48da 100644 --- a/templates/java/api.mustache +++ b/templates/java/api.mustache @@ -24,6 +24,7 @@ import java.util.ArrayList; import java.util.HashMap; import java.util.List; import java.util.Map; +import java.util.UUID; {{/fullJavaUtil}} import java.util.stream.Collectors; import java.util.stream.Stream; @@ -224,4 +225,4 @@ public class {{classname}} extends ApiClient { {{> api_helpers}} } -{{/operations}} +{{/operations}} \ No newline at end of file