docs(specs): Review OpenAPI Search API (record operations)

specs/search/paths/objects/batch.yml

@@ -2,8 +2,12 @@ post:
   tags:
     - Records
   operationId: batch
-  summary: Batch operations to one index.
-  description: Perform multiple write operations targeting one index, in a single API call.
+  summary: Batch write operations on one index.
+  description: >
+    To reduce the time spent on network round trips, you can perform several write actions in a single API call.
+    Actions are applied in the order they are specified.
+    
+    The supported `action`s are equivalent to the individual operations of the same name.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
   requestBody:
@@ -12,7 +16,7 @@ post:
       application/json:
         schema:
           title: batchWriteParams
-          description: The `batch` parameters.
+          description: Batch parameters.
           type: object
           additionalProperties: false
           properties:
@@ -27,7 +31,8 @@ post:
                     $ref: 'common/schemas.yml#/action'
                   body:
                     type: object
-                    description: arguments to the operation (depends on the type of the operation).
+                    description: Operation arguments (varies with specified `action`).
+                    example: {'name': 'Betty Jane McCamey','company': 'Vita Foods Inc.','email': 'betty@mccamey.com'}
                 required:
                   - action
                   - body

specs/search/paths/objects/clearObjects.yml

@@ -2,8 +2,8 @@ post:
   tags:
     - Records
   operationId: clearObjects
-  summary: Clear all objects from an index.
-  description: Delete an index's content, but leave settings and index-specific API keys untouched.
+  summary: Delete all records from an index.
+  description: Delete the records but leave settings and index-specific API keys untouched.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
   responses:

specs/search/paths/objects/common/schemas.yml

@@ -8,7 +8,7 @@ action:
     - deleteObject
     - delete
     - clear
-  description: type of operation.
+  description: Type of batch operation.
 
 builtInOperationType:
   type: string
@@ -20,7 +20,7 @@ builtInOperationType:
     - AddUnique
     - IncrementFrom
     - IncrementSet
-  description: The operation to apply on the attribute.
+  description: Operation to apply to the attribute.
 
 attribute:
   type: string
@@ -35,7 +35,7 @@ builtInOperation:
       $ref: '#/builtInOperationType'
     value:
       type: string
-      description: the right-hand side argument to the operation, for example, increment or decrement step, value to add or remove.
+      description: Value that corresponds to the operation, for example an `Increment` or `Decrement` step, `Add` or `Remove` value.
   required:
     - _operation
     - value

specs/search/paths/objects/deleteBy.yml

@@ -2,13 +2,11 @@ post:
   tags:
     - Records
   operationId: deleteBy
-  summary: Delete all records matching the query.
+  summary: Delete all records matching a query.
   description: >
-    Remove all objects matching a filter (including geo filters).
+    This operation doesn't support all the query options, only its filters (numeric, facet, or tag) and geo queries.
 
-    This method enables you to delete one or more objects based on filters (numeric, facet, tag or geo queries).
-
-    It doesn't accept empty filters or a query.
+    It doesn't accept empty filters or queries.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
   requestBody:

specs/search/paths/objects/getObjects.yml

@@ -4,23 +4,25 @@ post:
   operationId: getObjects
   x-use-read-transporter: true
   x-cacheable: true
-  summary: Retrieve one or more objects.
-  description: Retrieve one or more objects, potentially from different indices, in a single API call.
+  summary: Get multiple records.
+  description: >
+    Retrieve one or more records, potentially from different indices, in a single API operation.
+    Results will be received in the same order as the requests.
   requestBody:
     required: true
-    description: The Algolia object.
+    description: Request object.
     content:
       application/json:
         schema:
           title: getObjectsParams
-          description: The `getObjects` parameters.
+          description: Request parameters.
           type: object
           additionalProperties: false
           properties:
             requests:
               type: array
               items:
-                description: getObjects operation on an index.
+                description: Record retrieval operation.
                 title: getObjectsRequest
                 type: object
                 additionalProperties: false
@@ -32,13 +34,16 @@ post:
                     type: array
                     items:
                       type: string
-                    description: List of attributes to retrieve. By default, all retrievable attributes are returned.
+                    description: Attributes to retrieve. If not specified, all retrievable attributes are returned.
+                    example: ['author','title','content']
                   objectID:
                     type: string
-                    description: ID of the object within that index.
+                    description: Record's objectID.
+                    example: '8b9b7619230b1950f653b962fb0dfd6b'
                   indexName:
                     type: string
-                    description: name of the index containing the object.
+                    description: Name of the index containing the required records.
+                    example: books
           required:
             - requests
   responses:
@@ -53,7 +58,7 @@ post:
             properties:
               results:
                 type: array
-                description: List of results fetched.
+                description: Retrieved results.
                 items:
                   type: object
                   description: Fetched object.

specs/search/paths/objects/multipleBatch.yml

@@ -2,15 +2,20 @@ post:
   tags:
     - Records
   operationId: multipleBatch
-  description: Perform multiple write operations, potentially targeting multiple indices, in a single API call.
-  summary: Batch operations to many indices.
+  description: >
+    To reduce the time spent on network round trips, you can perform several write actions in a single API operation.
+    It's a multi-index version of the [`batch` operation](#tag/Records/operation/batch). It can be helpful when, for example, you have one index per user.
+    Actions are applied in the order they are specified.
+    
+    The supported `action`s are equivalent to the individual operations of the same name.
+  summary: Batch write operations on multiple indices.
   requestBody:
     required: true
     content:
       application/json:
         schema:
           title: batchParams
-          description: The `multipleBatch` parameters.
+          description: Batch parameters.
           type: object
           additionalProperties: false
           properties:
