openapi: 3.0.3
info:
  title: Event Streams for Apache Kafka API
  description: |
    A managed Apache Kafka cluster is designed to be highly fault-tolerant and scalable,
    allowing large volumes of data to be ingested, stored, and processed in real-time. By
    distributing data across multiple brokers, Kafka achieves high throughput and low
    latency, making it suitable for applications requiring real-time data processing and
    analytics.
  version: 3.1.0
  contact:
    name: IONOS Cloud Support
    url: https://docs.ionos.com/support/general-information/contact-information
    email: support@cloud.ionos.com
externalDocs:
  url: https://api.ionos.com/docs/cloud/
  description: IONOS Cloud - API documentation
servers:
  - url: https://kafka.de-txl.ionos.com
    description: Germany, Berlin
  - url: https://kafka.de-fra.ionos.com
    description: Germany, Frankfurt (de/fra, de/fra/2)
  - url: https://kafka.fr-par.ionos.com
    description: France, Paris
  - url: https://kafka.es-vit.ionos.com
    description: Spain, Logroño
  - url: https://kafka.gb-lhr.ionos.com
    description: United Kingdom, London
  - url: https://kafka.gb-bhx.ionos.com
    description: United Kingdom, Worcester
  - url: https://kafka.us-las.ionos.com
    description: United States, Las Vegas
  - url: https://kafka.us-mci.ionos.com
    description: United States, Lenexa
  - url: https://kafka.us-ewr.ionos.com
    description: United States, Newark
tags:
- name: Clusters
  description: |
    A Kafka cluster that stores data and serve client requests.
    Kafka clusters typically have multiple brokers to handle more data
    and provide high availability. Each broker is identified by a unique
    ID and manages partitions of different topics.
    This tag groups all operations for clusters.
- name: Topics
  description: |
    A topic is a category or feed name to which records are
    published. Topics are the way Kafka organizes messages. They act as logical
    channels for data streams. Topics are split into partitions, making them
    scalable and allowing parallelism.
    This tag groups all operations for topics.
- name: Users
  description: |
    The user of the cluster. Access is managed by certificates. The certificates are
    retrieved by the access endpoint.
    This tag groups all operations for users.
