Swagger OpenAPI spec for Confluent REST Proxy

rest_proxy.yaml

openapi: 3.0.1
info:
  title: REST Proxy API
  description: >-
    The Confluent REST Proxy provides a RESTful interface to a Kafka cluster, making it easy to produce and consume messages, view the state of the cluster, and perform administrative actions without using the native Kafka protocol or clients.
    <p>Some example use cases are</p>
    <ul>
    <li>Reporting data to Kafka from any frontend app built in any language not supported by official Confluent clients</li>
    <li>Ingesting messages into a stream processing framework that doesn’t yet support Kafka</li>
    <li>Scripting administrative actions</li>
    </ul>
  version: 5.2.1
externalDocs:
  description: Confluent's API Reference
  url: https://docs.confluent.io/current/kafka-rest/
paths:
  /topics:
    get:
      responses:
        200:
          description: successful operation
          content:
            application/vnd.kafka.v2+json:
              schema:
                type: array
                items:
                  type: string
            application/vnd.kafka.v2+xml:
              schema:
                type: array
                items:
                  type: string
  /topics/{topicName}:
    get:
      parameters:
      - name: topicName
        in: path
        description: topic name
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/vnd.kafka.v2+json:
              schema:
                $ref: '#/components/schemas/topic'
            application/vnd.kafka.v2+xml:
              schema:
                $ref: '#/components/schemas/topic'
        404:
          description: Error code 40401 -- Topic not found
    post:
      description: post messages to a given topic
      parameters:
        - name: topicName
          in: path
          description: name of topic to produce the messages to
          required: true
          schema:
            type: string
      requestBody:
        description: message(s) to produce to the given topic
        required: true
        content:
          application/vnd.kafka.binary.v2+json:
            schema:
              $ref: '#/components/schemas/messages'
          application/vnd.kafka.avro.v2+json:
            schema:
              $ref: '#/components/schemas/messages'
          application/vnd.kafka.json.v2+json:
            schema:
              $ref: '#/components/schemas/messages'
      responses:
        200:
          description: message(s) posted
          content:
            application/vnd.kafka.v2+json:
              schema:
                $ref: '#/components/schemas/messages_response'
        404:
          description: 40401 -- Topic not found
        422:
          description: >-
            42201 -- Request includes keys and uses a format that requires schemas, but does not include the `key_schema` or `key_schema_id` fields<br>
            42202  -- Request includes values and uses a format that requires schemas, but does not include the `value_schema` or `value_schema_id` fields<br>
             42205 -- Request includes invalid schema.
  /topics/{topicName}/partitions:
    get:
      description: Get a list of partitions for the topic
      parameters:
      - name: topicName
        in: path
        description: the name of the topic
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful
          content:
            application/vnd.kafka.v2+json:
              schema:
                $ref: '#/components/schemas/partitions'
        404:
          description: topic not found
  /topics/{topicName}/partitions/{partitionID}:
    get:
      description: Get metadata about a single partition in the topic
      parameters:
      - name: topicName
        in: path
        description: Name of the topic
        required: true
        schema:
          type: string
      - name: partitionID
        in: path
        description: ID of the partition to inspect
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful
          content:
            application/vnd.kafka.v2+json:
              schema:
                $ref: '#/components/schemas/partitions'
    post:
      description: Produce messages to one partition of the topic
      parameters:
        - name: topicName
          in: path
          description: name of topic to produce the messages to
          required: true
          schema:
            type: string
        - name: partitionID
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        description: message(s) to produce to the given topic
        required: true
        content:
          application/vnd.kafka.v2+json:
            schema:
              $ref: '#/components/schemas/messages'
      responses:
        200:
          description: message(s) posted
          content:
            application/vnd.kafka.v2+json:
              schema:
                $ref: '#/components/schemas/messages_response'
        404:
          description: >-
            40401 -- Topic not found<br>
            40402 -- Partition not found
        422:
          description: >-
            42201 -- Request includes keys and uses a format that requires schemas, but does not include the `key_schema` or `key_schema_id` fields<br>
            42202  -- Request includes values and uses a format that requires schemas, but does not include the `value_schema` or `value_schema_id` fields<br>
             42205 -- Request includes invalid schema.
  /consumers/{group_name}:
    description: Create a new consumer instance in the consumer group
    post:
      parameters:
        - name: group_name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/vnd.kafka.v2+json:
            schema:
              $ref: '#/components/schemas/consumer_group'
      responses:
        200:
          description: Consumer group created
          content:
            application/vnd.kafka.v2+json:
              schema:
                type: object
                properties:
                  instance_id:
                    type: string
                    description: Unique ID for the consumer instance in this group
                  base_uri:
                    type: string
                    description: Base URI used to construct URIs for subsequent requests against this consumer instance.  This will be of the form `http://hostname:port/consumers/consumer_group/instances/instance_id`
        409:
          description: Consumer instance with the specified name already exists
        422:
          description: Invalid consumer configuration
  /consumers/{group_name}/instances/{instance}:
    description: Delete the consumer instance
    delete:
      parameters:
        - name: group_name
          in: path
          required: true
          schema:
            type: string
          description: The name of the consumer group
        - name: instance
          in: path
          required: true
          schema:
            type: string
          description: The ID of the consumer instance
      responses:
        204:
          description: Success
        404:
          description: 40403 -- Consumer instance not found
  /consumers/{group_name}/instances/{instance}/offsets:
    post:
      description: Commit a list of offsets for the consumer.  When the post body is empty, it commits all the records that have been fetched by the consumer instance.
      parameters:
        - name: group_name
          in: path
          required: true
          schema:
            type: string
          description: The name of the consumer group
        - name: instance
          in: path
          required: true
          schema:
            type: string
          description: The ID of the consumer instance
      requestBody:
        description: The offsets to commit
        content:
          application/vnd.kafka.v2+json:
            schema:
              $ref: '#/components/schemas/offsets'
      responses:
        200:
          description: Success
        404:
          description: 40403 -- Consumer instance not found
    get:
      description: Get the latest committed offsets for the given partitions
      parameters:
        - name: group_name
          in: path
          required: true
          schema:
            type: string
          description: The name of the consumer group
        - name: instance
          in: path
          required: true
          schema:
            type: string
          description: The ID of the consumer instance
      requestBody:
        required: true
        content:
          application/vnd.kafka.v2+json:
            schema:
              $ref: '#/components/schemas/offsets_query'
      responses:
        200:
          description: Success
          content:
            application/vnd.kafka.v2+json:
              schema:
                $ref: '#/components/schemas/offsets_response'
        404:
          description: >-
            40402 -- Partition not found<br>
            40403 -- Consumer instance not found
  /consumers/{group_name}/instances/{instance}/subscription:
    post:
      description: Subscribe to the given list of topics or a topic pattern to get dynamically assigned partition.  If a prior subscription exists, it would be replaced by the latest subscription.
      parameters:
        - name: group_name
          in: path
          required: true
          schema:
            type: string
          description: The name of the consumer group
        - name: instance
          in: path
          required: true
          schema:
            type: string
          description: The ID of the consumer instance
      requestBody:
        required: true
        content:
          application/vnd.kafka.v2+json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/topic_subscription'
              - $ref: '#/components/schemas/topic_pattern_subscription'
              
      responses:
        404:
          description: 40403 -- Consumer instance not found
        409:
          description: 40903 -- Subscription to topics, partitions and pattern are mutually exclusive
        204:
          description: Success
    get:
      description: Get the current subscribed list of topics
      parameters:
        - name: group_name
          in: path
          required: true
          schema:
            type: string
          description: The name of the consumer group
        - name: instance
          in: path
          required: true
          schema:
            type: string
          description: The ID of the consumer instance
      responses:
        404:
          description: 40403 -- Consumer instance not found
        200:
          description: Success
          content:
             application/vnd.kafka.v2+json:
               schema:
                 oneOf:
                 - $ref: '#/components/schemas/topic_subscription'
                 - $ref: '#/components/schemas/topic_pattern_subscription'
    delete:
      description: Unsubscribe from the topics currently subscribed
      parameters:
        - name: group_name
          in: path
          required: true
          schema:
            type: string
          description: The name of the consumer group
        - name: instance
          in: path
          required: true
          schema:
            type: string
          description: The ID of the consumer instance
      responses:
        204:
          description: success
        404:
          description: 40403 -- Consumer instance not found
  /consumers/{group_name}/instances/{instance}/assignments:
    post:
      description: Manually assign a list of partitions to this consumer.
      parameters:
        - name: group_name
          in: path
          required: true
          schema:
            type: string
          description: The name of the consumer group
        - name: instance
          in: path
          required: true
          schema:
            type: string
          description: The ID of the consumer instance
      requestBody:
        required: true
        content:
          application/vnd.kafka.v2+json:
            schema:
              $ref: '#/components/schemas/assignment'
      responses:
        204:
          description: success
        404:
          description: 40403 -- Consumer instance not found
        409:
          description: 40903 -- Subscription to topics, partitions and pattern are mutually exclusive
    get:
      description: Get the list of partitions currently manually assigned to this consumer
      parameters:
        - name: group_name
          in: path
          required: true
          schema:
            type: string
          description: The name of the consumer group
        - name: instance
          in: path
          required: true
          schema:
            type: string
          description: The ID of the consumer instance
      responses:
        200:
          description: Success
          content:
            application/vnd.kafka.v2+json:
              schema:
                $ref: '#/components/schemas/assignment'
  /consumers/{group_name}/instances/{instance}/positions:
    post:
      description: Overrides the fetch offsets that the consumer will use for the next set of records to fetch
      parameters:
        - name: group_name
          in: path
          required: true
          schema:
            type: string
          description: The name of the consumer group
        - name: instance
          in: path
          required: true
          schema:
            type: string
          description: The ID of the consumer instance
      requestBody:
        content:
          application/vnd.kafka.v2+json:
            schema:
              type: object
              properties:
                offsets:
                  type: array
                  items:
                    type: object
                    properties:
                      topic:
                        type: string
                      partition:
                        type: integer
                        description: Partition ID
                      offset:
                        type: integer
      responses:
        204:
          description: success
        404:
          description: 40403 -- Consumer instance not found
  /consumers/{group_name}/instances/{instance}/beginning:
    post:
      description: Seek to the first offset for each of the given partitions
      parameters:
        - name: group_name
          in: path
          required: true
          schema:
            type: string
          description: The name of the consumer group
        - name: instance
          in: path
          required: true
          schema:
            type: string
          description: The ID of the consumer instance
      requestBody:
        required: true
        content:
          application/vnd.kafka.v2+json:
            schema:
              $ref: '#/components/schemas/partition_positions'
      responses:
        204:
          description: Success
        404:
          description: 40403 -- Consumer instance not found
  /consumers/{group_name}/instances/{instance}/end:
    post:
      description: Seek to the last offset for each of the given partitions
      parameters:
        - name: group_name
          in: path
          required: true
          schema:
            type: string
          description: The name of the consumer group
        - name: instance
          in: path
          required: true
          schema:
            type: string
          description: The ID of the consumer instance
      requestBody:
        required: true
        content:
          application/vnd.kafka.v2+json:
            schema:
              $ref: '#/components/schemas/partition_positions'
      responses:
        204:
          description: Success
        404:
          description: 40403 -- Consumer instance not found
  /consumers/{group_name}/instances/{instance}/records:
    get:
      description: Fetch data for the topics or partitions specified using one of the subscribe/assign APIs
      parameters:
        - name: group_name
          in: path
          required: true
          schema:
            type: string
          description: The name of the consumer group
        - name: instance
          in: path
          required: true
          schema:
            type: string
          description: The ID of the consumer instance
        - name: timeout
          in: query
          description: Maximum amount of milliseconds the REST proxy will spend fetching records
          schema:
            type: integer
        - name: max_bytes
          in: query
          description: The maximum number of bytes of unencoded keys and values that should be included in the response
          schema:
            type: integer
      responses:
        200:
          description: records back from Kafka
          content:
            application/vnd.kafka.binary.v2+json:
              schema:
                $ref: '#/components/schemas/records'
            application/vnd.kafka.avro.v2+json:
              schema:
                $ref: '#/components/schemas/records'
            application/vnd.kafka.json.v2+json:
              schema:
                $ref: '#/components/schemas/records'
        404:
          description: 40403 -- Consumer instance not found
        406:
          description: 40601 -- Consumer format does not match the embedded format requested by the `Accept` header
  /brokers:
    get:
      description: Get a list of brokers
      responses:
        200:
          description: A list of broker IDs
          content:
            application/vnd.kafka.v2+json:
              schema:
                type: object
                properties:
                  brokers:
                    type: array
                    items:
                      type: integer
