Amazon MSK Msk Channels API

openapi: 3.2.0
info:
  title: Managed Streaming for Kafka Channels API
  version: '2018-11-14'
  description: Generated from AWS's published Smithy model for Managed Streaming for Kafka. 5 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://kafka.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Channels
paths:
  /v1/clusters/{ClusterArn}/channels:
    post:
      operationId: CreateChannel
      summary: Create Channel
      description: Creates a Channel that streams records from an Amazon MSK Express cluster topic to Amazon S3 or Apache Iceberg.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChannelResponse'
        '400':
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '403':
          description: ForbiddenException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenException'
        '500':
          description: InternalServerErrorException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorException'
        '404':
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundException'
        '503':
          description: ServiceUnavailableException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableException'
        '429':
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
        '401':
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChannelRequest'
      tags:
      - Channels
    get:
      operationId: ListChannels
      summary: List Channels
      description: Returns the list of channels in a cluster.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListChannelsResponse'
        '400':
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestException'
        '403':
          description: ForbiddenException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenException'
        '500':
          description: InternalServerErrorException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorException'
        '404':
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundException'
        '503':
          description: ServiceUnavailableException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableException'
        '429':
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
        '401':
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListChannelsRequest'
      tags:
      - Channels
  /v1/clusters/{ClusterArn}/channels/{ChannelArn}:
    delete:
      operationId: DeleteChannel
      summary: Delete Channel
      description: Deletes the channel specified by channelArn from the cluster specified by clusterArn. The channel transitions through DELETING and is removed when the asynchronous delete completes.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteChannelResponse'
        '400':
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestException'
        '403':
          description: ForbiddenException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenException'
        '500':
          description: InternalServerErrorException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorException'
        '404':
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundException'
        '503':
          description: ServiceUnavailableException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableException'
        '429':
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
        '401':
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteChannelRequest'
      tags:
      - Channels
    get:
      operationId: DescribeChannel
      summary: Describe Channel
      description: Returns the current configuration and state of a channel.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DescribeChannelResponse'
        '400':
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestException'
        '403':
          description: ForbiddenException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenException'
        '500':
          description: InternalServerErrorException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorException'
        '404':
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundException'
        '503':
          description: ServiceUnavailableException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableException'
        '429':
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
        '401':
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DescribeChannelRequest'
      tags:
      - Channels
    put:
      operationId: UpdateChannel
      summary: Update Channel
      description: Updates the destination configuration of an existing channel. Exactly one of icebergDestinationUpdate or s3DestinationUpdate must be supplied.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateChannelResponse'
        '400':
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestException'
        '403':
          description: ForbiddenException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenException'
        '500':
          description: InternalServerErrorException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorException'
        '404':
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundException'
        '503':
          description: ServiceUnavailableException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableException'
        '429':
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
        '401':
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateChannelRequest'
      tags:
      - Channels
components:
  schemas:
    DescribeChannelResponse:
      type: object
      properties:
        ChannelArn:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the channel.
        ChannelName:
          type: string
          description: The name of the channel.
        EncryptionConfiguration:
          $ref: '#/components/schemas/EncryptionConfiguration'
        IcebergDestinationConfiguration:
          $ref: '#/components/schemas/IcebergDestinationConfiguration'
        S3DestinationConfiguration:
          $ref: '#/components/schemas/S3DestinationConfiguration'
        Status:
          type: string
          enum:
          - CREATING
          - ACTIVE
          - UPDATING
          - DELETING
          - FAILED
          - SUSPENDING
          - SUSPENDED
          description: The current lifecycle state of the channel.
        DestinationType:
          type: string
          enum:
          - ICEBERG
          - S3
          description: The type of destination configured for the channel.
        CreationTime:
          type: string
          format: date-time
          description: The time when the channel was created.
        TopicConfigurationList:
          type: array
          items:
            $ref: '#/components/schemas/TopicConfiguration'
          description: The list of topic configurations for the channel.
        LoggingInfo:
          $ref: '#/components/schemas/ChannelLoggingInfo'
        StateInfo:
          $ref: '#/components/schemas/ChannelStateInfo'
        ClusterOperationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the in-flight cluster operation. Returned only while the channel is in CREATING, UPDATING, or DELETING.
        Tags:
          type: object
          additionalProperties:
            type: string
          description: The tags attached to the channel.
      required:
      - ChannelArn
      - ChannelName
      - Status
      - DestinationType
      - CreationTime
      - TopicConfigurationList
    S3:
      type: object
      properties:
        Bucket:
          type: string
        Enabled:
          type: boolean
        Prefix:
          type: string
      required:
      - Enabled
    DestinationTable:
      type: object
      properties:
        DestinationDatabaseName:
          type: string
          description: The name of the destination namespace (database) in the AWS Glue Data Catalog.
        DestinationTableName:
          type: string
          description: The name of the destination Apache Iceberg table.
        PartitionSpec:
          $ref: '#/components/schemas/PartitionSpec'
    Catalog:
      type: object
      properties:
        CatalogArn:
          type: string
          description: The Amazon Resource Name (ARN) of the federated AWS Glue Data Catalog that projects the S3 Tables bucket. If omitted, MSK derives the catalog ARN from warehouseLocation.
        WarehouseLocation:
          type: string
          description: The Amazon Resource Name (ARN) of the S3 Tables bucket that backs the Apache Iceberg warehouse.
    RecordSchema:
      type: object
      properties:
        GsrArn:
          type: string
          description: The Amazon Resource Name (ARN) of the AWS Glue Schema Registry schema (not registry) used to validate records for the destination Apache Iceberg table.
      required:
      - GsrArn
    CreateChannelResponse:
      type: object
      properties:
        ChannelArn:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the channel.
        ClusterOperationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the cluster operation.
      required:
      - ChannelArn
    ChannelLoggingInfo:
      type: object
      properties:
        CloudWatchLogs:
          $ref: '#/components/schemas/CloudWatchLogs'
        Firehose:
          $ref: '#/components/schemas/Firehose'
        S3:
          $ref: '#/components/schemas/S3'
    CloudWatchLogs:
      type: object
      properties:
        Enabled:
          type: boolean
        LogGroup:
          type: string
      required:
      - Enabled
    InternalServerErrorException:
      type: object
      properties:
        InvalidParameter:
          type: string
          description: The parameter that caused the error.
        Message:
          type: string
          description: The description of the error.
    TopicConfiguration:
      type: object
      properties:
        RecordConverter:
          $ref: '#/components/schemas/RecordConverter'
        RecordSchema:
          $ref: '#/components/schemas/RecordSchema'
        TopicArn:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the topic.
      required:
      - RecordConverter
      - TopicArn
    UnauthorizedException:
      type: object
      properties:
        InvalidParameter:
          type: string
          description: The parameter that caused the error.
        Message:
          type: string
          description: The description of the error.
    S3Storage:
      type: object
      properties:
        BucketArn:
          type: string
          description: The Amazon Resource Name (ARN) of the destination Amazon S3 bucket.
        CompressionType:
          type: string
          enum:
          - NONE
          - GZIP
          - ZSTD
          description: The compression codec applied to delivered Amazon S3 objects.
        OutputPrefix:
          type: string
          description: An optional prefix prepended to every Amazon S3 object key written by the channel.
        OutputKeyTemplate:
          type: string
          description: An optional template that controls the Amazon S3 object key for each delivered record. Supports the placeholders !{partition-id}, !{sequence-number}, and !{kafka-offset}.
        StorageClass:
          type: string
          enum:
          - STANDARD
          - INTELLIGENT_TIERING
          - GLACIER_IR
          description: The Amazon S3 storage class for delivered objects.
        ExpectedBucketOwner:
          type: string
          description: Optional 12-digit AWS account ID expected to own the Amazon S3 bucket.
      required:
      - BucketArn
      - CompressionType
      - StorageClass
    DeleteChannelResponse:
      type: object
      properties:
        ChannelArn:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the channel.
        ClusterOperationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the cluster operation.
      required:
      - ChannelArn
    ConflictException:
      type: object
      properties:
        InvalidParameter:
          type: string
          description: The parameter that caused the error.
        Message:
          type: string
          description: The description of the error.
    S3DestinationUpdate:
      type: object
      properties:
        DataFreshnessInSeconds:
          type: integer
          description: 'The maximum time, in seconds, that records buffer in MSK before being flushed to the destination. Allowed range: 300 to 900.'
      required:
      - DataFreshnessInSeconds
    BadRequestException:
      type: object
      properties:
        InvalidParameter:
          type: string
          description: The parameter that caused the error.
        Message:
          type: string
          description: The description of the error.
    Firehose:
      type: object
      properties:
        DeliveryStream:
          type: string
        Enabled:
          type: boolean
      required:
      - Enabled
    NotFoundException:
      type: object
      properties:
        InvalidParameter:
          type: string
          description: The parameter that caused the error.
        Message:
          type: string
          description: The description of the error.
    UpdateChannelResponse:
      type: object
      properties:
        ChannelArn:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the channel.
        ClusterOperationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the cluster operation.
      required:
      - ChannelArn
    EncryptionConfiguration:
      type: object
      properties:
        KmsKeyArn:
          type: string
          description: The Amazon Resource Name (ARN) of the AWS KMS key used to encrypt the data.
      required:
      - KmsKeyArn
    DeleteChannelRequest:
      type: object
      properties:
        ChannelArn:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the channel.
        ClusterArn:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the cluster.
      required:
      - ChannelArn
      - ClusterArn
    ChannelInfo:
      type: object
      properties:
        ChannelArn:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the channel.
        ChannelName:
          type: string
          description: The name of the channel.
        Status:
          type: string
          enum:
          - CREATING
          - ACTIVE
          - UPDATING
          - DELETING
          - FAILED
          - SUSPENDING
          - SUSPENDED
          description: The current lifecycle state of the channel.
        CreationTime:
          type: string
          format: date-time
          description: The time when the channel was created.
        DestinationType:
          type: string
          enum:
          - ICEBERG
          - S3
          description: The type of destination configured for the channel.
        ClusterOperationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the in-flight cluster operation. Returned only while the channel is in CREATING, UPDATING, or DELETING.
      required:
      - ChannelArn
      - ChannelName
      - Status
      - CreationTime
      - DestinationType
    TooManyRequestsException:
      type: object
      properties:
        InvalidParameter:
          type: string
          description: The parameter that caused the error.
        Message:
          type: string
          description: The description of the error.
    CreateChannelRequest:
      type: object
      properties:
        ChannelName:
          type: string
          description: The name of the channel. Must be unique within the cluster.
        ClusterArn:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the cluster.
        EncryptionConfiguration:
          $ref: '#/components/schemas/EncryptionConfiguration'
        IcebergDestinationConfiguration:
          $ref: '#/components/schemas/IcebergDestinationConfiguration'
        S3DestinationConfiguration:
          $ref: '#/components/schemas/S3DestinationConfiguration'
        Tags:
          type: object
          additionalProperties:
            type: string
          description: The tags attached to the channel.
        TopicConfigurationList:
          type: array
          items:
            $ref: '#/components/schemas/TopicConfiguration'
          description: The list of topic configurations for the channel. Currently exactly one topic must be specified.
        LoggingInfo:
          $ref: '#/components/schemas/ChannelLoggingInfo'
      required:
      - ChannelName
      - ClusterArn
      - TopicConfigurationList
    UpdateChannelRequest:
      type: object
      properties:
        ChannelArn:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the channel.
        ClusterArn:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the cluster.
        IcebergDestinationUpdate:
          $ref: '#/components/schemas/IcebergDestinationUpdate'
        S3DestinationUpdate:
          $ref: '#/components/schemas/S3DestinationUpdate'
      required:
      - ChannelArn
      - ClusterArn
    IcebergDestinationConfiguration:
      type: object
      properties:
        AppendOnly:
          type: boolean
          description: Whether the destination is append-only. Must be true; updates and deletes are not supported.
        Catalog:
          $ref: '#/components/schemas/Catalog'
        DataFreshnessInSeconds:
          type: integer
          description: 'The maximum time, in seconds, that records buffer in MSK before being flushed to the destination. Allowed range: 300 to 900. Default: 600.'
        DeadLetterQueueS3:
          $ref: '#/components/schemas/DeadLetterQueueS3'
        DestinationTableList:
          type: array
          items:
            $ref: '#/components/schemas/DestinationTable'
          description: The destination Iceberg tables. Currently exactly one table must be specified.
        SchemaEvolution:
          $ref: '#/components/schemas/SchemaEvolution'
        ServiceExecutionRoleArn:
          type: string
          description: The Amazon Resource Name (ARN) of the IAM role that MSK assumes to access the destination table, the AWS Glue Data Catalog, and the dead-letter Amazon S3 bucket.
        TableCreation:
          $ref: '#/components/schemas/TableCreation'
        CompressionType:
          type: string
          enum:
          - ZSTD
          - SNAPPY
          description: The compression codec for Iceberg table data files. Defaults to ZSTD.
      required:
      - AppendOnly
      - DeadLetterQueueS3
      - DestinationTableList
      - SchemaEvolution
      - ServiceExecutionRoleArn
      - TableCreation
    TableCreation:
      type: object
      properties:
        EnableTableCreation:
          type: boolean
          description: Whether MSK creates the destination table on the customer's behalf. Must be true for the current release.
    S3DestinationConfiguration:
      type: object
      properties:
        DataFreshnessInSeconds:
          type: integer
          description: 'The maximum time, in seconds, that records buffer in MSK before being flushed to the destination. Allowed range: 300 to 900. Default: 600.'
        DeadLetterQueueS3:
          $ref: '#/components/schemas/DeadLetterQueueS3'
        ServiceExecutionRoleArn:
          type: string
          description: The Amazon Resource Name (ARN) of the IAM role that MSK assumes to write to the destination Amazon S3 bucket and the dead-letter bucket.
        Storage:
          $ref: '#/components/schemas/S3Storage'
      required:
      - DeadLetterQueueS3
      - ServiceExecutionRoleArn
      - Storage
    IcebergDestinationUpdate:
      type: object
      properties:
        DataFreshnessInSeconds:
          type: integer
          description: 'The maximum time, in seconds, that records buffer in MSK before being flushed to the destination. Allowed range: 300 to 900.'
      required:
      - DataFreshnessInSeconds
    DescribeChannelRequest:
      type: object
      properties:
        ChannelArn:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the channel.
        ClusterArn:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the cluster.
      required:
      - ChannelArn
      - ClusterArn
    DeadLetterQueueS3:
      type: object
      properties:
        BucketArn:
          type: string
          description: The Amazon Resource Name (ARN) of the dead-letter Amazon S3 bucket.
        ErrorOutputPrefix:
          type: string
          description: An optional prefix prepended to every dead-letter Amazon S3 object key.
        ExpectedBucketOwner:
          type: string
          description: Optional 12-digit AWS account ID expected to own the dead-letter Amazon S3 bucket.
      required:
      - BucketArn
    PartitionSpec:
      type: object
      properties:
        PartitionStrategy:
          type: string
          enum:
          - TIME_HOUR
          description: The partitioning strategy applied to records written to the table.
        SourceList:
          type: array
          items:
            $ref: '#/components/schemas/PartitionSource'
          description: The source columns used by the partitioning strategy. For TIME_HOUR, must contain exactly one source column whose value is a timestamp.
      required:
      - PartitionStrategy
    ListChannelsResponse:
      type: object
      properties:
        Channels:
          type: array
          items:
            $ref: '#/components/schemas/ChannelInfo'
          description: The list of channels in the cluster.
        NextToken:
          type: string
          description: If the response from ListChannels is truncated, this token is included. Send it as the nextToken parameter on a subsequent ListChannels call to retrieve the next page.
    ListChannelsRequest:
      type: object
      properties:
        ClusterArn:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the cluster.
        MaxResults:
          type: integer
          description: Maximum number of channels to return in a single response.
        NextToken:
          type: string
          description: If the response of ListChannels is truncated, it returns a nextToken in the response. This nextToken should be sent in the subsequent request to ListChannels.
        TopicNameFilter:
          type: string
          description: Filters results to channels whose topic name matches the specified value.
      required:
      - ClusterArn
    ServiceUnavailableException:
      type: object
      properties:
        InvalidParameter:
          type: string
          description: The parameter that caused the error.
        Message:
          type: string
          description: The description of the error.
    PartitionSource:
      type: object
      properties:
        SourceName:
          type: string
          description: Source name.
    SchemaEvolution:
      type: object
      properties:
        EnableSchemaEvolution:
          type: boolean
          description: Whether to allow MSK to evolve the destination table's schema. Must be false for the current release.
    ForbiddenException:
      type: object
      properties:
        InvalidParameter:
          type: string
          description: The parameter that caused the error.
        Message:
          type: string
          description: The description of the error.
    ChannelStateInfo:
      type: object
      properties:
        Code:
          type: string
          description: A short, machine-readable code identifying the failure cause.
        Message:
          type: string
          description: A human-readable message describing the failure.
    RecordConverter:
      type: object
      properties:
        ValueConverter:
          type: string
          enum:
          - BYTE_ARRAY
          - JSON
          - JSON_SCHEMA_GSR
          - STRING
          description: The deserialization format applied to Apache Kafka record values.
      required:
      - ValueConverter
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: kafka
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/kafka/service/2018-11-14/kafka-2018-11-14.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)