Kuma System API

openapi: 3.1.0
info:
  title: Kuma Dataplane System API
  description: Kuma API
  version: v1alpha1
  x-ref-schema-name: DataplaneOverview
security:
- BasicAuth: []
- BearerAuth: []
- {}
tags:
- name: System
paths:
  /:
    get:
      operationId: index
      summary: The index endpoint
      description: The index endpoint, some common metadata
      tags:
      - System
      responses:
        '200':
          $ref: '#/components/responses/IndexResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
  /_resources:
    get:
      operationId: get-resource-type-description
      summary: A list of all resources that exist
      description: Returns a Global Insight object
      tags:
      - System
      responses:
        '200':
          $ref: '#/components/responses/ResourceTypeDescriptionListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
components:
  schemas:
    Index:
      type: object
      title: Index
      description: Some metadata about the service
      required:
      - hostname
      - product
      - version
      - instanceId
      - clusterId
      - gui
      properties:
        hostname:
          type: string
        product:
          type: string
          description: The product line (Kuma for OSS, different for other distributions)
        version:
          type: string
          description: The semantic version of the server running
        instanceId:
          type: string
          description: A unique id to identify the instance requested
        clusterId:
          type: string
          description: A unique id to identify the cluster being connected to
        gui:
          type: string
          description: The path to the GUI
        basedOnKuma:
          type: string
          description: In case of an alternative distribution of Kuma the Kuma version this release is based on
    ResourceTypeDescriptionList:
      type: object
      title: ResourceTypeDescriptionList
      description: A list of all resources install
      required:
      - resources
      properties:
        resources:
          type: array
          items:
            $ref: '#/components/schemas/ResourceTypeDescription'
    PolicyDescription:
      type: object
      required:
      - hasToTargetRef
      - hasFromTargetRef
      - hasRulesTargetRef
      - isTargetRef
      - isFromAsRules
      description: information about a policy
      properties:
        isTargetRef:
          description: whether this policy uses targetRef matching
          type: boolean
        hasToTargetRef:
          description: indicates that this policy can be used as an outbound policy
          type: boolean
        hasFromTargetRef:
          description: indicates that this policy can be used as an inbound policy
          type: boolean
        hasRulesTargetRef:
          description: indicates that the policy has a rules targetRef field for matching
          type: boolean
        isFromAsRules:
          description: If set to `true`, performs a backward compatibility conversion from the deprecated 'from' array to the new 'rules' array. This ensures older policies remain functional under the updated schema.
          type: boolean
    ResourceTypeDescription:
      description: Description of a resource type, this is useful for dynamically generated clients and the gui
      type: object
      required:
      - name
      - scope
      - readOnly
      - path
      - singularDisplayName
      - pluralDisplayName
      - includeInFederation
      - shortName
      properties:
        name:
          description: the name of the resource type
          type: string
        scope:
          type: string
          enum:
          - Global
          - Mesh
        readOnly:
          type: boolean
        path:
          description: the path to use for accessing this resource. If scope is `Global` then it will be `/<path>` otherwise it will be `/meshes/<path>`
          type: string
        singularDisplayName:
          type: string
        pluralDisplayName:
          type: string
        shortName:
          description: the short name of the resource type used in KRIs and kubectl
          type: string
        includeInFederation:
          description: description resources of this type should be included in federetion-with-policies export profile (especially useful for moving from non-federated to federated or migrating to a new global).
          type: boolean
        policy:
          $ref: '#/components/schemas/PolicyDescription'
    InvalidParameters:
      type: object
      title: Invalid Parameters
      required:
      - field
      - reason
      - source
      properties:
        field:
          type: string
          description: The name of the field that caused the error.
        reason:
          type: string
          description: 'A short, human-readable description of the problem.

            _Should_ be provided as "Sentence case" for direct use in a UI.

            '
        rule:
          type: string
          description: 'May be provided as a hint to the user to help understand the type of failure.

            Additional guidance may be provided in additional fields, i.e. `choices`.

            '
        choices:
          type: array
          description: 'Optional field to provide a list of valid choices for the field that caused the error.

            '
          items:
            type: string
        source:
          type: string
          description: 'The location of the field that caused the error.

            '
          enum:
          - body
          - query
          - header
          - path
    Error:
      type: object
      title: Error
      description: 'Standard error. Follows the [AIP #193 - Errors](https://kong-aip.netlify.app/aip/193/) specification.

        '
      x-examples:
        Example 1:
          status: 404
          title: Not Found
          type: https://kongapi.info/konnect/not-found
          instance: portal:trace:2287285207635123011
          detail: The requested document was not found
      required:
      - status
      - title
      - instance
      - type
      - detail
      properties:
        status:
          type: integer
          description: The HTTP status code.
          example: 404
        title:
          type: string
          description: 'A short, human-readable summary of the problem.

            It **should not** change between occurrences of a problem, except for localization.

            Should be provided as "Sentence case" for potential direct use in a UI

            '
          example: Not Found
        type:
          type: string
          description: 'A unique identifier for this error. When dereferenced it must provide human-readable documentation for the problem.

            '
          example: Not Found
        instance:
          type: string
          example: portal:trace:2287285207635123011
          description: 'Used to return the correlation ID back to the user, in the format `<app>:trace:<correlation_id>`.

            '
        detail:
          type: string
          example: The requested team was not found
          description: 'A human readable explanation specific to this occurrence of the problem.

            This field may contain request/entity data to help the user understand what went wrong.

            Enclose variable values in square brackets.

            _Should_ be provided as "Sentence case" for direct use in a UI

            '
        invalid_parameters:
          type: array
          description: 'All 400 errors **MUST** return an `invalid_parameters` key in the response.

            Used to indicate which fields have invalid values when validated.

            '
          items:
            $ref: '#/components/schemas/InvalidParameters'
  responses:
    Internal:
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    ResourceTypeDescriptionListResponse:
      description: A response containing a list of all resources installed in Kuma
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceTypeDescriptionList'
    BadRequest:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    IndexResponse:
      description: A response for the index endpoint
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Index'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer