From eb12de4a040f4fc858310e0e32b025de849998b4 Mon Sep 17 00:00:00 2001 From: Emmanuel Date: Mon, 10 Feb 2025 17:26:14 +0100 Subject: [PATCH 1/2] chore: apply changes from doc PR to make them permanent https://github.com/algolia/doc/pull/9721 --- specs/composition-full/paths/search/search.yml | 2 +- specs/composition/spec.yml | 13 ++++++++----- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/specs/composition-full/paths/search/search.yml b/specs/composition-full/paths/search/search.yml index 317715ef48..693426b754 100644 --- a/specs/composition-full/paths/search/search.yml +++ b/specs/composition-full/paths/search/search.yml @@ -1,6 +1,6 @@ post: tags: - - Search + - search operationId: search x-use-read-transporter: true x-cacheable: true diff --git a/specs/composition/spec.yml b/specs/composition/spec.yml index f2feb9814e..a038f8d2ae 100644 --- a/specs/composition/spec.yml +++ b/specs/composition/spec.yml @@ -34,18 +34,21 @@ security: - appId: [] apiKey: [] tags: - - name: Compositions + - name: compositions + x-displayName: Compositions description: | Manage your compositions and composition settings. - - name: Rules + - name: rules + x-displayName: Rules description: | Manage your compositions rules. - - name: Search + - name: search + x-displayName: Search description: Search one or more indices for matching records or facet values. x-tagGroups: - - name: Search + - name: Compositions tags: - - Compositions + - search paths: # ######################## # ### Search Endpoints ### From 2311922a08f37b762439a4b501fed829b9e3f392 Mon Sep 17 00:00:00 2001 From: Emmanuel Date: Mon, 10 Feb 2025 17:48:04 +0100 Subject: [PATCH 2/2] chore: add proper description for the composition API + correct the search section description --- specs/composition/spec.yml | 80 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 77 insertions(+), 3 deletions(-) diff --git a/specs/composition/spec.yml b/specs/composition/spec.yml index a038f8d2ae..4047057024 100644 --- a/specs/composition/spec.yml +++ b/specs/composition/spec.yml @@ -1,7 +1,81 @@ openapi: 3.0.2 info: - title: Composition API - description: Composition API. + title: Composition API (beta) + description: | + The Algolia Composition API lets you run search requests on your Compositions. + + ## Client libraries + + Use Algolia's API clients and libraries to reliably integrate Algolia's APIs with your apps. + The official API clients are covered by Algolia's [Service Level Agreement](https://www.algolia.com/policies/sla/). + + See: [Algolia's ecosystem](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem/) + + ## Base URLs + + The base URLs for requests to the Composition API are: + + - `https://{APPLICATION_ID}.algolia.net` + - `https://{APPLICATION_ID}-dsn.algolia.net`. + If your subscription includes a [Distributed Search Network](https://dashboard.algolia.com/infra), + this ensures that requests are sent to servers closest to users. + + Both URLs provide high availability by distributing requests with load balancing. + + **All requests must use HTTPS.** + + ## Retry strategy + + To guarantee high availability, implement a retry strategy for all API requests using the URLs of your servers as fallbacks: + + - `https://{APPLICATION_ID}-1.algolianet.com` + - `https://{APPLICATION_ID}-2.algolianet.com` + - `https://{APPLICATION_ID}-3.algolianet.com` + + These URLs use a different DNS provider than the primary URLs. + You should randomize this list to ensure an even load across the three servers. + + All Algolia API clients implement this retry strategy. + + ## 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 + + Depending on the endpoint, request bodies are either JSON objects or arrays of JSON objects, + + ## Parameters + + Parameters are passed as query parameters for GET and DELETE requests, + and in the request body for POST and PUT requests. + + Query parameters must be [URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding). + Non-ASCII characters must be UTF-8 encoded. + Plus characters (`+`) are interpreted as spaces. + Arrays as query parameters must be one of: + + - A comma-separated string: `attributesToRetrieve=title,description` + - A URL-encoded JSON array: `attributesToRetrieve=%5B%22title%22,%22description%22%D` + + ## Response status and errors + + The Composition API returns JSON responses. + Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response. + + 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. + + ## Version + + The current version of the Composition API is version 1, as indicated by the `/1/` in each endpoint's URL. + version: 1.0.0 components: securitySchemes: @@ -44,7 +118,7 @@ tags: Manage your compositions rules. - name: search x-displayName: Search - description: Search one or more indices for matching records or facet values. + description: Search one composition for matching records or facet values. x-tagGroups: - name: Compositions tags: