modules/rest-api/openapi/openapi.yaml

openapi: 3.0.1
info:
  title: Ignite REST module
  contact:
    email: user@ignite.apache.org
  license:
    name: Apache 2.0
    url: https://ignite.apache.org
  version: 3.0.0-SNAPSHOT
paths:
  /management/v1/cluster/init:
    post:
      tags:
      - clusterManagement
      summary: Initializes cluster.
      description: Initializes a new cluster.
      operationId: init
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitCommand'
        required: true
      responses:
        "200":
          description: Cluster initialized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "400":
          description: Incorrect configuration.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/cluster/state:
    get:
      tags:
      - clusterManagement
      summary: Returns cluster state.
      description: Returns current cluster status.
      operationId: clusterState
      responses:
        "200":
          description: Cluster status returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterState'
        "404":
          description: "Cluster status not found. Most likely, the cluster is not\
            \ initialized."
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/cluster/topology/logical:
    get:
      tags:
      - topology
      summary: Cluster logical topology.
      description: Gets information about logical cluster topology.
      operationId: logical
      responses:
        "200":
          description: Logical topology returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ClusterNode'
        "404":
          description: "Logical topology not found. Most likely, the cluster is not\
            \ initialized."
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "500":
          description: Internal error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/cluster/topology/physical:
    get:
      tags:
      - topology
      summary: Cluster physical topology.
      description: Gets information about physical cluster topology.
      operationId: physical
      responses:
        "200":
          description: Physical topology returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ClusterNode'
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/configuration/cluster:
    get:
      tags:
      - clusterConfiguration
      summary: Returns cluster configuration in HOCON format.
      description: Gets the current configuration of the cluster.
      operationId: getClusterConfiguration
      responses:
        "200":
          description: Received cluster configuration.
          content:
            text/plain:
              schema:
                type: string
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "400":
          description: Incorrect configuration.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "404":
          description: "Configuration not found. Most likely, the cluster is not initialized."
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    patch:
      tags:
      - clusterConfiguration
      summary: Updates cluster configuration in HOCON format.
      description: Updates cluster configuration. New configuration should be provided
        in HOCON format.
      operationId: updateClusterConfiguration
      requestBody:
        description: The cluster configuration to update.
        content:
          text/plain:
            schema:
              type: string
        required: true
      responses:
        "200":
          description: Configuration updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "400":
          description: Incorrect configuration.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "404":
          description: "Configuration not found. Most likely, the cluster is not initialized."
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/configuration/cluster/{path}:
    get:
      tags:
      - clusterConfiguration
      summary: Returns configuration in HOCON format represented by path.
      description: Gets the configuration on the specific path. Configuration is in
        HOCON format
      operationId: getClusterConfigurationByPath
      parameters:
      - name: path
        in: path
        description: "Configuration tree address. For example: `element.subelement`."
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Configuration of the cluster on the specified path.
          content:
            text/plain:
              schema:
                type: string
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "400":
          description: Incorrect configuration.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "404":
          description: "Configuration not found. Most likely, the cluster is not initialized."
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/configuration/node:
    get:
      tags:
      - nodeConfiguration
      summary: Returns node configuration in HOCON format.
      description: Gets node configuration in HOCON format.
      operationId: getNodeConfiguration
      responses:
        "200":
          description: Full node configuration.
          content:
            text/plain:
              schema:
                type: string
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "400":
          description: Incorrect configuration.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    patch:
      tags:
      - nodeConfiguration
      summary: Updates node configuration in HOCON format.
      description: Updates node configuration. New configuration should be provided
        in HOCON format.
      operationId: updateNodeConfiguration
      requestBody:
        description: The node configuration to update.
        content:
          text/plain:
            schema:
              type: string
        required: true
      responses:
        "200":
          description: Configuration successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Void'
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "400":
          description: Incorrect configuration.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/configuration/node/{path}:
    get:
      tags:
      - nodeConfiguration
      summary: Returns configuration in HOCON format represented by path.
      description: "Gets a configuration of a specific node, in HOCON format."
      operationId: getNodeConfigurationByPath
      parameters:
      - name: path
        in: path
        description: "Configuration tree address. For example: `element.subelement`."
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Returned node configuration.
          content:
            text/plain:
              schema:
                type: string
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "400":
          description: Incorrect configuration.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/deployment/cluster/units:
    get:
      tags:
      - deployment
      summary: Cluster unit statuses REST method.
      description: Cluster unit statuses.
      operationId: listClusterStatuses
      parameters:
      - name: statuses
        in: query
        schema:
          type: array
          description: Deployment status filter.
          nullable: true
          items:
            $ref: '#/components/schemas/DeploymentStatus'
      responses:
        "200":
          description: All statuses returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnitStatus'
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/deployment/cluster/units/{unitId}:
    get:
      tags:
      - deployment
      summary: Cluster unit statuses REST method.
      description: Cluster unit statuses.
      operationId: listClusterStatusesByUnit
      parameters:
      - name: unitId
        in: path
        required: true
        schema:
          type: string
          description: The ID of the deployment unit.
      - name: version
        in: query
        schema:
          type: string
          description: Unit version filter.
          nullable: true
      - name: statuses
        in: query
        schema:
          type: array
          description: Deployment status filter.
          nullable: true
          items:
            $ref: '#/components/schemas/DeploymentStatus'
      responses:
        "200":
          description: All statuses returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnitStatus'
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/deployment/node/units:
    get:
      tags:
      - deployment
      summary: Node unit statuses REST method.
      description: Node unit statuses.
      operationId: listNodeStatuses
      parameters:
      - name: statuses
        in: query
        schema:
          type: array
          description: Deployment status filter.
          nullable: true
          items:
            $ref: '#/components/schemas/DeploymentStatus'
      responses:
        "200":
          description: All statuses returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnitStatus'
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/deployment/node/units/{unitId}:
    get:
      tags:
      - deployment
      summary: Node unit statuses REST method.
      description: Node unit statuses.
      operationId: listNodeStatusesByUnit
      parameters:
      - name: unitId
        in: path
        required: true
        schema:
          type: string
          description: The ID of the deployment unit.
      - name: version
        in: query
        schema:
          type: string
          description: Unit version filter.
          nullable: true
      - name: statuses
        in: query
        schema:
          type: array
          description: Deployment status filter.
          nullable: true
          items:
            $ref: '#/components/schemas/DeploymentStatus'
      responses:
        "200":
          description: All statuses returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnitStatus'
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/deployment/units/{unitId}/{unitVersion}:
    post:
      tags:
      - deployment
      summary: Deploy unit REST method.
      description: Deploys provided unit to the cluster.
      operationId: deployUnit
      parameters:
      - name: unitId
        in: path
        required: true
        schema:
          type: string
          description: The ID of the deployment unit.
      - name: unitVersion
        in: path
        required: true
        schema:
          type: string
          description: The version of the deployment unit.
      - name: deployMode
        in: query
        schema:
          nullable: true
          allOf:
          - $ref: '#/components/schemas/deployMode'
          - type: object
            description: ALL or MAJORITY.
      - name: initialNodes
        in: query
        schema:
          type: array
          description: List of node identifiers to deploy to.
          nullable: true
          items:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - unitContent
              type: object
              properties:
                unitContent:
                  type: array
                  description: The code to deploy.
                  items:
                    type: string
                    format: binary
        required: true
      responses:
        "200":
          description: Unit deployed successfully.
          content:
            application/json:
              schema:
                type: boolean
        "409":
          description: Unit with same identifier and version is already deployed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    delete:
      tags:
      - deployment
      summary: Undeploy unit REST method.
      description: Undeploys the unit with provided unitId and unitVersion.
      operationId: undeployUnit
      parameters:
      - name: unitId
        in: path
        required: true
        schema:
          type: string
          description: The ID of the deployment unit.
      - name: unitVersion
        in: path
        required: true
        schema:
          type: string
          description: The version of the deployment unit.
      responses:
        "200":
          description: Unit undeployed successfully.
          content:
            application/json:
              schema:
                type: boolean
        "404":
          description: Unit with provided identifier and version does not exist.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/metric/node/disable:
    post:
      tags:
      - nodeMetric
      summary: Disable metric source.
      description: Disables the specified metric source.
      operationId: disableNodeMetric
      requestBody:
        content:
          text/plain:
            schema:
              type: string
        required: true
      responses:
        "200":
          description: Metric source disabled.
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "404":
          description: Metric source not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/metric/node/enable:
    post:
      tags:
      - nodeMetric
      summary: Enable metric source.
      description: Enables the specified metric source.
      operationId: enableNodeMetric
      requestBody:
        content:
          text/plain:
            schema:
              type: string
        required: true
      responses:
        "200":
          description: Metric source enabled.
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        "404":
          description: Metric source not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/metric/node/set:
    get:
      tags:
      - nodeMetric
      summary: List metric sets.
      description: Gets a list of all enabled metric sets.
      operationId: listNodeMetricSets
      responses:
        "200":
          description: Returned a list of metric sets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MetricSet'
        "500":
          description: Internal error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/metric/node/source:
    get:
      tags:
      - nodeMetric
      summary: List metric sources.
      description: Gets a list of all available metric sources.
      operationId: listNodeMetricSources
      responses:
        "200":
          description: Returned a list of metric sources.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MetricSource'
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/node/state:
    get:
      tags:
      - nodeManagement
      description: Gets current network status.
      operationId: nodeState
      responses:
        "200":
          description: Current node status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeState'
        "500":
          description: Internal error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /management/v1/node/version:
    get:
      tags:
      - nodeManagement
      description: Gets the version of Apache Ignite the node uses.
      operationId: nodeVersion
      responses:
        "200":
          description: Node version.
          content:
            text/plain:
              schema:
                type: string
        "500":
          description: Internal error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    ClusterNode:
      type: object
      properties:
        id:
          type: string
          description: Node ID.
        name:
          type: string
          description: Unique cluster name.
        address:
          description: Network address of this node.
          allOf:
          - $ref: '#/components/schemas/NetworkAddress'
          - type: object
            description: Cluster network address information.
        metadata:
          allOf:
          - $ref: '#/components/schemas/NodeMetadata'
          - type: object
            description: Node metadata information.
      description: Information about the cluster node.
    ClusterState:
      type: object
      properties:
        cmgNodes:
          type: array
          description: List of cluster management group nodes. These nodes are responsible
            for maintaining RAFT cluster topology.
          items:
            type: string
        msNodes:
          type: array
          description: List of metastorage nodes. These nodes are responsible for
            storing RAFT cluster metadata.
          items:
            type: string
        igniteVersion:
          type: string
          description: Version of Apache Ignite that the cluster was created on.
        clusterTag:
          allOf:
          - $ref: '#/components/schemas/ClusterTag'
          - type: object
            description: Unique tag that identifies the cluster.
      description: Information about current cluster state.
    ClusterTag:
      type: object
      properties:
        clusterId:
          type: string
          description: Unique cluster UUID. Generated automatically.
          format: uuid
        clusterName:
          type: string
          description: Unique cluster name.
      description: Unique tag that identifies the cluster.
    DeploymentStatus:
      type: string
      description: Status of deployment process.
      enum:
      - UPLOADING
      - DEPLOYED
      - OBSOLETE
      - REMOVING
    InitCommand:
      type: object
      properties:
        metaStorageNodes:
          type: array
          description: A list of RAFT metastorage nodes.
          items:
            type: string
        cmgNodes:
          type: array
          description: A list of RAFT cluster management nodes.
          items:
            type: string
        clusterName:
          type: string
          description: The name of the cluster.
        clusterConfiguration:
          type: string
          description: Cluster configuration in HOCON format.
      description: Cluster initialization configuration.
    InvalidParam:
      type: object
      properties:
        name:
          type: string
          description: Parameter name.
        reason:
          type: string
          description: The issue with the parameter.
      description: Information about invalid request parameter.
    Metric:
      type: object
      properties:
        name:
          type: string
          description: Metric name.
        desc:
          type: string
          description: Metric description.
          nullable: true
      description: Metric representation.
    MetricSet:
      required:
      - metrics
      - name
      type: object
      properties:
        name:
          type: string
          description: Metric set name.
        metrics:
          type: array
          description: Metrics.
          items:
            $ref: '#/components/schemas/Metric'
      description: Metrics set representation.
    MetricSource:
      required:
      - enabled
      - name
      type: object
      properties:
        name:
          type: string
          description: Metric source name.
        enabled:
          type: boolean
          description: "If True, the metric is tracked. Otherwise, the metric is not\
            \ tracked."
      description: A list of metric sources provided by modules.
    NetworkAddress:
      type: object
      properties:
        host:
          type: string
          description: Name of the host node runs on.
        port:
          type: integer
          description: Port the node runs on.
          format: int32
      description: Node network address information.
    NodeMetadata:
      type: object
      properties:
        restHost:
          type: string
          description: The host exposed to REST API.
        httpPort:
          type: integer
          description: The HTTP port exposed to REST API.
          format: int32
        httpsPort:
          type: integer
          description: The HTTPS port exposed to REST API.
          format: int32
      description: Node metadata information.
    NodeState:
      required:
      - name
      - state
      type: object
      properties:
        name:
          type: string
          description: Unique node name.
        state:
          allOf:
          - $ref: '#/components/schemas/State'
          - type: object
            description: Node status.
      description: Node state.
    Problem:
      type: object
      properties:
        title:
          type: string
          description: Short summary of the issue.
        status:
          type: integer
          description: Returned HTTP status code.
          format: int32
        code:
          type: string
          description: Ignite 3 error code.
        type:
          type: string
          description: URI to documentation regarding the issue.
        detail:
          type: string
          description: Extended explanation of the issue.
        node:
          type: string
          description: Name of the node the issue happened on.
        traceId:
          type: string
          description: Unique issue identifier. This identifier can be used to find
            logs related to the issue.
          format: uuid
        invalidParams:
          type: array
          description: A list of parameters that did not pass validation and the reason
            for it.
          items:
            $ref: '#/components/schemas/InvalidParam'
      description: Extended description of the problem with the request.
    State:
      type: string
      description: Possible node statuses.
      enum:
      - STARTING
      - STARTED
      - STOPPING
    UnitStatus:
      required:
      - id
      - versionToStatus
      type: object
      properties:
        id:
          type: string
          description: Unit identifier.
        versionToStatus:
          type: array
          description: Map from unit version to unit deployment status.
          items:
            $ref: '#/components/schemas/UnitVersionStatus'
      description: Unit status.
    UnitVersionStatus:
      required:
      - status
      - version
      type: object
      properties:
        version:
          type: string
          description: Unit version.
        status:
          allOf:
          - $ref: '#/components/schemas/DeploymentStatus'
          - type: object
            description: Unit status.
      description: Unit version and status.
    Void:
      type: object
    deployMode:
      type: string
      description: Initial set of nodes to deploy.
      enum:
      - MAJORITY
      - ALL