components:
  schemas:
    topic:
      type: object
      properties:
        name:
          type: string
          description: Name of the topic
        configs:
          type: object
          description:  Per-topic configuration overrides
        partitions:
          type: array
          description:  List of partitions for this topic
          items:
            type: object
            properties:
              partition:
                type: integer
                description: the ID of this partition
              leader:
                type: integer
                description: the broker ID of the leader for this partition
              replicas:
                type: array
                items:
                  type: object
                  properties:
                    broker:
                      type: integer
                      description: broker ID of the replica
                    leader:
                      type: boolean
                      description: true if this replica is the leader for the partition
                    in_sync:
                      type: boolean
                      description: true if this replica is currently in sync with the leader
    messages:
      type: object
      properties:
        key_schema:
          type: string
          description: Full schema encoded as a string (e.g. JSON serioalized for Avro data)
        value_schema:
          type: string
          description: Full schema encoded as a string (e.g. JSON serioalized for Avro data)
        records:
          type: array
          description: a list of records to produce to the topic
          items:
            type: object
            properties:
              key:
                type: string
                description: The message key, formatted according to the embedded format, or null to omit a key (optional)
              value:
                type: string
                description: The message value, formatted according to the embedded format
              partion:
                type: integer
                description: Partition to store the message in (optional)
    messages_response:
      type: object
      properties:
        key_schema_id:
          type: integer
          description:  The ID for the schema used to produce keys, or null if keys were not used
        value_schema_id:
          type: integer
          description:  The ID for the schema used to produce keys, or null if keys were not used
        offsets:
          type: array
          description: List of partitions and offsets the messages were published to
          items:
            type: object
            properties:
              partition:
                type: integer
                description: Partition the message was published to, or null if publishing the message failed
              offset:
                type: integer
                description: Offset of the message, or null if publishing the message failed
              error_code:
                 type: integer
                 description: An error code classifying the reason the operation failed, or null if it succeeded
                 enum:
                 - 1
                 - 2
              error:
                type: string
                description: An error message describing why the operation failed, or null if it succeeded
    partitions:
      type: array
      items:
        $ref: '#/components/schemas/partition'
    partition:
      type: object
      properties:
          partition:
            type: integer
            description: ID of the partition
          leader:
            type: integer
            description: Broker ID of the leader for this partition
          replicas:
            type: array
            description: List of brokers acting as replicas for this partition
            items:
              type: object
              properties:
                broker:
                  type: integer
                  description: Broker ID of the replica
                leader:
                  type: boolean
                  description: true if this broker is the leader for the partition
                in_sync:
                  type: boolean
                  description: true if the replica is in sync with the leader
    consumer_group:
      type: object
      properties:
        name:
          type: string
          description: Name for the consumer instance, which will be used in URLs for the consumer
        format:
          type: string
          description: The format of consumed messages, which is used to convert messages into a JSON-compatible form.
          enum:
          - binary
          - avro
          - json
          default: binary
        auto.offset.reset:
          type: string
          description: sets the `auto.offset.reset` setting for the consumer
        auto.commit.enable:
          type: string
          description: sets the `auto.commit.enable` setting for the consumer
        fetch.min.bytes:
          type: string
          description: sets the `fetch.min.bytes` setting for this consumer specifically
        consumer.request.timeout.ms:
          type: string
          description: sets the `consumer.request.timeout.ms` setting for this consumer specifically
    offsets:
      type: object
      properties:
        offsets:
          type: array
          items:
            type: object
            properties:
              topic:
                type: string
                description: Name of the topic
              partition:
                type: integer
                description: Partition ID
              offset:
                type: integer
                description: The offset to commit
    offsets_query:
      type: object
      properties:
        partitions:
          type: array
          description: A list of partitions to find the last committed offsets for
          items:
            type: object
            properties:
              topic:
                type: string
                description: Name of the topic
              partition:
                type: integer
                description: Partition ID
    offsets_response:
      type: object
      properties:
        offsets:
          type: array
          items:
            type: object
            properties:
              topic:
                type: string
                description: Name of the topic
              partition:
                type: integer
                description: Partition ID
              offset:
                type: integer
                description: Committed offset
              metadata:
                type: string
                description: Metadata for the committed offset
    topic_subscription:
      type: object
      properties:
        topics:
          type: array
          description: A list of topics to subscribe
          items:
            type: string
            description: Name of the topic
    topic_pattern_subscription:
      type: object
      properties:
        topic_pattern:
          type: string
          description: A pattern of topics to subscribe to
    assignment:
      type: object
      properties:
        partitions:
          type: array
          items:
            type: object
            properties:
              topic:
                type: string
                description: Name of the topic
              partition:
                type: integer
                description: Partition ID
    partition_positions:
      type: object
      properties:
        partitions:
          type: array
          description: A list of partitions
          items:
            type: object
            properties:
              topic:
                type: string
              partition:
                type: integer
                description: Partition ID
    records:
      type: array
      items:
        type: object
        properties:
          topic:
            type: string
            description: The topic
          key:
            type: string
          value:
            type: string
          partition:
            type: integer
            description: Partition of the message
          offset:
            type: integer
            description: Offset of the message

hey Alice, thanks for posting this useful gist. Is there a possibility to connect via email to get some help on setting this up & getting it to work?