Add api spec for tiering of indices from hot to warm

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

CHANGELOG.md

@@ -55,6 +55,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added `plugins` to NodeInfoSettings ([#442](https://github.com/opensearch-project/opensearch-api-specification/pull/442)) 
 - 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 api spec for tiering of indices from hot to warm ([#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_hot_to_warm.0
+      x-operation-group: indices.tier_hot_to_warm
+      x-version-added: 2.16.0
+      description: Tier the index from hot to warm in the cluster.
+      parameters:
+        - $ref: '#/components/parameters/indices.tier_hot_to_warm::path.index'
+        - $ref: '#/components/parameters/indices.tier_hot_to_warm::query.allow_no_indices'
+        - $ref: '#/components/parameters/indices.tier_hot_to_warm::query.cluster_manager_timeout'
+        - $ref: '#/components/parameters/indices.tier_hot_to_warm::query.ignore_unavailable'
+        - $ref: '#/components/parameters/indices.tier_hot_to_warm::query.timeout'
+        - $ref: '#/components/parameters/indices.tier_hot_to_warm::query.wait_for_completion'
+      responses:
+        '200':
+          $ref: '#/components/responses/indices.tier_hot_to_warm@200'
   /{index}/_upgrade:
     get:
       operationId: indices.get_upgrade.1
@@ -2743,6 +2759,22 @@ components:
             required:
               - _all
               - _shards
+    indices.tier_hot_to_warm@200:
+      description: Hot to warm tiering response
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              acknowledged:
+                type: boolean
+              failed_indices:
+                type: array
+                items:
+                  $ref: '../schemas/tier.hot_to_warm.yaml#/components/schemas/FailedIndex'
+            required:
+              - acknowledged
+              - failed_indices
     indices.update_aliases@200:
       description: ''
       content:
@@ -5126,6 +5158,59 @@ components:
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Level'
       style: form
+    indices.tier_hot_to_warm::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_hot_to_warm::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_hot_to_warm::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_hot_to_warm::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_hot_to_warm::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_hot_to_warm::query.wait_for_completion:
+      name: wait_for_completion
+      in: query
+      description: Should this request wait until the operation has completed before returning.
+      schema:
+        type: boolean
+        default: true
+        description: Should this request wait until the operation has completed before returning.
     indices.update_aliases::query.cluster_manager_timeout:
       name: cluster_manager_timeout
       in: query

spec/schemas/tier.hot_to_warm.yaml

@@ -0,0 +1,15 @@
+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:
+          $ref: '_common.yaml#/components/schemas/IndexName'
+        error:
+          type: string

tests/indices/index.yaml

@@ -83,6 +83,14 @@ chapters:
     parameters:
       index: books
 
+  - synopsis: Tier the `books` and `games` indices from hot to warm.
+    path: /{index}/_tier/warm
+    method: POST
+    parameters:
+      index: books,games
+    response:
+      status: 200
+
   - synopsis: Delete the `books` and `games` indices.
     path: /{index}
     method: DELETE