AWS Kinesis #X Amz Target=Kinesis 20131202.DescribeStream API

openapi: 3.2.0
info:
  version: 2013-12-02
  x-release: v4
  title: 'Amazon Kinesis #X Amz Target=Kinesis 20131202.DescribeStream API'
  description: <fullname>Amazon Kinesis Data Streams Service API Reference</fullname> <p>Amazon Kinesis Data Streams is a managed service that scales elastically for real-time processing of streaming big data.</p>
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_twitter.com_awscloud_profile_image.png
    backgroundColor: '#FFFFFF'
  termsOfService: https://aws.amazon.com/service-terms/
  contact:
    name: Mike Ralphson
    email: mike.ralphson@gmail.com
    url: https://github.com/mermade/aws2openapi
    x-twitter: PermittedSoc
  license:
    name: Apache 2.0 License
    url: http://www.apache.org/licenses/
  x-providerName: amazonaws.com
  x-serviceName: kinesis
  x-origin:
  - contentType: application/json
    url: https://raw.githubusercontent.com/aws/aws-sdk-js/master/apis/kinesis-2013-12-02.normal.json
    converter:
      url: https://github.com/mermade/aws2openapi
      version: 1.0.0
    x-apisguru-driver: external
  x-apiClientRegistration:
    url: https://portal.aws.amazon.com/gp/aws/developer/registration/index.html?nc2=h_ct
  x-apisguru-categories:
  - cloud
  x-preferred: true
servers:
- url: http://kinesis.{region}.amazonaws.com
  variables:
    region:
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - us-gov-west-1
      - us-gov-east-1
      - ca-central-1
      - eu-north-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-south-1
      - af-south-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-east-1
      - ap-south-1
      - sa-east-1
      - me-south-1
      default: us-east-1
  description: The Kinesis multi-region endpoint
- url: https://kinesis.{region}.amazonaws.com
  variables:
    region:
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - us-gov-west-1
      - us-gov-east-1
      - ca-central-1
      - eu-north-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-south-1
      - af-south-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-east-1
      - ap-south-1
      - sa-east-1
      - me-south-1
      default: us-east-1
  description: The Kinesis multi-region endpoint
- url: http://kinesis.{region}.amazonaws.com.cn
  variables:
    region:
      description: The AWS region
      enum:
      - cn-north-1
      - cn-northwest-1
      default: cn-north-1
  description: The Kinesis endpoint for China (Beijing) and China (Ningxia)
- url: https://kinesis.{region}.amazonaws.com.cn
  variables:
    region:
      description: The AWS region
      enum:
      - cn-north-1
      - cn-northwest-1
      default: cn-north-1
  description: The Kinesis endpoint for China (Beijing) and China (Ningxia)
security:
- hmac: []
tags:
- name: '#X Amz Target=Kinesis 20131202.DescribeStream'
paths:
  /#X-Amz-Target=Kinesis_20131202.DescribeStream:
    parameters:
    - $ref: '#/components/parameters/X-Amz-Content-Sha256'
    - $ref: '#/components/parameters/X-Amz-Date'
    - $ref: '#/components/parameters/X-Amz-Algorithm'
    - $ref: '#/components/parameters/X-Amz-Credential'
    - $ref: '#/components/parameters/X-Amz-Security-Token'
    - $ref: '#/components/parameters/X-Amz-Signature'
    - $ref: '#/components/parameters/X-Amz-SignedHeaders'
    post:
      operationId: DescribeStream
      description: <p>Describes the specified Kinesis data stream.</p> <note> <p>This API has been revised. It's highly recommended that you use the <a>DescribeStreamSummary</a> API to get a summarized description of the specified Kinesis data stream and the <a>ListShards</a> API to list the shards in a specified data stream and obtain information about each shard. </p> </note> <note> <p>When invoking this API, it is recommended you use the <code>StreamARN</code> input parameter rather than the <code>StreamName</code> input parameter.</p> </note> <p>The information returned includes the stream name, Amazon Resource Name (ARN), creation time, enhanced metric configuration, and shard map. The shard map is an array of shard objects. For each shard object, there is the hash key and sequence number ranges that the shard spans, and the IDs of any earlier shards that played in a role in creating the shard. Every record ingested in the stream is identified by a sequence number, which is assigned when the record is put into the stream.</p> <p>You can limit the number of shards returned by each call. For more information, see <a href="https://docs.aws.amazon.com/kinesis/latest/dev/kinesis-using-sdk-java-retrieve-shards.html">Retrieving Shards from a Stream</a> in the <i>Amazon Kinesis Data Streams Developer Guide</i>.</p> <p>There are no guarantees about the chronological order shards returned. To process shards in chronological order, use the ID of the parent shard to track the lineage to the oldest shard.</p> <p>This operation has a limit of 10 transactions per second per account.</p>
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DescribeStreamOutput'
        '480':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '481':
          description: LimitExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
        '482':
          description: InvalidArgumentException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgumentException'
        '483':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DescribeStreamInput'
      parameters:
      - name: Limit
        in: query
        schema:
          type: string
        description: Pagination limit
        required: false
      - name: ExclusiveStartShardId
        in: query
        schema:
          type: string
        description: Pagination token
        required: false
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - Kinesis_20131202.DescribeStream
      tags:
      - '#X Amz Target=Kinesis 20131202.DescribeStream'
components:
  schemas:
    ResourceNotFoundException: {}
    ShardId:
      type: string
      pattern: '[a-zA-Z0-9_.-]+'
      minLength: 1
      maxLength: 128
    MetricsName:
      type: string
      enum:
      - IncomingBytes
      - IncomingRecords
      - OutgoingBytes
      - OutgoingRecords
      - WriteProvisionedThroughputExceeded
      - ReadProvisionedThroughputExceeded
      - IteratorAgeMilliseconds
      - ALL
    EnhancedMonitoringList:
      type: array
      items:
        $ref: '#/components/schemas/EnhancedMetrics'
    SequenceNumberRange:
      type: object
      required:
      - StartingSequenceNumber
      properties:
        StartingSequenceNumber:
          allOf:
          - $ref: '#/components/schemas/SequenceNumber'
          - description: The starting sequence number for the range.
        EndingSequenceNumber:
          allOf:
          - $ref: '#/components/schemas/SequenceNumber'
          - description: The ending sequence number for the range. Shards that are in the OPEN state have an ending sequence number of <code>null</code>.
      description: The range of possible sequence numbers for the shard.
    DescribeStreamOutput:
      type: object
      required:
      - StreamDescription
      properties:
        StreamDescription:
          allOf:
          - $ref: '#/components/schemas/StreamDescription'
          - description: The current status of the stream, the stream Amazon Resource Name (ARN), an array of shard objects that comprise the stream, and whether there are more shards available.
      description: Represents the output for <code>DescribeStream</code>.
    MetricsNameList:
      type: array
      items:
        $ref: '#/components/schemas/MetricsName'
      minItems: 1
      maxItems: 7
    KeyId:
      type: string
      minLength: 1
      maxLength: 2048
    StreamName:
      type: string
      pattern: '[a-zA-Z0-9_.-]+'
      minLength: 1
      maxLength: 128
    RetentionPeriodHours:
      type: integer
    DescribeStreamInput:
      type: object
      title: DescribeStreamInput
      properties:
        StreamName:
          allOf:
          - $ref: '#/components/schemas/StreamName'
          - description: The name of the stream to describe.
        Limit:
          allOf:
          - $ref: '#/components/schemas/DescribeStreamInputLimit'
          - description: The maximum number of shards to return in a single call. The default value is 100. If you specify a value greater than 100, at most 100 results are returned.
        ExclusiveStartShardId:
          allOf:
          - $ref: '#/components/schemas/ShardId'
          - description: <p>The shard ID of the shard to start with.</p> <p>Specify this parameter to indicate that you want to describe the stream starting with the shard whose ID immediately follows <code>ExclusiveStartShardId</code>.</p> <p>If you don't specify this parameter, the default behavior for <code>DescribeStream</code> is to describe the stream starting with the first shard in the stream.</p>
        StreamARN:
          allOf:
          - $ref: '#/components/schemas/StreamARN'
          - description: The ARN of the stream.
      description: Represents the input for <code>DescribeStream</code>.
    AccessDeniedException: {}
    DescribeStreamInputLimit:
      type: integer
      minimum: 1
      maximum: 10000
    StreamStatus:
      type: string
      enum:
      - CREATING
      - DELETING
      - ACTIVE
      - UPDATING
    InvalidArgumentException: {}
    StreamModeDetails:
      type: object
      required:
      - StreamMode
      properties:
        StreamMode:
          allOf:
          - $ref: '#/components/schemas/StreamMode'
          - description: ' Specifies the capacity mode to which you want to set your data stream. Currently, in Kinesis Data Streams, you can choose between an <b>on-demand</b> capacity mode and a <b>provisioned</b> capacity mode for your data streams. '
      description: ' Specifies the capacity mode to which you want to set your data stream. Currently, in Kinesis Data Streams, you can choose between an <b>on-demand</b> capacity mode and a <b>provisioned</b> capacity mode for your data streams. '
    LimitExceededException: {}
    Timestamp:
      type: string
      format: date-time
    StreamMode:
      type: string
      enum:
      - PROVISIONED
      - ON_DEMAND
    Shard:
      type: object
      required:
      - ShardId
      - HashKeyRange
      - SequenceNumberRange
      properties:
        ShardId:
          allOf:
          - $ref: '#/components/schemas/ShardId'
          - description: The unique identifier of the shard within the stream.
        ParentShardId:
          allOf:
          - $ref: '#/components/schemas/ShardId'
          - description: The shard ID of the shard's parent.
        AdjacentParentShardId:
          allOf:
          - $ref: '#/components/schemas/ShardId'
          - description: The shard ID of the shard adjacent to the shard's parent.
        HashKeyRange:
          allOf:
          - $ref: '#/components/schemas/HashKeyRange'
          - description: The range of possible hash key values for the shard, which is a set of ordered contiguous positive integers.
        SequenceNumberRange:
          allOf:
          - $ref: '#/components/schemas/SequenceNumberRange'
          - description: The range of possible sequence numbers for the shard.
      description: A uniquely identified group of data records in a Kinesis data stream.
    HashKeyRange:
      type: object
      required:
      - StartingHashKey
      - EndingHashKey
      properties:
        StartingHashKey:
          allOf:
          - $ref: '#/components/schemas/HashKey'
          - description: The starting hash key of the hash key range.
        EndingHashKey:
          allOf:
          - $ref: '#/components/schemas/HashKey'
          - description: The ending hash key of the hash key range.
      description: The range of possible hash key values for the shard, which is a set of ordered contiguous positive integers.
    StreamDescription:
      type: object
      required:
      - StreamName
      - StreamARN
      - StreamStatus
      - Shards
      - HasMoreShards
      - RetentionPeriodHours
      - StreamCreationTimestamp
      - EnhancedMonitoring
      properties:
        StreamName:
          allOf:
          - $ref: '#/components/schemas/StreamName'
          - description: The name of the stream being described.
        StreamARN:
          allOf:
          - $ref: '#/components/schemas/StreamARN'
          - description: The Amazon Resource Name (ARN) for the stream being described.
        StreamStatus:
          allOf:
          - $ref: '#/components/schemas/StreamStatus'
          - description: <p>The current status of the stream being described. The stream status is one of the following states:</p> <ul> <li> <p> <code>CREATING</code> - The stream is being created. Kinesis Data Streams immediately returns and sets <code>StreamStatus</code> to <code>CREATING</code>.</p> </li> <li> <p> <code>DELETING</code> - The stream is being deleted. The specified stream is in the <code>DELETING</code> state until Kinesis Data Streams completes the deletion.</p> </li> <li> <p> <code>ACTIVE</code> - The stream exists and is ready for read and write operations or deletion. You should perform read and write operations only on an <code>ACTIVE</code> stream.</p> </li> <li> <p> <code>UPDATING</code> - Shards in the stream are being merged or split. Read and write operations continue to work while the stream is in the <code>UPDATING</code> state.</p> </li> </ul>
        StreamModeDetails:
          allOf:
          - $ref: '#/components/schemas/StreamModeDetails'
          - description: ' Specifies the capacity mode to which you want to set your data stream. Currently, in Kinesis Data Streams, you can choose between an <b>on-demand</b> capacity mode and a <b>provisioned</b> capacity mode for your data streams. '
        Shards:
          allOf:
          - $ref: '#/components/schemas/ShardList'
          - description: The shards that comprise the stream.
        HasMoreShards:
          allOf:
          - $ref: '#/components/schemas/BooleanObject'
          - description: If set to <code>true</code>, more shards in the stream are available to describe.
        RetentionPeriodHours:
          allOf:
          - $ref: '#/components/schemas/RetentionPeriodHours'
          - description: The current retention period, in hours. Minimum value of 24. Maximum value of 168.
        StreamCreationTimestamp:
          allOf:
          - $ref: '#/components/schemas/Timestamp'
          - description: The approximate time that the stream was created.
        EnhancedMonitoring:
          allOf:
          - $ref: '#/components/schemas/EnhancedMonitoringList'
          - description: Represents the current enhanced monitoring settings of the stream.
        EncryptionType:
          allOf:
          - $ref: '#/components/schemas/EncryptionType'
          - description: '<p>The server-side encryption type used on the stream. This parameter can be one of the following values:</p> <ul> <li> <p> <code>NONE</code>: Do not encrypt the records in the stream.</p> </li> <li> <p> <code>KMS</code>: Use server-side encryption on the records in the stream using a customer-managed Amazon Web Services KMS key.</p> </li> </ul>'
        KeyId:
          allOf:
          - $ref: '#/components/schemas/KeyId'
          - description: '<p>The GUID for the customer-managed Amazon Web Services KMS key to use for encryption. This value can be a globally unique identifier, a fully specified ARN to either an alias or a key, or an alias name prefixed by "alias/".You can also use a master key owned by Kinesis Data Streams by specifying the alias <code>aws/kinesis</code>.</p> <ul> <li> <p>Key ARN example: <code>arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012</code> </p> </li> <li> <p>Alias ARN example: <code>arn:aws:kms:us-east-1:123456789012:alias/MyAliasName</code> </p> </li> <li> <p>Globally unique key ID example: <code>12345678-1234-1234-1234-123456789012</code> </p> </li> <li> <p>Alias name example: <code>alias/MyAliasName</code> </p> </li> <li> <p>Master key owned by Kinesis Data Streams: <code>alias/aws/kinesis</code> </p> </li> </ul>'
      description: Represents the output for <a>DescribeStream</a>.
    ShardList:
      type: array
      items:
        $ref: '#/components/schemas/Shard'
    EncryptionType:
      type: string
      enum:
      - NONE
      - KMS
    StreamARN:
      type: string
      pattern: arn:aws.*:kinesis:.*:\d{12}:stream/\S+
      minLength: 1
      maxLength: 2048
    EnhancedMetrics:
      type: object
      properties:
        ShardLevelMetrics:
          allOf:
          - $ref: '#/components/schemas/MetricsNameList'
          - description: <p>List of shard-level metrics.</p> <p>The following are the valid shard-level metrics. The value "<code>ALL</code>" enhances every metric.</p> <ul> <li> <p> <code>IncomingBytes</code> </p> </li> <li> <p> <code>IncomingRecords</code> </p> </li> <li> <p> <code>OutgoingBytes</code> </p> </li> <li> <p> <code>OutgoingRecords</code> </p> </li> <li> <p> <code>WriteProvisionedThroughputExceeded</code> </p> </li> <li> <p> <code>ReadProvisionedThroughputExceeded</code> </p> </li> <li> <p> <code>IteratorAgeMilliseconds</code> </p> </li> <li> <p> <code>ALL</code> </p> </li> </ul> <p>For more information, see <a href="https://docs.aws.amazon.com/kinesis/latest/dev/monitoring-with-cloudwatch.html">Monitoring the Amazon Kinesis Data Streams Service with Amazon CloudWatch</a> in the <i>Amazon Kinesis Data Streams Developer Guide</i>.</p>
      description: Represents enhanced metrics types.
    SequenceNumber:
      type: string
      pattern: 0|([1-9]\d{0,128})
    BooleanObject:
      type: boolean
    HashKey:
      type: string
      pattern: 0|([1-9]\d{0,38})
  parameters:
    X-Amz-Security-Token:
      name: X-Amz-Security-Token
      in: header
      schema:
        type: string
      required: false
    X-Amz-SignedHeaders:
      name: X-Amz-SignedHeaders
      in: header
      schema:
        type: string
      required: false
    X-Amz-Credential:
      name: X-Amz-Credential
      in: header
      schema:
        type: string
      required: false
    X-Amz-Date:
      name: X-Amz-Date
      in: header
      schema:
        type: string
      required: false
    X-Amz-Algorithm:
      name: X-Amz-Algorithm
      in: header
      schema:
        type: string
      required: false
    X-Amz-Signature:
      name: X-Amz-Signature
      in: header
      schema:
        type: string
      required: false
    X-Amz-Content-Sha256:
      name: X-Amz-Content-Sha256
      in: header
      schema:
        type: string
      required: false
  securitySchemes:
    hmac:
      type: apiKey
      name: Authorization
      in: header
      description: Amazon Signature authorization v4
      x-amazon-apigateway-authtype: awsSigv4
externalDocs:
  description: Amazon Web Services documentation
  url: https://docs.aws.amazon.com/kinesis/
x-hasEquivalentPaths: true