Add api spec for tiering of indices from hot to warm

Signed-off-by: Neetika Singhal <[email protected]>

CHANGELOG.md

@@ -56,6 +56,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added test coverage ([#443](https://github.com/opensearch-project/opensearch-api-specification/pull/443))
 - Added `--opensearch-version` to `merger` that excludes schema elements per semver ([#428](https://github.com/opensearch-project/opensearch-api-specification/pull/428))
 - Added `retry` to `tester` to support asynchronous tasks ([453](https://github.com/opensearch-project/opensearch-api-specification/pull/453))
+- Added `/{index}/_tier` api spec for tiering of indices ([#368](https://github.com/opensearch-project/opensearch-api-specification/pull/368))
 
 ### Changed
 

spec/namespaces/indices.yaml

@@ -1793,6 +1793,22 @@ paths:
       responses:
         '200':
           $ref: '#/components/responses/indices.stats@200'
+  /{index}/_tier/warm:
+    post:
+      operationId: indices.tier_warm.0
+      x-operation-group: indices.tier_warm
+      x-version-added: 2.16.0
+      description: Tier the index to warm in the cluster.
+      parameters:
+        - $ref: '#/components/parameters/indices.tier::path.index'
+        - $ref: '#/components/parameters/indices.tier::query.allow_no_indices'
+        - $ref: '#/components/parameters/indices.tier::query.cluster_manager_timeout'
+        - $ref: '#/components/parameters/indices.tier::query.ignore_unavailable'
+        - $ref: '#/components/parameters/indices.tier::query.timeout'
+        - $ref: '#/components/parameters/indices.tier::query.wait_for_completion'
+      responses:
+        '200':
+          $ref: '#/components/responses/indices.tier_warm@200'
   /{index}/_upgrade:
     get:
       operationId: indices.get_upgrade.1
@@ -2743,6 +2759,24 @@ components:
             required:
               - _all
               - _shards
+    indices.tier_warm@200:
+      description: tiering response for indices target to warm tier
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              acknowledged:
+                description: Whether the request has been acknowledged
+                type: boolean
+              failed_indices:
+                description: List of failed indices
+                type: array
+                items:
+                  $ref: '../schemas/tier.yaml#/components/schemas/FailedIndex'
+            required:
+              - acknowledged
+              - failed_indices
     indices.update_aliases@200:
       description: ''
       content:
@@ -5126,6 +5160,59 @@ components:
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Level'
       style: form
+    indices.tier::path.index:
+      in: path
+      name: index
+      description: |-
+        Comma-separated list of data streams, indices, and aliases to tier from hot to warm.
+        Supports wildcards (`*`).
+        To search all data streams or indices, omit this parameter or use `*` or `_all`.
+      required: true
+      schema:
+        $ref: '../schemas/_common.yaml#/components/schemas/Indices'
+      style: simple
+    indices.tier::query.allow_no_indices:
+      in: query
+      name: allow_no_indices
+      description: |-
+        If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices.
+        This behavior applies even if the request targets other open indices.
+      schema:
+        type: boolean
+        default: false
+      style: form
+    indices.tier::query.cluster_manager_timeout:
+      name: cluster_manager_timeout
+      in: query
+      description: Operation timeout for connection to cluster-manager node.
+      schema:
+        $ref: '../schemas/_common.yaml#/components/schemas/Duration'
+      x-version-added: 2.0.0
+    indices.tier::query.ignore_unavailable:
+      in: query
+      name: ignore_unavailable
+      description: If `false`, the request returns an error if it targets a missing or closed index.
+      schema:
+        type: boolean
+        default: false
+      style: form
+    indices.tier::query.timeout:
+      in: query
+      name: timeout
+      description: |-
+        Period to wait for a response.
+        If no response is received before the timeout expires, the request fails and returns an error.
+      schema:
+        $ref: '../schemas/_common.yaml#/components/schemas/Duration'
+      style: form
+    indices.tier::query.wait_for_completion:
+      name: wait_for_completion
+      in: query
+      description: Wait until the operation has completed before returning.
+      schema:
+        type: boolean
+        default: true
+        description: Wait until the operation has completed before returning.
     indices.update_aliases::query.cluster_manager_timeout:
       name: cluster_manager_timeout
       in: query

spec/schemas/tier.yaml

@@ -0,0 +1,17 @@
+openapi: 3.1.0
+info:
+  title: Schemas of tier_hot_to_warm category
+  description: Schemas of tier_hot_to_warm category
+  version: 1.0.0
+paths: {}
+components:
+  schemas:
+    FailedIndex:
+      type: object
+      properties:
+        index:
+          description: Index name
+          $ref: '_common.yaml#/components/schemas/IndexName'
+        error:
+          description: Error message
+          type: string

tests/indices/tier/warm.yaml

@@ -0,0 +1,38 @@
+$schema: ../../json_schemas/test_story.schema.yaml
+
+description: Test endpoints relevant to tiering of index to warm.
+epilogues:
+  - path: /books
+    method: DELETE
+    status: [200, 404]
+  - path: /games
+    method: DELETE
+    status: [200, 404]
+chapters:
+  - synopsis: Create an indices named `books` and `games` with default settings.
+    path: /{index}
+    method: PUT
+    parameters:
+      index: books,games
+
+  - synopsis: Check if the indices `games` and `books` exists. They should.
+    path: /{index}
+    method: HEAD
+    parameters:
+      index: books,games
+      allow_no_indices: true
+      expand_wildcards: none
+      flat_settings: true
+      include_defaults: true
+      ignore_unavailable: true
+      local: true
+
+  - synopsis: Tier the `books` and `games` indices from hot to warm.
+    version: '>= 2.16'
+    path: /{index}/_tier/warm
+    method: POST
+    parameters:
+      index: books,games
+    response:
+      status: 200
+