paths:
  /clusters:
    get:
      operationId: clustersGet
      summary: Retrieve all Clusters
      security:
      - tokenAuth: []
      description: |
        This endpoint enables retrieving all Clusters using
        pagination and optional filters.
      parameters:
        - $ref: "#/components/parameters/clusterNameFilter"
        - $ref: "#/components/parameters/clusterStateFilter"
      tags:
        - Clusters
      responses:
        "200":
          description: |
            Returned all requested Clusters successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClusterReadList"
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
    post:
      operationId: clustersPost
      summary: Create Cluster
      security:
      - tokenAuth: []
      tags:
        - Clusters
      description: |
        Creates a new Cluster.
        
        The full Cluster needs to be provided to create the object.
        Optional data will be filled with defaults or left empty.
      requestBody:
        description: Cluster to create.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClusterCreate"
      responses:
        "201":
          description: Cluster successfully created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClusterRead"
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "415":
          $ref: '#/components/responses/UnsupportedMediaType'
        "422":
          $ref: '#/components/responses/UnprocessableEntity'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /clusters/{clusterId}:
    get:
      operationId: clustersFindById
      summary: Retrieve Cluster
      security:
      - tokenAuth: []
      tags:
        - Clusters
      description: Returns the Cluster by ID.
      parameters:
        - name: clusterId
          in: path
          schema:
            type: string
            format: uuid
          example: "e69b22a5-8fee-56b1-b6fb-4a07e4205ead"
          required: true
          description: The ID (UUID) of the Cluster.
      responses:
        "200":
          description: Getting Cluster was successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClusterRead"
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "404":
          $ref: '#/components/responses/NotFound'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
    delete:
      operationId: clustersDelete
      summary: Delete Cluster
      security:
      - tokenAuth: []
      tags:
        - Clusters
      description: Deletes the specified Cluster.
      parameters:
        - name: clusterId
          in: path
          schema:
            type: string
            format: uuid
          example: "e69b22a5-8fee-56b1-b6fb-4a07e4205ead"
          required: true
          description: The ID (UUID) of the Cluster.
      responses:
        "202":
          description: Deleting Cluster was successful.
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "404":
          $ref: '#/components/responses/NotFound'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /clusters/{clusterId}/users:
    get:
      operationId: clustersUsersGet
      summary: Retrieve all Users
      security:
      - tokenAuth: []
      description: |
        This endpoint enables retrieving all Users using
        pagination and optional filters.
      parameters:
        - name: clusterId
          in: path
          schema:
            type: string
            format: uuid
          example: "e69b22a5-8fee-56b1-b6fb-4a07e4205ead"
          required: true
          description: The ID (UUID) of the Cluster.
      tags:
        - Users
      responses:
        "200":
          description: |
            Returned all requested Users successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserReadList"
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /clusters/{clusterId}/users/{userId}/access:
    get:
      operationId: clustersUsersAccessGet
      summary: Retrieve Apache Kafka User with Credentials
      security:
        - tokenAuth: []
      tags:
        - Users
      description: Returns the user by ID containing its access certificates in the metadata.
      parameters:
        - name: clusterId
          in: path
          schema:
            type: string
            format: uuid
          example: e69b22a5-8fee-56b1-b6fb-4a07e4205ead
          required: true
          description: The ID (UUID) of the cluster.
        - name: userId
          in: path
          schema:
            type: string
            format: uuid
          example: d11db12c-2625-5664-afd4-a3599731b5af
          required: true
          description: The ID (UUID) of the user.
      responses:
        "200":
          description: Get user access information was successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserReadAccess"
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "404":
          $ref: '#/components/responses/NotFound'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /clusters/{clusterId}/topics:
    get:
      operationId: clustersTopicsGet
      summary: Retrieve all Topics
      security:
        - tokenAuth: []
      description: |
        This endpoint enables retrieving all topics using
        pagination and optional filters.
      parameters:
        - name: clusterId
          in: path
          schema:
            type: string
            format: uuid
          example: e69b22a5-8fee-56b1-b6fb-4a07e4205ead
          required: true
          description: The ID (UUID) of the cluster.
      tags:
        - Topics
      responses:
        "200":
          description: |
            Returned all requested topics successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TopicReadList"
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "409":
          description: |
            ### Conflict
            The request could not be completed due to a conflict with the current state of the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
    post:
      operationId: clustersTopicsPost
      summary: Create Topic
      security:
        - tokenAuth: []
      tags:
        - Topics
      description: |
        Creates a new topic.
        The full topic needs to be provided to create the object.
        Optional data will be filled with defaults or left empty.
      parameters:
        - name: clusterId
          in: path
          schema:
            type: string
            format: uuid
          example: e69b22a5-8fee-56b1-b6fb-4a07e4205ead
          required: true
          description: The ID (UUID) of the cluster.
      requestBody:
        description: Topic to create.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TopicCreate"
      responses:
        "201":
          description: Topic successfully created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TopicRead"
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "409":
          description: |
            ### Conflict
            The request could not be completed due to a conflict with the current state of the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "415":
          $ref: '#/components/responses/UnsupportedMediaType'
        "422":
          $ref: '#/components/responses/UnprocessableEntity'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /clusters/{clusterId}/topics/{topicId}:
    get:
      operationId: clustersTopicsFindById
      summary: Retrieve Topic
      security:
        - tokenAuth: []
      tags:
        - Topics
      description: Returns the topic by ID.
      parameters:
        - name: clusterId
          in: path
          schema:
            type: string
            format: uuid
          example: e69b22a5-8fee-56b1-b6fb-4a07e4205ead
          required: true
          description: The ID (UUID) of the cluster.
        - name: topicId
          in: path
          schema:
            type: string
            format: uuid
          example: ae085c4c-3626-5f1d-b4bc-cc53ae8267ce
          required: true
          description: The ID (UUID) of the topic.
      responses:
        "200":
          description: Getting topic was successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TopicRead"
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "404":
          $ref: '#/components/responses/NotFound'
        "409":
          description: |
            ### Conflict
            The request could not be completed due to a conflict with the current state of the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
    delete:
      operationId: clustersTopicsDelete
      summary: Delete Topic
      security:
        - tokenAuth: []
      tags:
        - Topics
      description: Deletes the specified topic.
      parameters:
        - name: clusterId
          in: path
          schema:
            type: string
            format: uuid
          example: e69b22a5-8fee-56b1-b6fb-4a07e4205ead
          required: true
          description: The ID (UUID) of the cluster.
        - name: topicId
          in: path
          schema:
            type: string
            format: uuid
          example: ae085c4c-3626-5f1d-b4bc-cc53ae8267ce
          required: true
          description: The ID (UUID) of the topic.
      responses:
        "202":
          description: Deleting topic was successful.
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/NotAllowed'
        "404":
          $ref: '#/components/responses/NotFound'
        "409":
          description: |
            ### Conflict
            The request could not be completed due to a conflict with the current state of the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "429":
          $ref: '#/components/responses/TooManyRequests'
        "500":
          $ref: '#/components/responses/InternalError'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/UnexpectedError'
components:
  parameters:
    clusterNameFilter:
      name: filter.name
      in: query
      required: false
      description: Only return Kafka clusters that contain the given name. Case insensitive.
      schema:
        $ref: "#/components/schemas/KafkaClusterName"
    clusterStateFilter:
      name: filter.state
      in: query
      required: false
      description: Only return Kafka clusters with a given state.
      schema:
        $ref: "#/components/schemas/State"
  schemas:
    ClusterReadList:
      allOf:
      - type: object
        required:
        - id
        - type
        - href
        properties:
          id:
            description: ID of the list of Cluster resources.
            type: string
            format: uuid
            example: ed17eb1f-ac43-5670-9e63-8be33c475449
          type:
            description: The type of the resource.
            type: string
            enum:
            - collection
          href:
            description: The URL of the list of Cluster resources.
            type: string
            example: /clusters
          items:
            description: The list of Cluster resources.
            type: array
            items:
              $ref: '#/components/schemas/ClusterRead'
    ClusterRead:
      type: object
      required:
      - id
      - type
      - href
      - metadata
      - properties
      properties:
        id:
          type: string
          description: The ID (UUID) of the Cluster.
          format: uuid
          example: "e69b22a5-8fee-56b1-b6fb-4a07e4205ead"
        type:
          description: The type of the resource.
          type: string
          enum:
          - cluster
        href:
          description: The URL of the Cluster.
          type: string
          example: /clusters/e69b22a5-8fee-56b1-b6fb-4a07e4205ead
        metadata:
          $ref: '#/components/schemas/ClusterMetadata'
        properties:
          $ref: '#/components/schemas/Cluster'
    ClusterCreate:
      type: object
      required:
      - properties
      properties:
        properties:
          $ref: '#/components/schemas/Cluster'
    TopicReadList:
      allOf:
      - type: object
        required:
        - id
        - type
        - href
        properties:
          id:
            description: ID of the list of Topic resources.
            type: string
            format: uuid
            example: 7c1fe82d-a1ea-55fc-a744-12fad4180eef
          type:
            description: The type of the resource.
            type: string
            enum:
            - collection
          href:
            description: The URL of the list of Topic resources.
            type: string
            example: /clusters/{clusterId}/topics
          items:
            description: The list of Topic resources.
            type: array
            items:
              $ref: '#/components/schemas/TopicRead'
    TopicRead:
      type: object
      required:
      - id
      - type
      - href
      - metadata
      - properties
      properties:
        id:
          type: string
          description: The ID (UUID) of the Topic.
          format: uuid
          example: "ae085c4c-3626-5f1d-b4bc-cc53ae8267ce"
        type:
          description: The type of the resource.
          type: string
          enum:
          - topic
        href:
          description: The URL of the Topic.
          type: string
          example: /clusters/{clusterId}/topics/ae085c4c-3626-5f1d-b4bc-cc53ae8267ce
        metadata:
          $ref: '#/components/schemas/ResourceMetadata'
        properties:
          $ref: '#/components/schemas/Topic'
    TopicCreate:
      type: object
      required:
      - properties
      properties:
        properties:
          $ref: '#/components/schemas/Topic'
    UserReadList:
      allOf:
      - type: object
        required:
        - id
        - type
        - href
        properties:
          id:
            description: ID of the list of User resources.
            type: string
            format: uuid
            example: 434e0c83-031d-5f5a-be82-63ee54dda025
          type:
            description: The type of the resource.
            type: string
            enum:
            - collection
          href:
            description: The URL of the list of User resources.
            type: string
            example: /clusters/{clusterId}/users
          items:
            description: The list of User resources.
            type: array
            items:
              $ref: '#/components/schemas/UserRead'
    UserRead:
      type: object
      required:
      - id
      - type
      - href
      - metadata
      - properties
      properties:
        id:
          type: string
          description: The ID (UUID) of the User.
          format: uuid
          example: "d11db12c-2625-5664-afd4-a3599731b5af"
        type:
          description: The type of the resource.
          type: string
          enum:
          - user
        href:
          description: The URL of the User.
          type: string
          example: /clusters/{clusterId}/users/d11db12c-2625-5664-afd4-a3599731b5af
        metadata:
          $ref: '#/components/schemas/ResourceMetadata'
        properties:
          $ref: '#/components/schemas/User'
    Cluster:
      type: object
      description: |
        A Kafka cluster that stores data and serve client requests.
        Kafka clusters typically have multiple brokers to handle more data
        and provide high availability. Each broker is identified by a unique
        ID and manages partitions of different topics.
      required:
        - name
        - version
        - size
        - connections
      additionalProperties: false
      properties:
        name:
          $ref: "#/components/schemas/KafkaClusterName"
        version:
          $ref: "#/components/schemas/KafkaVersion"
        size:
          $ref: "#/components/schemas/KafkaClusterSize"
        connections:
          type: array
          minItems: 1
          maxItems: 1
          items:
            $ref: "#/components/schemas/KafkaClusterConnection"
    KafkaClusterName:
      type: string
      description: |
        The name of your Kafka cluster.
        Must be 63 characters or less and must begin and end with an alphanumeric character (`[a-z0-9A-Z]`)
        with dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics between.
      pattern: "^[A-Za-z0-9][-A-Za-z0-9_.]*[A-Za-z0-9]$"
      minLength: 2
      maxLength: 63
      example: my-kafka-cluster
    KafkaClusterSize:
      type: string
      description: |
        The size of your Kafka cluster.
        The size of the Kafka cluster is given in T-shirt sizes. Valid values are: `XS`, `S`, `M`, `L`, and `XL`.
      pattern: "^(XS|S|M|L|XL)$"
      example: "XS"
    KafkaVersion:
      type: string
      pattern: "^(3.9.0|3.9.1)$"
      maxLength: 32
      description: |
        The version of Kafka. Allowed values are `3.9.0` and `3.9.1`.
      example: 3.9.1
    ResourceMetadata:
      allOf:
        - $ref: "#/components/schemas/Metadata"
        - $ref: "#/components/schemas/ResourceState"
    ClusterMetadata:
      allOf:
        - $ref: "#/components/schemas/Metadata"
        - $ref: "#/components/schemas/ResourceState"
        - type: object
          properties:
            brokerAddresses:
              type: array
              description: IP addresses and ports of cluster brokers.
              items:
                type: string
                description: IP address and port of cluster broker.
                example: "192.0.2.101:9093"
              example:
                - "192.0.2.101:9093"
                - "192.0.2.102:9093"
                - "192.0.2.103:9093"
    KafkaClusterConnection:
      description: |
        Connection information of the Kafka cluster.
      type: object
      required:
        - datacenterId
        - lanId
        - brokerAddresses
      properties:
        datacenterId:
          description: The datacenter to connect your instance to.
          type: string
          example: '5a029f4a-72e5-11ec-90d6-0242ac120003'
        lanId:
          description: The numeric LAN ID to connect your instance to.
          type: string
          example: '2'
        brokerAddresses:
          type: array
          description: |
            IP addresses and subnet of cluster brokers.
            Note the following unavailable IP range:
            10.224.0.0/11
          items:
            $ref: "#/components/schemas/KafkaClusterBrokerIp"
          example:
            - 192.0.2.101/24
            - 192.0.2.102/24
            - 192.0.2.103/24
    KafkaClusterBrokerIp:
      type: string
      description: |
        The IP and subnet for a cluster broker.
        Note the following unavailable IP range:
        10.224.0.0/11
      example: 192.0.2.101/24
    User:
      type: object
      description: |
        The user of the cluster. Access is managed by certificates. The certificates are
        retrieved by the access endpoint.
      required:
        - name
      properties:
        name:
          type: string
          description: |
            The name of the Kafka cluster user.
            Must be 63 characters or less and must begin and end with an alphanumeric character (`[a-z0-9A-Z]`)
            with dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics between.
          pattern: "^[A-Za-z0-9][-A-Za-z0-9_.]*[A-Za-z0-9]$"
          minLength: 2
          maxLength: 63
          example: my-kafka-cluster-user
    UserReadAccess:
      type: object
      required:
        - id
        - type
        - href
        - metadata
        - properties
      properties:
        id:
          type: string
          description: The ID (UUID) of the user.
          format: uuid
          example: d11db12c-2625-5664-afd4-a3599731b5af
        type:
          description: The type of the resource.
          type: string
          enum:
            - user
        href:
          description: The URL of the user.
          type: string
          example: /clusters/{clusterId}/users/d11db12c-2625-5664-afd4-a3599731b5af
        metadata:
          $ref: '#/components/schemas/UserAccessMetadata'
        properties:
          $ref: '#/components/schemas/User'
    UserAccessMetadata:
      allOf:
        - $ref: "#/components/schemas/ResourceMetadata"
        - type: object
          additionalProperties: false
          properties:
            certificateAuthority:
              type: string
              description: PEM for the certificate authority.
              example: -----BEGIN CERTIFICATE ...
            privateKey:
              type: string
              description: PEM for the private key.
              example: -----BEGIN PRIVATE KEY ...
            certificate:
              type: string
              description: PEM for the certificate.
              example: -----BEGIN CERTIFICATE ...
    Topic:
      type: object
      description: |
        A topic is a category or feed name to which records are
        published. Topics are the way Kafka organizes messages. They act as logical
        channels for data streams. Topics are split into partitions, making them
        scalable and allowing parallelism.
      required:
        - name
      properties:
        name:
          type: string
          description: |
            The name of the Kafka cluster topic.
            Must be 63 characters or less and must begin and end with an alphanumeric character (`[a-z0-9A-Z]`)
            with dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics between.
          pattern: "^[A-Za-z0-9][-A-Za-z0-9_.]*[A-Za-z0-9]$"
          minLength: 2
          maxLength: 63
          example: my-kafka-cluster-topic
        replicationFactor:
          type: integer
          description: |
            The number of replicas of the topic. The replication factor
            determines how many copies of the topic are stored on different
            brokers. The replication factor must be less than or equal to the
            number of brokers in the Kafka cluster.
          minimum: 1
          example: 3
          default: 3
        numberOfPartitions:
          type: integer
          description: |
            The number of partitions of the topic. Partitions allow for parallel processing of messages.
          minimum: 1
          example: 3
          default: 3
        logRetention:
          type: object
          properties:
            retentionTime:
              type: integer
              description: |
                This configuration controls the maximum time we will retain a log before we will discard old log
                 segments to free up space.
                 This represents an SLA on how soon consumers must read their data. If set to -1,
                 no time limit is applied.
              example: 604800000
              default: 604800000
            segmentBytes:
              type: integer
              description: |
                This configuration controls the segment file size for the log. Retention and cleaning is always done
                a file at a time so a larger segment size means fewer files but less granular control over retention.
              example: 1073741824
              default: 1073741824
    ResourceState:
      type: object
      description: The current status of the resource.
      required:
        - state
      properties:
        state:
          $ref: "#/components/schemas/State"
        message:
          type: string
          description: |
            A human readable message describing the current state.
            In case of an error, the message will contain a detailed error message.
          example: In progress.
    State:
      type: string
      description: |
        State of the resource. Resource states:
        `AVAILABLE`: There are no pending modification requests for this item.
        `BUSY`: There is at least one modification request pending and all following requests will be queued.
        `DEPLOYING`: The resource is being created.
        `FAILED`: The creation of the resource failed.
        `UPDATING`: The resource is being updated.
        `FAILED_UPDATING`: An update to the resource was not successful.
        `DESTROYING`: A delete command was issued, and the resource is being deleted.
      x-extensible-enum:
        - AVAILABLE
        - BUSY
        - DEPLOYING
        - FAILED
        - UPDATING
        - FAILED_UPDATING
        - DESTROYING
      example: "AVAILABLE"
    Error:
      description: |
        The Error object is used to represent an error response from the API.
      type: object
      properties:
        httpStatus:
          type: integer
          description: The HTTP status code of the operation.
          example: 400
        messages:
          type: array
          description: |
            A list of error messages.
          items:
            type: object
            properties:
              errorCode:
                type: string
                description: |
                  Application internal error code
                example: "err-1234"
              message:
                type: string
                description: |
                  A human readable explanation specific to this occurrence of the
                  problem.
                example: "Error message example"
    Metadata:
      type: object
      description: Metadata of the resource.
      properties:
        createdDate:
          type: string
          format: date-time
          description: The ISO 8601 creation timestamp.
          example: "2020-12-10T13:37:50+01:00"
          readOnly: true
        createdBy:
          type: string
          description: Unique name of the identity that created the resource.
          example: "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3"
          readOnly: true
        createdByUserId:
          type: string
          description: Unique id of the identity that created the resource.
          example: 87f9a82e-b28d-49ed-9d04-fba2c0459cd3
          readOnly: true
        lastModifiedDate:
          type: string
          format: date-time
          description: The ISO 8601 modified timestamp.
          example: "2020-12-11T13:37:50+01:00"
          readOnly: true
        lastModifiedBy:
          type: string
          description: Unique name of the identity that last modified the resource.
          example: "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3"
          readOnly: true
        lastModifiedByUserId:
          type: string
          description: Unique id of the identity that last modified the resource.
          example: 87f9a82e-b28d-49ed-9d04-fba2c0459cd3
          readOnly: true
        resourceURN:
          type: string
          description: Unique name of the resource.
          example: "ionos:<product>:<location>:<contract>:<resource-path>"
          readOnly: true
    Pagination:
      required:
      - offset
      - limit
      - _links
      description: |
        Pagination information. The offset and limit parameters are used to
        navigate the list of elements. The _links object contains URLs to
        navigate the different pages.
      type: object
      properties:
        offset:
          $ref: '#/components/schemas/Offset'
        limit:
          $ref: '#/components/schemas/Limit'
        _links:
          $ref: '#/components/schemas/Links'
    Offset:
      description: |
        The offset specified in the request (if none was specified, the default
        offset is 0).
      type: integer
      example: 0
      minimum: 0
      readOnly: true
    Limit:
      description: |
        The limit specified in the request (if none was specified, use the
        endpoint's default pagination limit).
      type: integer
      example: 42
      minimum: 0
      readOnly: true
    Links:
      description: |
        URLs to navigate the different pages. As of now we always only return a
        single page.
      type: object
      properties:
        prev:
          description: |
            URL (with offset and limit parameters) of the previous page; only
            present if offset is greater than 0.
          type: string
          format: uri
          example: http://PREVIOUS-PAGE-URI
          readOnly: true
        self:
          description: |
            URL (with offset and limit parameters) of the current page.
          type: string
          format: uri
          example: http://THIS-PAGE-URI
          readOnly: true
        next:
          description: |
            URL (with offset and limit parameters) of the next page; only
            present if offset + limit is less than the total number of elements.
          type: string
          format: uri
          example: http://NEXT-PAGE-URI
          readOnly: true
  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        The token can be generated using the 
        [Authentication API](https://api.ionos.com/docs/authentication/v1/#tag/tokens/operation/tokensGenerate).
  responses:
    BadRequest:
      description: |
        ### Bad Request
        The request send to the API was malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: |
        ### Unauthorized
        The request is missing authorization information or the authorization information provided are expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotAllowed:
      description: |
        ### Not Allowed
        The user issuing the request does not have the needed permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: |
        ### Conflict
        The UUID is already taken by another party, follow the guides to generate UUIDs uniquely.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ConflictDependencies:
      description: |
        ### ConflictDependencies
        The resource has dependencies and cannot be deleted. Follow the guidelines to delete the dependencies first.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: |
        ### Not Found
        The resource that was requested could not be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnexpectedError:
      description: |
        ### Unexpected Internal Server Error
        An unexpected internal error occurred. We apologize for the inconvenience!
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: |
        ### Unprocessable Entity
        The request was well-formed but was unable to be followed due to semantic errors.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: |
        ### Too Many Requests
        The user has sent too many requests in a given amount of time.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnsupportedMediaType:
      description: |
        ### Unsupported Media Type
        The request has an unsupported media type.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: |
        ### Internal Server Error
        An internal error occurred. We apologize for the inconvenience!
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: |
        ### Service Unavailable
        The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
