From 0f8d4432bb6174153fbca3fd2ad1249ec2f68159 Mon Sep 17 00:00:00 2001 From: Kai Welke Date: Wed, 13 Mar 2024 11:55:09 +0100 Subject: [PATCH] feat(specs): insights api reference (#2859) Co-authored-by: shortcuts --- .../common/schemas/EventAttributes.yml | 39 ++++++------ specs/insights/paths/deleteUserToken.yml | 18 +++--- specs/insights/paths/pushEvents.yml | 8 +-- specs/insights/spec.yml | 60 ++++++++++++++++++- 4 files changed, 86 insertions(+), 39 deletions(-) diff --git a/specs/insights/common/schemas/EventAttributes.yml b/specs/insights/common/schemas/EventAttributes.yml index d0022190ec..ff1141bae2 100644 --- a/specs/insights/common/schemas/EventAttributes.yml +++ b/specs/insights/common/schemas/EventAttributes.yml @@ -4,7 +4,7 @@ eventName: maxLength: 64 pattern: '[\x20-\x7E]{1,64}' description: | - The name of the event, up to 64 ASCII characters. + Event name, up to 64 ASCII characters. Consider naming events consistently—for example, by adopting Segment's [object-action](https://segment.com/academy/collecting-data/naming-conventions-for-clean-data/#the-object-action-framework) @@ -13,7 +13,7 @@ eventName: index: type: string - description: The name of an Algolia index. + description: Index name to which the event's items belong. example: YourIndexName userToken: @@ -22,9 +22,10 @@ userToken: maxLength: 129 pattern: '[a-zA-Z0-9_=/+-]{1,129}' description: | - An anonymous or pseudonymous user identifier. + Anonymous or pseudonymous user identifier. - > **Note**: Never include personally identifiable information in user tokens. + Don't use personally identifiable information in user tokens. + For more information, see [User token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken/). example: test-user-1 authenticatedUserToken: @@ -33,16 +34,19 @@ authenticatedUserToken: maxLength: 129 pattern: '[a-zA-Z0-9_=/+-]{1,129}' description: | - An identifier for authenticated users. + Identifier for authenticated users. - > **Note**: Never include personally identifiable information in user tokens. + When the user signs in, you can get an identifier from your system and send it as `authenticatedUserToken`. + This lets you keep using the `userToken` from before the user signed in, while providing a reliable way to identify users across sessions. + Don't use personally identifiable information in user tokens. + For more information, see [User token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken/). example: c6a52c02-d0c7-4b53-8ce3-2b8fd202f3f9 timestamp: type: integer format: int64 description: | - The timestamp of the event in milliseconds in [Unix epoch time](https://wikipedia.org/wiki/Unix_time). + Timestamp of the event in milliseconds in [Unix epoch time](https://wikipedia.org/wiki/Unix_time). By default, the Insights API uses the time it receives an event as its timestamp. example: 1687193127 @@ -60,7 +64,7 @@ queryID: objectIDs: type: array - description: The object IDs of the records that are part of the event. + description: Object IDs of the records that are part of the event. items: type: string minItems: 1 @@ -70,9 +74,10 @@ objectIDs: filters: type: array description: | - Facet filters. + Applied facet filters. - Each facet filter string must be URL-encoded, such as, `discount:10%25`. + Facet filters are `facet:value` pairs. + Facet values must be URL-encoded, such as, `discount:10%25`. items: type: string minItems: 1 @@ -87,15 +92,13 @@ positions: minItems: 1 maxItems: 20 description: | - The position of the clicked item the search results. + Position of the clicked item the search results. - The first search result has a position of 1 (not 0). You must provide 1 `position` for each `objectID`. example: [1, 2, 5] price: - description: | - The total price of a product, including any discounts, in units of `currency`. + description: Total price of a product, including any discounts, in units of `currency`. oneOf: - type: number format: double @@ -104,8 +107,7 @@ price: example: '9.99' discount: - description: | - The absolute value of the discount for this product, in units of `currency`. + description: Absolute value of the discount for this product, in units of `currency`. oneOf: - type: number format: double @@ -118,8 +120,8 @@ quantity: format: int32 example: 2 description: | - The quantity of a product that has been purchased or added to the cart. - The total value of a purchase is the sum of `quantity` multiplied with the `price` for each purchased item. + Quantity of a product that has been purchased or added to the cart. + The total purchase value is the sum of `quantity` multiplied with the `price` for each purchased item. objectData: type: object @@ -174,7 +176,6 @@ objectDataAfterSearchList: currency: type: string - format: ISO 4217 description: Three-letter [currency code](https://www.iso.org/iso-4217-currency-codes.html). example: EUR diff --git a/specs/insights/paths/deleteUserToken.yml b/specs/insights/paths/deleteUserToken.yml index 957a61ae4f..ba01dd485c 100644 --- a/specs/insights/paths/deleteUserToken.yml +++ b/specs/insights/paths/deleteUserToken.yml @@ -4,33 +4,29 @@ delete: operationId: deleteUserToken summary: Delete user token. description: | - Delete all events related to a certain user token from events metrics and analytics. - To delete a personalization user profile, see [Delete a user profile](https://www.algolia.com/doc/rest-api/personalization/#delete-a-user-profile). + Deletes all events related to the specified user token from events metrics and analytics. + To delete a personalization user profile, see [Delete a user profile](/specs/personalization#tag/profiles/operation/deleteUserProfile). parameters: - name: userToken in: path - description: The user token for which to delete all associated events. + description: User token for which to delete all associated events. required: true schema: - type: string - minLength: 1 - maxLength: 129 - pattern: '[a-zA-Z0-9_=/+]{1,129}' - example: test-user-1 + $ref: '../common/schemas/EventAttributes.yml#/userToken' responses: '204': description: No content. headers: x-ratelimit-limit: - description: The current rate limit. The maximum number of requests you can make to this endpoint. + description: Maximum number of requests you can make to this endpoint. schema: type: integer x-ratelimit-remaining: - description: The number of remaining API requests you can make to this endpoint before reaching the rate limit. + description: Number of remaining API requests you can make to this endpoint before reaching the rate limit. schema: type: integer x-ratelimit-reset: - description: The timestamp in Unix epoch time when the rate limit will reset. + description: Timestamp in Unix epoch time when the rate limit will reset. schema: type: integer diff --git a/specs/insights/paths/pushEvents.yml b/specs/insights/paths/pushEvents.yml index b8ca102f9e..0fe8fd8ec5 100644 --- a/specs/insights/paths/pushEvents.yml +++ b/specs/insights/paths/pushEvents.yml @@ -4,7 +4,7 @@ post: operationId: pushEvents summary: Send events. description: | - Send a list of events to the Insights API. + Sends a list of events to the Insights API. You can include up to 1,000 events in a single request, but the request body must be smaller than 2 MB. @@ -22,11 +22,7 @@ post: events: type: array description: | - List of click and conversion events. - - An event is an object representing a user interaction. - Events have attributes that describe the interaction, - such as an event name, a type, or a user token. + Click and conversion events. **All** events must be valid, otherwise the API returns an error. minItems: 1 diff --git a/specs/insights/spec.yml b/specs/insights/spec.yml index 38e3091589..83b9cfb219 100644 --- a/specs/insights/spec.yml +++ b/specs/insights/spec.yml @@ -1,12 +1,66 @@ openapi: 3.0.2 info: title: Insights API - description: >- - The Algolia Insights API lets you collect events related to your search and discovery experience. - Events represent actions that users take on your app or website. + description: | + The Insights API lets you collect events related to your search and discovery experience. + Events represent user interactions with your app or website. They unlock powerful features, such as recommendations, personalization, smarter search results, and analytics that help you optimize your user experience. + + # Client libraries + + Use Algolia's API clients, libraries, and integrations to collect events from your UI and send them to the Insights API. + See: [Algolia's ecosystem](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem/) + + # Base URLs + + The base URLs for making requests to the Insights API are: + + - `https://insights.us.algolia.io` (`https://insights.algolia.io` is an alias) + - `https://insights.de.algolia.io` + + **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 +externalDocs: + url: https://www.algolia.com/doc/guides/sending-events/getting-started/ + description: Events components: securitySchemes: appId: