chore(specs): update composition specs for the doc website (#4450)

Author: e-krebs

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

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:
@@ -34,18 +108,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
-    description: Search one or more indices for matching records or facet values.
+  - name: search
+    x-displayName: Search
+    description: Search one composition for matching records or facet values.
 x-tagGroups:
-  - name: Search
+  - name: Compositions
     tags:
-      - Compositions
+      - search
 paths:
   # ########################
   # ### Search Endpoints ###