openapi: 3.0.3

info:
  title: IONOS DBaaS PostgreSQL REST API
  description: |
    An enterprise-grade Database is provided as a Service (DBaaS) solution that
    can be managed through a browser-based "Data Center Designer" (DCD) tool or
    via an easy to use API.

    The API allows you to create additional PostgreSQL database clusters or modify existing
    ones. It is designed to allow users to leverage the same power and
    flexibility found within the DCD visual tool. Both tools are consistent with
    their concepts and lend well to making the experience smooth and intuitive.
  version: 1.0.0

servers:
- url: https://api.ionos.com/databases/postgresql
  description: Production

security:
- basicAuth: []
- tokenAuth: []

tags:
- name: Clusters
  description: Everything about PostgreSQL clusters.
- name: Backups
  description: Everything about PostgreSQL backups.
- name: Restores
  description: Everything about PostgreSQL restores.
- name: Logs
  description: Everything about PostgreSQL logs.
- name: Users
  description: Everything about PostgreSQL users.
- name: Databases
  description: Everything about PostgreSQL databases.
- name: Metadata
  description: All metadata about the API, like versions.

paths:
  /clusters:
    get:
      operationId: clustersGet
      summary: List clusters
      description: Retrieves a list of PostgreSQL clusters.
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/PaginationOffset'
      - $ref: '#/components/parameters/ClusterNameQuery'
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterList'
        default:
          $ref: '#/components/responses/ApiError'
    post:
      operationId: clustersPost
      summary: Create a cluster
      description: |
        Creates a new PostgreSQL cluster.
        If the `fromBackup` field is populated, the new cluster will be created
        based on the given backup.
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Clusters
      requestBody:
        description: The cluster to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateClusterRequest'
        required: true
      responses:
        "200":
          description: |
            The created cluster is returned with `metadata.state` set to "BUSY".
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterResponse'
        default:
          $ref: '#/components/responses/ApiError'

  /clusters/{clusterId}:
    get:
      operationId: clustersFindById
      summary: Fetch a cluster
      description: |
        You can retrieve a PostgreSQL cluster by using its ID. This value can be
        found in the response body when a PostgreSQL cluster is created or when
        you GET a list of PostgreSQL clusters.
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/ClusterIdPath'
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterResponse'
        default:
          $ref: '#/components/responses/ApiError'
    patch:
      operationId: clustersPatch
      summary: Patch a cluster
      description: Patch attributes of a PostgreSQL cluster.
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/ClusterIdPath'
      requestBody:
        description: Part of the cluster which should be modified.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchClusterRequest'
        required: true
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterResponse'
        default:
          $ref: '#/components/responses/ApiError'
    delete:
      operationId: clustersDelete
      summary: Delete a cluster
      description: Delete a PostgreSQL cluster.
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/ClusterIdPath'
      responses:
        "200":
          description: |
            The deleted cluster with `metadata.state` set to "DESTROYING".
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterResponse'
        default:
          $ref: '#/components/responses/ApiError'

  /clusters/backups:
    get:
      operationId: clustersBackupsGet
      summary: List cluster backups
      description: Retrieves a list of all PostgreSQL cluster backups.
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Backups
      parameters:
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/PaginationOffset'
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterBackupList'
        default:
          $ref: '#/components/responses/ApiError'

  /clusters/backups/{backupId}:
    get:
      operationId: clustersBackupsFindById
      summary: Fetch a cluster backup
      description: |
        Retrieve a PostgreSQL cluster backup by using its ID. This value can be
        found when you GET a list of PostgreSQL cluster backups.
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Backups
      parameters:
      - $ref: '#/components/parameters/BackupIdPath'
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupResponse'
        default:
          $ref: '#/components/responses/ApiError'

  /clusters/{clusterId}/backups:
    get:
      operationId: clusterBackupsGet
      summary: List backups of cluster
      description: Retrieves a list of all backups of the given PostgreSQL cluster.
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Backups
      parameters:
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/PaginationOffset'
      - $ref: '#/components/parameters/ClusterIdPath'
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterBackupList'
        default:
          $ref: '#/components/responses/ApiError'

  /clusters/{clusterId}/restore:
    post:
      operationId: clusterRestorePost
      summary: In-place restore of a cluster
      description: Triggers an in-place restore of the given PostgreSQL.
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Restores
      parameters:
      - $ref: '#/components/parameters/ClusterIdPath'
      requestBody:
        description: The restore request to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRestoreRequest'
        required: true
      responses:
        "202":
          description: Successful operation.
        default:
          $ref: '#/components/responses/ApiError'

  /clusters/{clusterId}/logs:
    get:
      operationId: clusterLogsGet
      summary: Get logs of your cluster
      description: Retrieves PostgreSQL logs based on the given parameters.
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Logs
      parameters:
      - $ref: '#/components/parameters/ClusterIdPath'
      - name: start
        in: query
        description: The start time for the query in RFC3339 format. Must not be more than 30 days ago but before the end parameter. The default is 30 days ago.
        required: false
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        description: The end time for the query in RFC3339 format. Must not be greater than now. The default is the current timestamp.
        required: false
        schema:
          type: string
          format: date-time
      - name: direction
        in: query
        description: The direction in which to scan through the logs. The logs are returned in order of the direction.
        schema:
          type: string
          default: BACKWARD
          enum:
          - BACKWARD
          - FORWARD
      - name: limit
        in: query
        description: The maximal number of log lines to return.  If the limit is reached then log lines will be cut at the end (respecting the scan direction).
        required: false
        schema:
          type: integer
          default: 100
          minimum: 1
          maximum: 5000
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterLogs'
        default:
          $ref: '#/components/responses/ApiError'

  /clusters/postgresversions:
    get:
      operationId: postgresVersionsGet
      summary: List all PostgreSQL versions
      description: Retrieves a list of all available PostgreSQL versions.
      deprecated: true
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Clusters
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostgresVersionList'
        default:
          $ref: '#/components/responses/ApiError'

  /clusters/{clusterId}/versions:
    get:
      operationId: clustersVersionsGet
      summary: Supported PostgreSQL versions of cluster
      description: Retrieves a list of all PostgreSQL versions available for this cluster.
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/ClusterIdPath'
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostgresVersionList'
        default:
          $ref: '#/components/responses/ApiError'

  /versions:
    get:
      operationId: versionsGet
      summary: PostgreSQL versions for new clusters
      description: Retrieves a list of available PostgreSQL versions for new clusters.
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Metadata
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostgresVersionList'
        default:
          $ref: '#/components/responses/ApiError'

  /clusters/{clusterId}/postgresversions:
    get:
      operationId: clusterPostgresVersionsGet
      summary: List PostgreSQL versions
      description: |
        Retrieves a list of all PostgreSQL versions available for this cluster
        including the current version.
      deprecated: true
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/ClusterIdPath'
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostgresVersionList'
        default:
          $ref: '#/components/responses/ApiError'

  /clusters/{clusterId}/users:
    get:
      operationId: usersList
      summary: List users
      description: Retrieves a list of users
      security:
        - basicAuth: []
        - tokenAuth: []
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/ClusterIdPath'
        - $ref: '#/components/parameters/PaginationLimit'
        - $ref: '#/components/parameters/PaginationOffset'
        - $ref: '#/components/parameters/SystemUserFilter'
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        default:
          $ref: '#/components/responses/ApiError'

    post:
      operationId: usersPost
      summary: Create a user
      description: Create a new Postgres User
      security:
        - basicAuth: []
        - tokenAuth: []
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/ClusterIdPath'
      requestBody:
        $ref: '#/components/requestBodies/UserRequest'
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResource'
        default:
          $ref: '#/components/responses/ApiError'

  /clusters/{clusterId}/users/{username}:
    get:
      operationId: usersGet
      summary: Get user
      description: Retrieves a single user
      security:
        - basicAuth: []
        - tokenAuth: []
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/ClusterIdPath'
        - $ref: '#/components/parameters/UsernamePath'
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResource'
        default:
          $ref: '#/components/responses/ApiError'

    patch:
      operationId: usersPatch
      summary: Patch user
      description: Patches a single user. Only changing the password is supported. System users cannot be patched.
      security:
        - basicAuth: []
        - tokenAuth: []
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/ClusterIdPath'
        - $ref: '#/components/parameters/UsernamePath'
      requestBody:
        $ref: '#/components/requestBodies/PatchUserRequest'
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResource'
        default:
          $ref: '#/components/responses/ApiError'

    delete:
      operationId: usersDelete
      summary: Delete user
      description: Deletes a single user
      security:
        - basicAuth: []
        - tokenAuth: []
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/ClusterIdPath'
        - $ref: '#/components/parameters/UsernamePath'
      responses:
        "204":
          description: Successful response
        default:
          $ref: '#/components/responses/ApiError'

  /clusters/{clusterId}/databases:
    get:
      operationId: databasesList
      summary: List databases
      description: Retrieves a list of databases
      security:
        - basicAuth: []
        - tokenAuth: []
      tags:
        - Databases
      parameters:
        - $ref: '#/components/parameters/ClusterIdPath'
        - $ref: '#/components/parameters/PaginationLimit'
        - $ref: '#/components/parameters/PaginationOffset'
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseList'
        default:
          $ref: '#/components/responses/ApiError'

    post:
      operationId: databasesPost
      summary: Create a database
      description: Create a new database
      security:
        - basicAuth: []
        - tokenAuth: []
      tags:
        - Databases
      parameters:
        - $ref: '#/components/parameters/ClusterIdPath'
      requestBody:
        description: a database to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Database'
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseResource'
        default:
          $ref: '#/components/responses/ApiError'

  /clusters/{clusterId}/databases/{databasename}:
    get:
      operationId: databasesGet
      summary: Get database
      description: Retrieves a single database
      security:
        - basicAuth: []
        - tokenAuth: []
      tags:
        - Databases
      parameters:
        - $ref: '#/components/parameters/ClusterIdPath'
        - $ref: '#/components/parameters/DatabasenamePath'
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseResource'
        default:
          $ref: '#/components/responses/ApiError'

    delete:
      operationId: databasesDelete
      summary: Delete database
      description: Deletes a single database
      security:
        - basicAuth: []
        - tokenAuth: []
      tags:
        - Databases
      parameters:
        - $ref: '#/components/parameters/ClusterIdPath'
        - $ref: '#/components/parameters/DatabasenamePath'
      responses:
        "204":
          description: Successful response
        default:
          $ref: '#/components/responses/ApiError'

  /infos/version:
    get:
      operationId: infosVersionGet
      summary: Get the current API version
      description: Retrieves the current version of the responding API.
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Metadata
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIVersion'
        default:
          $ref: '#/components/responses/ApiError'

  /infos/versions:
    get:
      operationId: infosVersionsGet
      summary: Fetch all API versions
      description: Retrieves all available versions of the responding API.
      security:
      - basicAuth: []
      - tokenAuth: []
      tags:
      - Metadata
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIVersion'
        default:
          $ref: '#/components/responses/ApiError'

components:
  requestBodies:
    UserRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
    PatchUserRequest:
      required: true
      description: Patch containing all properties that should be updated
      content:
        application/json:
          schema:
            type: object
            required:
              - properties
            properties:
              properties:
                $ref: '#/components/schemas/PatchUserProperties'

  responses:
    ApiError:
      description: |
        Any erroneous status code: 400 (parse error), 401 (auth error),
        402 (trial access), 403 (insufficient permissions), 404 (not found),
        405 (unsupported HTTP method), 415 (unsupported content type,
        422 (validation error), 429 (request rate limit exceeded),
        500 (server error), 503 (maintenance)
      headers:
        Content-Type:
          description: application/problem+json
          schema:
            type: string
            default: application/problem+json
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  parameters:
    ClusterNameQuery:
      name: filter.name
      in: query
      description: |
        Response filter to list only the PostgreSQL clusters that contain
        the specified name. The value is case insensitive and matched on the
        'displayName' field.
      required: false
      schema:
        type: string

    ClusterIdPath:
      name: clusterId
      in: path
      description: The unique ID of the cluster.
      required: true
      schema:
        type: string
      example: 498ae72f-411f-11eb-9d07-046c59cc737e

    BackupIdPath:
      name: backupId
      in: path
      description: The unique ID of the backup.
      required: true
      schema:
        type: string
      example: 498ae72f-411f-11eb-9d07-046c59cc737e-4oymiqu-12

    UsernamePath:
      name: username
      in: path
      description: The authentication username.
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 63
      example: benjamin

    DatabasenamePath:
      name: databasename
      in: path
      description: The database name.
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 63
      example: benjamindb

    PaginationLimit:
      x-go-name: PaginationLimitParameter
      name: limit
      in: query
      description: The maximum number of elements to return. Use together with 'offset' for pagination.
      required: false
      schema:
        type: integer
        default: 100
        maximum: 1000
        minimum: 1
        example: 100

    PaginationOffset:
      x-go-name: PaginationOffsetParameter
      name: offset
      in: query
      description: The first element to return. Use together with 'limit' for pagination.
      required: false
      schema:
        type: integer
        default: 0
        example: 200

    SystemUserFilter:
      name: system
      in: query
      description: If set to 'true' all users, including system users are returned. System users cannot be deleted or updated.
      required: false
      schema:
        type: boolean

  schemas:
    ErrorResponse:
      properties:
        httpStatus:
          type: integer
          description: The HTTP status code of the operation.
          example: 400
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ErrorMessage'
      type: object

    ErrorMessage:
      properties:
        errorCode:
          type: string
          description: |
            Application internal error code
          example: dbaas-err-api-123
        message:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          example: Error message example
      type: object

    ResourceType:
      description: The type of the resource.
      type: string
      enum:
      - collection
      - cluster
      - backup
      - user
      - database

    ResourceId:
      type: string
      description: The unique ID of the resource.
      example: 498ae72f-411f-11eb-9d07-046c59cc737e

    ResourceHref:
      type: string
      description: Absolute URL of the resource.

    PostgresVersion:
      type: string
      description: The PostgreSQL version of your cluster.
      example: '13'

    Instances:
      type: integer
      description: |
        The total number of instances in the cluster (one master and n-1
        standbys).
      example: 2
      minimum: 1
      maximum: 5

    Cores:
      type: integer
      description: The number of CPU cores per instance.
      example: 4
      minimum: 1

    Ram:
      type: integer
      description: The amount of memory per instance in megabytes. Has to be a multiple of 1024.
      multipleOf: 1024
      example: 4096
      minimum: 4096

    StorageSize:
      type: integer
      description: The amount of storage per instance in megabytes.
      example: 15000
      minimum: 10240
      maximum: 2097152

    Location:
      type: string
      description: |
        The physical location where the cluster will be created. This will be
        where all of your instances live. Property cannot be modified after
        datacenter creation.
      example: de/fra
      x-extensible-enum:
      - de/fra
      - de/txl
      - gb/lhr
      - es/vit
      - us/ewr
      - us/las
      - us/mci
      - fr/par

    DisplayName:
      type: string
      description: The friendly name of your cluster.
      example: PostgreSQL cluster

    DNSName:
      type: string
      description: The DNS name pointing to your cluster.
      example: pg.example.com

    CreateClusterRequest:
      description: |
        Request payload with all data needed to create a new PostgreSQL cluster.
      properties:
        metadata:
          $ref: '#/components/schemas/ClusterMetadata'
        properties:
          $ref: '#/components/schemas/CreateClusterProperties'
      type: object

    CreateClusterProperties:
      description: |
        Properties with all data needed to create a new PostgreSQL cluster.
      required:
      - postgresVersion
      - instances
      - cores
      - ram
      - storageSize
      - storageType
      - connections
      - location
      - displayName
      - credentials
      - synchronizationMode
      properties:
        postgresVersion:
          $ref: '#/components/schemas/PostgresVersion'
        instances:
          $ref: '#/components/schemas/Instances'
        cores:
          $ref: '#/components/schemas/Cores'
        ram:
          $ref: '#/components/schemas/Ram'
        storageSize:
          $ref: '#/components/schemas/StorageSize'
        storageType:
          $ref: '#/components/schemas/StorageType'
        connections:
          type: array
          minItems: 1
          maxItems: 1
          items:
            $ref: '#/components/schemas/Connection'
        location:
          $ref: '#/components/schemas/Location'
        backupLocation:
          $ref: '#/components/schemas/BackupLocation'
        displayName:
          $ref: '#/components/schemas/DisplayName'
        maintenanceWindow:
          $ref: '#/components/schemas/MaintenanceWindow'
        credentials:
          $ref: '#/components/schemas/DBUser'
        synchronizationMode:
          $ref: '#/components/schemas/CreateSynchronizationMode'
        fromBackup:
          $ref: '#/components/schemas/CreateRestoreRequest'
        connectionPooler:
          $ref: '#/components/schemas/ConnectionPooler'
      type: object

    PatchClusterRequest:
      description: Request payload to change a cluster.
      properties:
        metadata:
          $ref: '#/components/schemas/ClusterMetadata'
        properties:
          $ref: '#/components/schemas/PatchClusterProperties'
      type: object

    PatchClusterProperties:
      description: Properties of the payload to change a cluster.
      properties:
        cores:
          $ref: '#/components/schemas/Cores'
        ram:
          $ref: '#/components/schemas/Ram'
        storageSize:
          $ref: '#/components/schemas/StorageSize'
        connections:
          type: array
          minItems: 0
          maxItems: 1
          items:
            $ref: '#/components/schemas/Connection'
        displayName:
          $ref: '#/components/schemas/DisplayName'
        maintenanceWindow:
          $ref: '#/components/schemas/MaintenanceWindow'
        postgresVersion:
          $ref: '#/components/schemas/PostgresVersion'
        instances:
          $ref: '#/components/schemas/Instances'
        connectionPooler:
          $ref: '#/components/schemas/ConnectionPooler'
        synchronizationMode:
          $ref: '#/components/schemas/SynchronizationMode'
      type: object

    CreateRestoreRequest:
      description: The restore request.
      properties:
        backupId:
          type: string
          example: dcd31531-3ac8-11eb-9feb-046c59cc737e
          description: The unique ID of the backup you want to restore.
        recoveryTargetTime:
          type: string
          format: date-time
          description: |
            If this value is supplied as ISO 8601 timestamp, the backup will be
            replayed up until the given timestamp. If empty, the backup will be
            applied completely.
          example: '2020-12-10T13:37:50+01:00'
      required:
      - backupId
      type: object

    DBUser:
      description: Credentials for the database user to be created.
      properties:
        username:
          type: string
          description: |
            The username for the initial PostgreSQL user. Some system usernames
            are restricted (e.g. "postgres", "admin", "standby").
          example: db-admin
        password:
          type: string
          example: password123
          minLength: 10
      required:
      - username
      - password
      type: object

    Connection:
      description: Details about the network connection for your cluster.
      properties:
        datacenterId:
          description: The datacenter to connect your cluster to.
          type: string
          example: '5a029f4a-72e5-11ec-90d6-0242ac120003'
        lanId:
          description: The numeric LAN ID to connect your cluster to.
          type: string
          example: '2'
        cidr:
          type: string
          description: |
            The IP and subnet for your cluster.
            Note the following unavailable IP ranges:
            10.233.64.0/18
            10.233.0.0/18
            10.233.114.0/24
          example: 192.168.1.100/24
      required:
      - datacenterId
      - lanId
      - cidr
      type: object

    ClusterMetadata:
      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'
        createdBy:
          type: string
          example: john.doe@example.com
        createdByUserId:
          type: string
          example: 87f9a82e-b28d-49ed-9d04-fba2c0459cd3
        lastModifiedDate:
          type: string
          format: date-time
          description: The ISO 8601 modified timestamp.
          example: '2020-12-11T13:37:50+01:00'
        lastModifiedBy:
          type: string
          example: jane.doe@example.com
        lastModifiedByUserId:
          type: string
          example: 87f9a82e-b28d-49ed-9d04-fba2c0459cd3
        state:
          $ref: '#/components/schemas/State'

    State:
      description: The current status reported back by the cluster.
      type: string
      enum:
      - AVAILABLE
      - BUSY
      - DESTROYING
      - DEGRADED
      - FAILED
      - UNKNOWN
      example: AVAILABLE

    BackupMetadata:
      description: Metadata of the backup resource.
      properties:
        createdDate:
          type: string
          format: date-time
          description: The ISO 8601 creation timestamp.
          example: '2020-12-10T13:37:50+01:00'
        state:
          $ref: '#/components/schemas/State'
      type: object

    ClusterResponse:
      description: A database cluster.
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/ResourceType'
          example: cluster
        id:
          $ref: '#/components/schemas/ResourceId'
        metadata:
          $ref: '#/components/schemas/ClusterMetadata'
        properties:
          $ref: '#/components/schemas/ClusterProperties'
      type: object

    ClusterProperties:
      description: Properties of a database cluster.
      properties:
        displayName:
          $ref: '#/components/schemas/DisplayName'
        postgresVersion:
          $ref: '#/components/schemas/PostgresVersion'
        location:
          $ref: '#/components/schemas/Location'
        dnsName:
          $ref: '#/components/schemas/DNSName'
        backupLocation:
          $ref: '#/components/schemas/BackupLocation'
        instances:
          $ref: '#/components/schemas/Instances'
        ram:
          $ref: '#/components/schemas/Ram'
        cores:
          $ref: '#/components/schemas/Cores'
        storageSize:
          $ref: '#/components/schemas/StorageSize'
        storageType:
          $ref: '#/components/schemas/StorageType'
        connections:
          type: array
          minItems: 1
          maxItems: 1
          items:
            $ref: '#/components/schemas/Connection'
        maintenanceWindow:
          $ref: '#/components/schemas/MaintenanceWindow'
        synchronizationMode:
          $ref: '#/components/schemas/SynchronizationMode'
        connectionPooler:
          $ref: '#/components/schemas/ConnectionPooler'
      type: object

    BackupResponse:
      description: A database backup.
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/ResourceType'
          example: backup
        id:
          $ref: '#/components/schemas/ResourceId'
        metadata:
          $ref: '#/components/schemas/BackupMetadata'
        properties:
          $ref: '#/components/schemas/ClusterBackup'
      type: object

    ClusterBackup:
      description: A backup object.
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
        clusterId:
          type: string
          description: The unique ID of the cluster.
          example: 498ae72f-411f-11eb-9d07-046c59cc737e
        version:
          type: string
          description: The PostgreSQL version this backup was created from.
          example: "14"
        isActive:
          type: boolean
          description: Whether a cluster currently backs up data to this backup.
          example: true
        earliestRecoveryTargetTime:
          type: string
          format: date-time
          description: The oldest available timestamp to which you can restore.
          example: '2021-10-23T01:21:10Z'
        size:
          type: integer
          description: Size of all base backups including the wal size in MB.
          example: 2052
        location:
          $ref: '#/components/schemas/BackupLocation'
      type: object

    BackupLocation:
      type: string
      description: The S3 location where the backups will be stored.
      example: de
      x-extensible-enum:
      - de
      - eu-south-2
      - eu-central-3
      - eu-central-4
      - us-central-1

    MaintenanceWindow:
      description: |
        A weekly 4 hour-long window, during which maintenance might occur.
      properties:
        time:
          type: string
          description: Start of the maintenance window in UTC time.
          example: '16:30:59'
        dayOfTheWeek:
          $ref: '#/components/schemas/DayOfTheWeek'
      required:
      - time
      - dayOfTheWeek
      type: object

    DayOfTheWeek:
      description: The name of the week day.
      type: string
      enum:
      - Sunday
      - Monday
      - Tuesday
      - Wednesday
      - Thursday
      - Friday
      - Saturday
      example: Monday

    APIVersion:
      properties:
        name:
          type: string
          example: v2.1
        swaggerUrl:
          type: string
          example: https://api.ionos.com/databases/postgres/infos/assets/swagger-v2.1.yml
      type: object

    StorageType:
      description: The storage type used in your cluster. (Value "SSD" is deprecated. Use the equivalent "SSD Premium" instead)
      type: string
      enum:
      - HDD
      - SSD
      - SSD Standard
      - SSD Premium
      example: HDD

    DeprecatedPagination:
      description: Pagination information in list responses. DEPRECATED because of misspelled _links attribute.
      type: object
      properties:
        offset:
          $ref: '#/components/schemas/PaginationOffset'
        limit:
          $ref: '#/components/schemas/PaginationLimit'
        links:
          $ref: '#/components/schemas/PaginationLinks'

    Pagination:
      description: Pagination information in list responses.
      type: object
      properties:
        offset:
          $ref: '#/components/schemas/PaginationOffset'
        limit:
          $ref: '#/components/schemas/PaginationLimit'
        _links:
          $ref: '#/components/schemas/PaginationLinks'

    PaginationOffset:
      description: |
        The offset specified in the request (if none was specified, the default
        offset is 0).
      type: integer
      example: 200
      minimum: 0
      default: 0

    PaginationLimit:
      description: |
        The limit specified in the request (if none was specified, the default
        limit is 100).
      type: integer
      example: 100
      minimum: 0
      default: 100
      maximum: 1000

    PaginationLinks:
      description: |
        URLs to navigate the different pages.
      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: <PREVIOUS-PAGE-URI>
          readOnly: true
        self:
          description: |
            URL (with offset and limit parameters) of the current page.
          type: string
          format: uri
          example: <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: <NEXT-PAGE-URI>
          readOnly: true

    ClusterList:
      description: List of clusters.
      allOf:
      - type: object
        properties:
          type:
            $ref: '#/components/schemas/ResourceType'
          id:
            $ref: '#/components/schemas/ResourceId'
          items:
            type: array
            items:
              $ref: '#/components/schemas/ClusterResponse'
      - $ref: '#/components/schemas/DeprecatedPagination'
      type: object

    ClusterBackupList:
      description: List of backups.
      allOf:
      - type: object
        properties:
          type:
            $ref: '#/components/schemas/ResourceType'
          id:
            $ref: '#/components/schemas/ResourceId'
          items:
            type: array
            items:
              $ref: '#/components/schemas/BackupResponse'
      - $ref: '#/components/schemas/DeprecatedPagination'

    PostgresVersionList:
      description: List of PostgreSQL versions.
      properties:
        data:
          type: array
          items:
            properties:
              name:
                type: string
                example: "14"
            type: object
      type: object

    ClusterLogs:
      description: The logs of the PostgreSQL cluster.
      properties:
        instances:
          type: array
          items:
            properties:
              name:
                description: The name of the PostgreSQL instance.
                type: string
                example: postgres-cluster-0
              messages:
                type: array
                items:
                  type: object
                  properties:
                    time:
                      type: string
                      format: date-time
                      example: '2021-09-06T10:00:38.253+02:00'
                    message:
                      type: string
                      example: Hello World

            type: object
      type: object

    CreateSynchronizationMode:
      description: |
        Represents the supported replication modes when creating a cluster.
        The SYNCHRONOUS mode is deprecated and cannot be used in create requests.
        It may still appear on existing clusters via the SynchronizationMode response schema.
        You may update your cluster to one of the supported modes yourself.
        Else, it will eventually be migrated to one of the supported modes.
      type: string
      enum:
      - ASYNCHRONOUS
      - STRICTLY_SYNCHRONOUS
      example: ASYNCHRONOUS

    SynchronizationMode:
      description: |
        Represents different modes of replication.
        Be aware that the SYNCHRONOUS mode is deprecated and will be removed in future versions.
        Existing clusters will eventually be migrated to one of the supported modes.
      type: string
      enum:
      - ASYNCHRONOUS
      - SYNCHRONOUS
      - STRICTLY_SYNCHRONOUS
      example: ASYNCHRONOUS

    ConnectionPooler:
      description: Configuration options for the connection pooler
      properties:
        enabled:
          type: boolean
        poolMode:
          $ref: '#/components/schemas/PoolMode'

    PoolMode:
      description: |
        Represents different modes of connection pooling for the connection pooler.
      type: string
      enum:
        - transaction
        - session
      example: transaction

    UserList:
      type: object
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - $ref: '#/components/schemas/Resource'
        - $ref: '#/components/schemas/UserItems'

    UserItems:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/UserResource'

    UserResource:
      type: object
      allOf:
        - $ref: '#/components/schemas/Resource'
        - $ref: '#/components/schemas/ResourceMetadata'
        - $ref: '#/components/schemas/User'

    User:
      type: object
      required:
        - properties
      properties:
        properties:
          $ref: '#/components/schemas/UserProperties'

    PatchUserProperties:
      type: object
      properties:
        password:
          $ref: '#/components/schemas/Password'

    UserProperties:
      type: object
      required:
        - username
      properties:
        username:
          $ref: '#/components/schemas/Username'
        password:
          $ref: '#/components/schemas/Password'
        system:
          $ref: '#/components/schemas/IsSystemUser'

    Username:
      type: string
      description: The username of a given user.
      minLength: 1
      maxLength: 63
      example: benjamin

    Password:
      type: string
      description: The password of a given user.
      writeOnly: true
      minLength: 10
      maxLength: 63
      example: TopSecret!

    IsSystemUser:
      type: boolean
      description: Describes whether this user is a system user or not. A system user cannot be updated or deleted.
      readOnly: true
      example: false

    DatabaseList:
      type: object
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - $ref: '#/components/schemas/Resource'
        - $ref: '#/components/schemas/DatabaseItems'

    DatabaseItems:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DatabaseResource'

    DatabaseResource:
      type: object
      allOf:
        - $ref: '#/components/schemas/Resource'
        - $ref: '#/components/schemas/ResourceMetadata'
        - $ref: '#/components/schemas/Database'

    Database:
      type: object
      required:
        - properties
      properties:
        properties:
          $ref: '#/components/schemas/DatabaseProperties'

    DatabaseProperties:
      type: object
      required:
        - name
        - owner
      properties:
        name:
          $ref: '#/components/schemas/Databasename'
        owner:
          $ref: '#/components/schemas/Databaseowner'

    Databasename:
      type: string
      description: The databasename of a given database.
      example: benjamindb
      minLength: 1
      maxLength: 63

    Databaseowner:
      type: string
      description: The name of the role owning a given database.
      example: benjamin
      minLength: 1
      maxLength: 63

    Resource:
      type: object
      required:
        - type
        - id
        - href
      properties:
        type:
          $ref: '#/components/schemas/ResourceType'
        id:
          $ref: '#/components/schemas/ResourceId'
        href:
          $ref: '#/components/schemas/ResourceHref'

    ResourceMetadata:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/Metadata'

    Metadata:
      type: object
      properties:
        createdBy:
          $ref: '#/components/schemas/UserIdentityURN'
        createdByUserId:
          $ref: '#/components/schemas/UserIdentityUUID'
        createdDate:
          $ref: '#/components/schemas/Timestamp'
        lastModifiedBy:
          $ref: '#/components/schemas/UserIdentityURN'
        lastModifiedByUserId:
          $ref: '#/components/schemas/UserIdentityUUID'
        lastModifiedDate:
          $ref: '#/components/schemas/Timestamp'
        resourceURN:
          $ref: '#/components/schemas/ResourceURN'

    UserIdentityURN:
      type: string
      description: The URN of an IAM user.
      example: 'ionos:iam:cloud::users/f719718d-e0aa-4870-a36c-cc0bdb8c6d90'

    UserIdentityUUID:
      type: string
      format: uuid
      description: The ID of an IAM user.
      example: 'f719718d-e0aa-4870-a36c-cc0bdb8c6d90'

    Timestamp:
      type: string
      format: date-time
      description: An ISO 8601 timestamp.
      example: '2023-05-11T13:37:50Z'

    ResourceURN:
      type: string
      description: The URN of the resource.
      example: 'ionos:postgresql:de-fra:11274857:clusters/c668480f-8627-4b6c-b422-2599d4b568a6/users/benjamin'

  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: |
        You will need to base64 encode the string containing your credentials.
        Separate your username and password with a colon, i.e.,
        username:password and send it as 'Authorization' request header. More
        details: https://en.wikipedia.org/wiki/Basic_access_authentication.
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Please provide header value as 'Bearer <token>' and don't forget to add
        'Bearer' HTTP Authorization Scheme before the token.
