Add flow_framework namespace specs

.cspell

@@ -191,4 +191,5 @@ urldecode
 vectory
 whoamiprotected
 wordnet
-Yrtsd
+Yrtsd
+reprovision

CHANGELOG.md

@@ -81,6 +81,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added 404 responses to `/_alias/{name}` and `/{index}/_alias/{name}` ([#519](https://github.com/opensearch-project/opensearch-api-specification/pull/519))
 - Added `asynchronous_search` ([#525](https://github.com/opensearch-project/opensearch-api-specification/pull/525))
 - Added `DELETE /_plugins/_ml/tasks/{task_id}` ([#530](https://github.com/opensearch-project/opensearch-api-specification/pull/530))
+- Added `/_plugins/_flow_framework` ([#508](https://github.com/opensearch-project/opensearch-api-specification/issues/508))
 - Added `AwarenessAttributeStats` to `/_cluster/health` ([#534](https://github.com/opensearch-project/opensearch-api-specification/pull/534))
 - Added `cache_reserved_in_bytes` to `ClusterFileSystem` ([#534](https://github.com/opensearch-project/opensearch-api-specification/pull/534))
 - Added `cluster_manager` to `ClusterNodeCount` ([#534](https://github.com/opensearch-project/opensearch-api-specification/pull/534))

spec/namespaces/flow_framework.yaml

@@ -0,0 +1,225 @@
+openapi: 3.1.0
+info:
+  title: OpenSearch Flow Framework API
+  description: OpenSearch Flow Framework API.
+  version: 1.0.0
+paths:
+  /_plugins/_flow_framework/workflow:
+    post:
+      operationId: flow_framework.create.0
+      x-operation-group: flow_framework.create
+      x-version-added: '2.12'
+      description: Create a workflow.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/automating-configurations/api/create-workflow/
+      parameters:
+        - $ref: '#/components/parameters/flow_framework.create::query.provision'
+        - $ref: '#/components/parameters/flow_framework.create::query.reprovision'
+        - $ref: '#/components/parameters/flow_framework.create::query.use_case'
+        - $ref: '#/components/parameters/flow_framework.create::query.validation'
+      requestBody:
+        $ref: '#/components/requestBodies/flow_framework.create'
+      responses:
+        '201':
+          $ref: '#/components/responses/flow_framework.create@201'
+        '403':
+          $ref: '#/components/responses/flow_framework.create@403'
+        '400':
+          $ref: '#/components/responses/flow_framework.create@400'
+  /_plugins/_flow_framework/workflow/{workflow_id}:
+    get:
+      operationId: flow_framework.get.0
+      x-operation-group: flow_framework.get
+      x-version-added: '2.12'
+      externalDocs:
+        url: https://opensearch.org/docs/latest/automating-configurations/api/get-workflow/
+      description: Get a workflow.
+      parameters:
+        - $ref: '#/components/parameters/flow_framework.get::path.workflow_id'
+      responses:
+        '200':
+          $ref: '#/components/responses/flow_framework.get@200'
+        '404':
+          $ref: '#/components/responses/flow_framework.get@404'
+    put:
+      operationId: flow_framework.update.0
+      x-operation-group: flow_framework.update
+      x-version-added: '2.12'
+      description: Update a workflow. You can only update a complete workflow if it has not yet been provisioned.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/automating-configurations/api/create-workflow/
+      parameters:
+        - $ref: '#/components/parameters/flow_framework.update::path.workflow_id'
+        - $ref: '#/components/parameters/flow_framework.update::query.update_fields'
+      requestBody:
+        $ref: '#/components/requestBodies/flow_framework.update'
+      responses:
+        '201':
+          $ref: '#/components/responses/flow_framework.update@201'
+          description: It returns the workflow_id
+        '404':
+          $ref: '#/components/responses/flow_framework.update@404'
+    delete:
+      operationId: flow_framework.delete.0
+      x-operation-group: flow_framework.delete
+      x-version-added: '2.12'
+      description: Delete a workflow.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/automating-configurations/api/delete-workflow/
+      parameters:
+        - $ref: '#/components/parameters/flow_framework.delete::path.workflow_id'
+        - $ref: '#/components/parameters/flow_framework.delete::query.clear_status'
+      responses:
+        '200':
+          $ref: '#/components/responses/flow_framework.delete@200'
+        '400':
+          $ref: '#/components/responses/flow_framework.delete@400'
+        '403':
+          $ref: '#/components/responses/flow_framework.delete@403'
+        '404':
+          $ref: '#/components/responses/flow_framework.delete@404'
+components:
+  parameters:
+    flow_framework.get::path.workflow_id:
+      name: workflow_id
+      in: path
+      required: true
+      schema:
+        type: string
+    flow_framework.update::path.workflow_id:
+      name: workflow_id
+      in: path
+      required: true
+      schema:
+        type: string
+    flow_framework.delete::path.workflow_id:
+      name: workflow_id
+      in: path
+      required: true
+      schema:
+        type: string
+    flow_framework.create::query.provision:
+      in: query
+      name: provision
+      schema:
+        description: Provision the workflow as part of the request
+        type: boolean
+        default: false
+    flow_framework.create::query.reprovision:
+      x-version-added: '2.17'
+      in: query
+      name: reprovision
+      schema:
+        type: boolean
+        default: false
+    flow_framework.create::query.use_case:
+      description: To use a workflow template, specify it in the use_case query parameter when creating a workflow.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/automating-configurations/workflow-templates/#supported-workflow-templates
+      in: query
+      name: use_case
+      schema:
+        type: string
+    flow_framework.create::query.validation:
+      in: query
+      name: validation
+      schema:
+        description: Validate the workflow. Valid values are all (validate the template) and none (do not validate the template). Default is all.
+        type: string
+        default: all
+    flow_framework.update::query.update_fields:
+      in: query
+      name: update_fields
+      schema:
+        description: Update only the fields included in the request body.
+        type: boolean
+        default: false
+    flow_framework.delete::query.clear_status:
+      in: query
+      name: clear_status
+      schema:
+        description: Delete the workflow state (without deprovisioning resources) after deleting the template. OpenSearch deletes the workflow state only if the provisioning status is not IN_PROGRESS. Default is false.
+        type: boolean
+        default: false
+  requestBodies:
+    flow_framework.create:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/flow_framework.common.yaml#/components/schemas/FlowFrameworkCreate'
+    flow_framework.update:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/flow_framework.common.yaml#/components/schemas/FlowFrameworkUpdate'
+  responses:
+    flow_framework.create@201:
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              workflow_id:
+                type: string
+                description: The ID of the workflow to be updated. Required for the PUT method.
+            required:
+              - workflow_id
+    flow_framework.create@403:
+      content:
+        application/json:
+          $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/FlowFrameworkAPIDisabledError'
+    flow_framework.create@400:
+      description: Bad Request - Multiple possible reasons
+      content:
+        application/json:
+          oneOf:
+            - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/BadRequestError'
+            - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/ConflictError'
+            - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/MissingParameterError'
+            - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/ParameterConflictError'
+            - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/MaxWorkflowsLimitError'
+            - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/WorkflowSaveError'
+    flow_framework.update@201:
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              workflow_id:
+                type: string
+                description: The ID of the workflow to be updated. Required for the PUT method.
+            required:
+              - workflow_id
+    flow_framework.delete@200:
+      content:
+        application/json:
+          $ref: '../schemas/flow_framework.common.yaml#/components/schemas/FlowFrameworkDeleteResponse'
+    flow_framework.get@200:
+      content:
+        application/json:
+          $ref: '../schemas/flow_framework.common.yaml#/components/schemas/FlowFrameworkGetResponse'
+    flow_framework.update@404:
+      description: Template Not Found Error
+      content:
+        application/json:
+          $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/TemplateNotFoundError'
+    flow_framework.delete@400:
+      description: Work Flow Id Null Error
+      content:
+        application/json:
+          $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/WorkFlowIdNullError'
+    flow_framework.delete@403:
+      description: Flow Framework API Disabled Error
+      content:
+        application/json:
+          $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/FlowFrameworkAPIDisabledError'
+    flow_framework.delete@404:
+      description: Template Not Found Error
+      content:
+        application/json:
+          $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/TemplateNotFoundError'
+    flow_framework.get@404:
+      description: Template Not Found Error
+      content:
+        application/json:
+          $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/TemplateNotFoundError'

spec/schemas/flow_framework.common.yaml

@@ -0,0 +1,127 @@
+openapi: 3.0.3
+info:
+  title: Schemas of flow_framework.common category
+  description: Schemas of flow_framework.common category
+  version: 1.0.0
+paths: { }
+components:
+  schemas:
+    FlowFrameworkCreate:
+      type: object
+      properties:
+        name:
+          type: string
+          description: The name of the workflow.
+        description:
+          type: string
+          description: A description of the workflow.
+        use_case:
+          type: string
+          description: A use case, which can be used with the Search Workflow API to find related workflows.
+        version:
+          $ref: '#/components/schemas/version'
+        workflows:
+          type: object
+          description: A map of workflows. Presently, only the provision key is supported. The value for the workflow key is a key-value map that includes fields for user_params and lists of nodes and edges.
+      required:
+        - name
+    FlowFrameworkUpdate:
+      type: object
+      properties:
+        name:
+          type: string
+          description: The name of the workflow.
+        description:
+          type: string
+          description: A description of the workflow.
+        use_case:
+          type: string
+          description: A use case, which can be used with the Search Workflow API to find related workflows.
+        version:
+          $ref: '#/components/schemas/version'
+      minProperties: 1
+    FlowFrameworkDeleteResponse:
+      type: object
+      properties:
+        _index:
+          type: string
+          description: The name of the index where the document was stored.
+        _id:
+          type: string
+          description: The unique identifier of the deleted document.
+        _version:
+          type: integer
+          description: The version of the document after the deletion.
+        result:
+          type: string
+          description: The result of the deletion operation.
+          enum: [deleted, not_found]
+        _shards:
+          $ref: '#/components/schemas/shards'
+        _seq_no:
+          type: integer
+          description: The sequence number assigned to the document after the deletion.
+        _primary_term:
+          type: integer
+          description: The primary term assigned to the document after the deletion.
+    FlowFrameworkGetResponse:
+      type: object
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+        use_case:
+          type: string
+        workflows:
+          type: object
+        user:
+          $ref: '#/components/schemas/user'
+        created_time:
+          type: integer
+        last_updated_time:
+          type: integer
+    version:
+      type: object
+      description: A key-value map with two fields, template, which identifies the template version, and compatibility, which identifies a list of minimum required OpenSearch versions.
+      properties:
+        template:
+          type: string
+          description: The template version of the workflow.
+        compatibility:
+          type: array
+          items:
+            type: string
+          description: A list of minimum required OpenSearch versions.
+    shards:
+      type: object
+      properties:
+        total:
+          type: integer
+          description: The total number of shards involved in the deletion.
+        successful:
+          type: integer
+          description: The number of shards where the deletion was successful.
+        failed:
+          type: integer
+          description: The number of shards where the deletion failed.
+    user:
+      type: object
+      properties:
+        name:
+          type: string
+        backend_roles:
+          type: array
+          items:
+            type: string
+        roles:
+          type: array
+          items:
+            type: string
+        custom_attribute_names:
+          type: array
+          items:
+            type: string
+        user_requested_tenant:
+          type: string
+          nullable: true