@@ -25,10 +30,13 @@ post:
                     $ref: 'common/schemas.yml#/action'
                   body:
                     type: object
-                    description: arguments to the operation (depends on the type of the operation).
+                    description: Operation arguments (varies with specified `action`).
+                    example: >
+                      {'requests':[{'action':'addObject','indexName':'contacts','body':{'name':'Betty Jane McCamey','company':'Vita Foods Inc.','email':'betty@mccamey.com'}},{'action':'addObject','indexName':'public_contacts','body':{'name':'Gayla Geimer','company': "Ortman McCain Co','email':'gayla@geimer.com'}}]}
                   indexName:
                     type: string
                     description: Index to target for this operation.
+                    example: 'index1'
                 required:
                   - action
                   - body
@@ -47,7 +55,7 @@ post:
             properties:
               taskID:
                 type: object
-                description: List of tasksIDs per index.
+                description: TaskIDs per index.
                 additionalProperties:
                   $ref: '../../../common/responses/common.yml#/taskID'
               objectIDs:

specs/search/paths/objects/object.yml

@@ -2,14 +2,21 @@ get:
   tags:
     - Records
   operationId: getObject
-  summary: Retrieve an object.
-  description: Retrieve one object from the index.
+  summary: Get a record.
+  description: To get more than one record, use the [`objects` operation](#tag/Records/operation/getObjects).
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - $ref: '../../../common/parameters.yml#/ObjectID'
     - name: attributesToRetrieve
       in: query
-      description: List of attributes to retrieve. If not specified, all retrievable attributes are returned.
+      description: >
+        Attributes to include with the records in the response.
+        This is useful to reduce the size of the API response.
+        By default, all retrievable attributes are returned.
+
+        `objectID` is always retrieved, even when not specified.
+
+        [`unretrievableAttributes`](https://www.algolia.com/doc/api-reference/api-parameters/unretrievableAttributes/) won't be retrieved unless the request is authenticated with the admin API key.
       schema:
         type: array
         items:
@@ -38,17 +45,19 @@ put:
   tags:
     - Records
   operationId: addOrUpdateObject
-  summary: Add or replace an object.
+  summary: Add or update a record (using objectID).
   description: |
-    Add or replace an object with a given object ID.
-    If the object does not exist, it will be created.
-    If it already exists, it will be replaced.
+    If you use an existing `objectID`, the existing record will be replaced with the new one.
+    
+    To update only some attributes of an existing record, use the [`partial` operation](#tag/Records/operation/partialUpdateObject) instead.
+
+    To add multiple records to your index in a single API request, use the [`batch` operation](#tag/Records/operation/batch).
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - $ref: '../../../common/parameters.yml#/ObjectID'
   requestBody:
     required: true
-    description: The Algolia object.
+    description: Algolia record.
     content:
       application/json:
         schema:
@@ -69,8 +78,8 @@ delete:
   tags:
     - Records
   operationId: deleteObject
-  summary: Delete an object.
-  description: Delete an existing object.
+  summary: Delete a record.
+  description: To delete a set of records matching a query, use the [`deleteByQuery` operation](#tag/Records/operation/deleteBy) instead.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - $ref: '../../../common/parameters.yml#/ObjectID'

specs/search/paths/objects/objects.yml

@@ -2,8 +2,15 @@ post:
   tags:
     - Records
   operationId: saveObject
-  description: Add an object to the index, automatically assigning it an object ID.
-  summary: Add an object to the index.
+  description: >
+    Add a record (object) to an index or replace it.
+
+    If the record doesn't contain an `objectID`, Algolia automatically adds it.
+    
+    If you use an existing `objectID`, the existing record is replaced with the new one.
+    
+    To add multiple records to your index in a single API request, use the [`batch` operation](#tag/Records/operation/batch).
+  summary: Add or update a record.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
   requestBody:
@@ -25,6 +32,8 @@ post:
             properties:
               createdAt:
                 type: string
+                description: Date of creation (ISO-8601 format).
+                example: '2023-06-29T15:15:40.747Z'
               taskID:
                 $ref: '../../../common/responses/common.yml#/taskID'
               objectID:

specs/search/paths/objects/partialUpdate.yml

@@ -2,33 +2,33 @@ post:
   tags:
     - Records
   operationId: partialUpdateObject
-  summary: Partially update an object.
+  summary: Update record attributes.
   x-codegen-request-body-name: attributesToUpdate
   description: >
-    Update one or more attributes of an existing object.
+    Add new attributes or update current ones in an existing record.
 
-    This method lets you update only a part of an existing object, either by adding new attributes or updating existing ones.
-
-    You can partially update several objects in a single method call.
-
-    If the index targeted by this operation doesn't exist yet, it's automatically created.
+    You can use any first-level attribute but not nested attributes. If you specify a [nested attribute](https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/how-to/creating-and-using-nested-attributes/), the engine treats it as a replacement for its first-level ancestor.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - $ref: '../../../common/parameters.yml#/ObjectID'
     - name: createIfNotExists
-      description: Creates the record if it does not exist yet.
+      description: >
+        If the record doesn't exist and the parameter value is:
+          
+        - `true`, a new record will be created.
+        - `false`, the engine will do nothing.
       in: query
       schema:
         type: boolean
         default: true
   requestBody:
     required: true
-    description: Map of attribute(s) to update.
+    description: Object containing attributes to update.
     content:
       application/json:
         schema:
           type: object
-          description: Attribute(s) to update.
+          description: Attributes to update.
           additionalProperties:
             $ref: 'common/schemas.yml#/attributeToUpdate'
   responses: