{ "openapi": "3.1.0", "info": { "title": "HTTP Bridge API Reference", "description": "The HTTP Bridge provides a REST API for integrating HTTP based client applications with a Kafka cluster. You can use the API to create and manage consumers and send and receive records over HTTP rather than the native Kafka protocol.", "version": "0.1.0" }, "paths": { "/consumers/{groupid}": { "post": { "tags": [ "Consumers" ], "description": "Creates a consumer instance in the given consumer group. You can optionally specify a consumer name and supported configuration options. It returns a base URI which must be used to construct URLs for subsequent requests against this consumer instance.", "operationId": "createConsumer", "requestBody": { "description": "Name and configuration of the consumer. The name is unique within the scope of the consumer group. If a name is not specified, a randomly generated name is assigned. All parameters are optional. The supported configuration options are shown in the following example.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Consumer" } } }, "required": false }, "responses": { "200": { "description": "Consumer created successfully.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/CreatedConsumer" }, "examples": { "response": { "value": { "instance_id": "consumer1", "base_uri": "http://localhost:8080/consumers/my-group/instances/consumer1" } } } } } }, "409": { "description": "A consumer instance with the specified name already exists in the HTTP Bridge.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 409, "message": "A consumer instance with the specified name already exists in the HTTP Bridge." } } } } } }, "422": { "description": "One or more consumer configuration options have invalid values.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 422, "message": "One or more consumer configuration options have invalid values." } } } } } } } }, "parameters": [ { "name": "groupid", "in": "path", "description": "ID of the consumer group in which to create the consumer.", "required": true, "schema": { "type": "string" } } ] }, "/consumers/{groupid}/instances/{name}/positions/beginning": { "post": { "tags": [ "Seek", "Consumers" ], "description": "Configures a subscribed consumer to seek (and subsequently read from) the first offset in one or more given topic partitions.", "operationId": "seekToBeginning", "requestBody": { "description": "List of topic partitions to which the consumer is subscribed. The consumer will seek the first offset in the specified partitions.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Partitions" } } }, "required": true }, "responses": { "204": { "description": "Seek to the beginning performed successfully." }, "404": { "description": "The specified consumer instance was not found, or the specified consumer instance did not have one of the specified partitions assigned.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified consumer instance was not found." } } } } } } } }, "parameters": [ { "name": "groupid", "in": "path", "description": "ID of the consumer group to which the subscribed consumer belongs.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Name of the subscribed consumer.", "required": true, "schema": { "type": "string" } } ] }, "/consumers/{groupid}/instances/{name}/positions/end": { "post": { "tags": [ "Seek", "Consumers" ], "description": "Configures a subscribed consumer to seek (and subsequently read from) the offset at the end of one or more of the given topic partitions.", "operationId": "seekToEnd", "requestBody": { "description": "List of topic partitions to which the consumer is subscribed. The consumer will seek the last offset in the specified partitions.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Partitions" } } }, "required": true }, "responses": { "204": { "description": "Seek to the end performed successfully." }, "404": { "description": "The specified consumer instance was not found, or the specified consumer instance did not have one of the specified partitions assigned.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified consumer instance was not found." } } } } } } } }, "parameters": [ { "name": "groupid", "in": "path", "description": "ID of the consumer group to which the subscribed consumer belongs.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Name of the subscribed consumer.", "required": true, "schema": { "type": "string" } } ] }, "/consumers/{groupid}/instances/{name}/subscription": { "get": { "tags": [ "Consumers" ], "responses": { "200": { "description": "List of subscribed topics and partitions.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/SubscribedTopicList" } } } }, "404": { "description": "The specified consumer instance was not found.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified consumer instance was not found." } } } } } } }, "operationId": "listSubscriptions", "description": "Retrieves a list of the topics to which the consumer is subscribed.", "parameters": [ { "name": "groupid", "in": "path", "description": "ID of the consumer group to which the subscribed consumer belongs.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Name of the subscribed consumer.", "required": true, "schema": { "type": "string" } } ] }, "post": { "tags": [ "Consumers" ], "description": "Subscribes a consumer to one or more topics. You can describe the topics to which the consumer will subscribe in a list (of `Topics` type) or as a `topic_pattern` field. Each call replaces the subscriptions for the subscriber.", "operationId": "subscribe", "requestBody": { "description": "List of topics to which the consumer will subscribe.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Topics" } } }, "required": true }, "responses": { "204": { "description": "Consumer subscribed successfully." }, "404": { "description": "The specified consumer instance was not found.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified consumer instance was not found." } } } } } }, "409": { "description": "Subscriptions to topics, partitions, and patterns are mutually exclusive.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 409, "message": "Subscriptions to topics, partitions, and patterns are mutually exclusive." } } } } } }, "422": { "description": "A list (of `Topics` type) or a `topic_pattern` must be specified.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 422, "message": "A list (of Topics type) or a topic_pattern must be specified." } } } } } } }, "parameters": [ { "name": "groupid", "in": "path", "description": "ID of the consumer group to which the subscribed consumer belongs.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Name of the consumer to subscribe to topics.", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Consumers" ], "description": "Unsubscribes a consumer from all topics.", "operationId": "unsubscribe", "responses": { "204": { "description": "Consumer unsubscribed successfully." }, "404": { "description": "The specified consumer instance was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified consumer instance was not found." } } } } } } }, "parameters": [ { "name": "groupid", "in": "path", "description": "ID of the consumer group to which the subscribed consumer belongs.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Name of the consumer to unsubscribe from topics.", "required": true, "schema": { "type": "string" } } ] } }, "/consumers/{groupid}/instances/{name}/positions": { "post": { "tags": [ "Seek", "Consumers" ], "description": "Configures a subscribed consumer to fetch offsets from a particular offset the next time it fetches a set of records from a given topic partition. This overrides the default fetch behavior for consumers. You can specify one or more topic partitions.", "operationId": "seek", "requestBody": { "description": "List of partition offsets from which the subscribed consumer will next fetch records.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/OffsetCommitSeekList" } } }, "required": true }, "responses": { "204": { "description": "Seek performed successfully." }, "404": { "description": "The specified consumer instance was not found, or the specified consumer instance did not have one of the specified partitions assigned.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified consumer instance was not found." } } } } } } } }, "parameters": [ { "name": "groupid", "in": "path", "description": "ID of the consumer group to which the consumer belongs.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Name of the subscribed consumer.", "required": true, "schema": { "type": "string" } } ] }, "/consumers/{groupid}/instances/{name}/assignments": { "post": { "tags": [ "Consumers" ], "description": "Assigns one or more topic partitions to a consumer.", "operationId": "assign", "requestBody": { "description": "List of topic partitions to assign to the consumer.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Partitions" } } }, "required": true }, "responses": { "204": { "description": "Partitions assigned successfully." }, "404": { "description": "The specified consumer instance was not found.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified consumer instance was not found." } } } } } }, "409": { "description": "Subscriptions to topics, partitions, and patterns are mutually exclusive.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 409, "message": "Subscriptions to topics, partitions, and patterns are mutually exclusive." } } } } } } } }, "parameters": [ { "name": "groupid", "in": "path", "description": "ID of the consumer group to which the consumer belongs.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Name of the consumer to assign topic partitions to.", "required": true, "schema": { "type": "string" } } ] }, "/topics": { "get": { "tags": [ "Topics" ], "description": "Retrieves a list of all topics.", "operationId": "listTopics", "responses": { "200": { "description": "List of topics.", "content": { "application/vnd.kafka.v2+json": { "schema": { "type": "array", "items": { "type": "string" } } } } } } } }, "/topics/{topicname}": { "get": { "tags": [ "Topics" ], "description": "Retrieves the metadata about a given topic.", "operationId": "getTopic", "responses": { "200": { "description": "Topic metadata.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/TopicMetadata" } } } }, "404": { "description": "The specified topic was not found.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified topic was not found." } } } } } } } }, "post": { "tags": [ "Topics", "Producer" ], "description": "Sends one or more records to a given topic, optionally specifying a partition, key, or both.", "operationId": "send", "requestBody": { "content": { "application/vnd.kafka.json.v2+json": { "schema": { "$ref": "#/components/schemas/ProducerRecordList" } }, "application/vnd.kafka.binary.v2+json": { "schema": { "$ref": "#/components/schemas/ProducerRecordList" } }, "application/vnd.kafka.text.v2+json": { "schema": { "$ref": "#/components/schemas/ProducerRecordList" } } }, "required": true }, "parameters": [ { "name": "async", "in": "query", "description": "Ignore metadata as result of the sending operation, not returning them to the client. If not specified it is false, metadata returned.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Records sent successfully.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/OffsetRecordSentList" }, "examples": { "response": { "value": { "offsets": [ { "partition": 2, "offset": 0 }, { "partition": 1, "offset": 1 }, { "partition": 2, "offset": 2 } ] } } } } } }, "404": { "description": "The specified topic was not found.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified topic was not found." } } } } } }, "422": { "description": "The record list is not valid.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 422, "message": "The record list contains invalid records." } } } } } } } }, "parameters": [ { "name": "topicname", "in": "path", "description": "Name of the topic to send records to or retrieve metadata from.", "required": true, "schema": { "type": "string" } } ] }, "/admin/topics": { "post": { "tags": [ "Topics" ], "description": "Creates a topic with given name, partitions count, and replication factor.", "operationId": "createTopic", "requestBody": { "description": "Creates a topic with given name, partitions count, and replication factor.", "content": { "application/vnd.kafka.json.v2+json": { "schema": { "$ref": "#/components/schemas/NewTopic" } } }, "required": true }, "responses": { "201": { "description": "Created." } } } }, "/consumers/{groupid}/instances/{name}/records": { "get": { "tags": [ "Consumers" ], "description": "Retrieves records for a subscribed consumer, including message values, topics, and partitions. The request for this operation MUST use the base URL (including the host and port) returned in the response from the `POST` request to `/consumers/{groupid}` that was used to create this consumer.", "operationId": "poll", "responses": { "200": { "description": "Poll request executed successfully.", "content": { "application/vnd.kafka.json.v2+json": { "schema": { "$ref": "#/components/schemas/ConsumerRecordList" }, "examples": { "response": { "value": [ { "topic": "topic", "key": "key1", "value": { "foo": "bar" }, "partition": 0, "offset": 2, "timestamp": 1591897790000 }, { "topic": "topic", "key": "key2", "value": [ "foo2", "bar2" ], "partition": 1, "offset": 3, "timestamp": 1591897790002 } ] } } }, "application/vnd.kafka.binary.v2+json": { "schema": { "$ref": "#/components/schemas/ConsumerRecordList" }, "examples": { "response": { "value": "[\n {\n \"topic\": \"test\",\n \"key\": \"a2V5\",\n \"value\": \"Y29uZmx1ZW50\",\n \"partition\": 1,\n \"offset\": 100,\n },\n {\n \"topic\": \"test\",\n \"key\": \"a2V5\",\n \"value\": \"a2Fma2E=\",\n \"partition\": 2,\n \"offset\": 101,\n }\n]" } } }, "application/vnd.kafka.text.v2+json": { "schema": { "$ref": "#/components/schemas/ConsumerRecordList" } }, "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/ConsumerRecordList" } } } }, "404": { "description": "The specified consumer instance was not found.", "content": { "application/vnd.kafka.json.v2+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.kafka.binary.v2+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.kafka.text.v2+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified consumer instance was not found." } } } } } }, "406": { "description": "The `format` used in the consumer creation request does not match the embedded format in the Accept header of this request or the bridge got a message from the topic which is not JSON encoded.", "content": { "application/vnd.kafka.json.v2+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.kafka.binary.v2+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.kafka.text.v2+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 406, "message": "The `format` used in the consumer creation request does not match the embedded format in the Accept header of this request." } } } } } }, "422": { "description": "Response exceeds the maximum number of bytes the consumer can receive.", "content": { "application/vnd.kafka.json.v2+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.kafka.binary.v2+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.kafka.text.v2+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 422, "message": "Response exceeds the maximum number of bytes the consumer can receive" } } } } } } } }, "parameters": [ { "name": "groupid", "in": "path", "description": "ID of the consumer group to which the subscribed consumer belongs.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Name of the subscribed consumer to retrieve records from.", "required": true, "schema": { "type": "string" } }, { "name": "timeout", "in": "query", "description": "The maximum amount of time, in milliseconds, that the HTTP Bridge spends retrieving records before timing out the request.", "required": false, "schema": { "type": "integer" } }, { "name": "max_bytes", "in": "query", "description": "The maximum size, in bytes, of unencoded keys and values that can be included in the response. Otherwise, an error response with code 422 is returned.", "required": false, "schema": { "type": "integer" } } ] }, "/topics/{topicname}/partitions": { "get": { "tags": [ "Topics" ], "description": "Retrieves a list of partitions for the topic.", "operationId": "listPartitions", "responses": { "200": { "description": "List of partitions.", "content": { "application/vnd.kafka.v2+json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PartitionMetadata" } } } } }, "404": { "description": "The specified topic was not found.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified topic was not found." } } } } } } } }, "parameters": [ { "name": "topicname", "in": "path", "description": "Name of the topic to send records to or retrieve metadata from.", "required": true, "schema": { "type": "string" } } ] }, "/topics/{topicname}/partitions/{partitionid}": { "get": { "tags": [ "Topics" ], "description": "Retrieves partition metadata for the topic partition.", "operationId": "getPartition", "responses": { "200": { "description": "Partition metadata.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/PartitionMetadata" } } } }, "404": { "description": "The specified partition was not found.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified partition was not found." } } } } } } } }, "post": { "tags": [ "Topics", "Producer" ], "description": "Sends one or more records to a given topic partition, optionally specifying a key.", "operationId": "sendToPartition", "requestBody": { "description": "List of records to send to a given topic partition, including a value (required) and a key (optional).", "content": { "application/vnd.kafka.json.v2+json": { "schema": { "$ref": "#/components/schemas/ProducerRecordToPartitionList" } }, "application/vnd.kafka.binary.v2+json": { "schema": { "$ref": "#/components/schemas/ProducerRecordToPartitionList" } }, "application/vnd.kafka.text.v2+json": { "schema": { "$ref": "#/components/schemas/ProducerRecordToPartitionList" } } }, "required": true }, "parameters": [ { "name": "async", "in": "query", "description": "Whether to return immediately upon sending records, instead of waiting for metadata. No offsets will be returned if specified. Defaults to false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Records sent successfully.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/OffsetRecordSentList" }, "examples": { "response": { "value": { "offsets": [ { "partition": 2, "offset": 0 }, { "partition": 1, "offset": 1 }, { "partition": 2, "offset": 2 } ] } } } } } }, "404": { "description": "The specified topic partition was not found.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified topic partition was not found." } } } } } }, "422": { "description": "The record is not valid.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 422, "message": "The record is not valid." } } } } } } } }, "parameters": [ { "name": "topicname", "in": "path", "description": "Name of the topic to send records to or retrieve metadata from.", "required": true, "schema": { "type": "string" } }, { "name": "partitionid", "in": "path", "description": "ID of the partition to send records to or retrieve metadata from.", "required": true, "schema": { "type": "integer", "minimum": 0 } } ] }, "/topics/{topicname}/partitions/{partitionid}/offsets": { "get": { "tags": [ "Topics" ], "description": "Retrieves a summary of the offsets for the topic partition.", "operationId": "getOffsets", "responses": { "200": { "description": "A summary of the offsets of the topic partition.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/OffsetsSummary" } } } }, "404": { "description": "The specified topic partition was not found.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified topic partition was not found." } } } } } } } }, "parameters": [ { "name": "topicname", "in": "path", "description": "Name of the topic containing the partition.", "required": true, "schema": { "type": "string" } }, { "name": "partitionid", "in": "path", "description": "ID of the partition.", "required": true, "schema": { "type": "integer", "minimum": 0 } } ] }, "/consumers/{groupid}/instances/{name}": { "delete": { "tags": [ "Consumers" ], "description": "Deletes a specified consumer instance. The request for this operation MUST use the base URL (including the host and port) returned in the response from the `POST` request to `/consumers/{groupid}` that was used to create this consumer.", "operationId": "deleteConsumer", "responses": { "204": { "description": "Consumer removed successfully." }, "404": { "description": "The specified consumer instance was not found.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified consumer instance was not found." } } } } } } } }, "parameters": [ { "name": "groupid", "in": "path", "description": "ID of the consumer group to which the consumer belongs.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Name of the consumer to delete.", "required": true, "schema": { "type": "string" } } ] }, "/consumers/{groupid}/instances/{name}/offsets": { "post": { "tags": [ "Consumers" ], "description": "Commits a list of consumer offsets. To commit offsets for all records fetched by the consumer, leave the request body empty.", "operationId": "commit", "requestBody": { "description": "List of consumer offsets to commit to the consumer offsets commit log. You can specify one or more topic partitions to commit offsets for.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/OffsetCommitSeekList" } } } }, "responses": { "204": { "description": "Commit made successfully." }, "404": { "description": "The specified consumer instance was not found.", "content": { "application/vnd.kafka.v2+json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "response": { "value": { "error_code": 404, "message": "The specified consumer instance was not found." } } } } } } } }, "parameters": [ { "name": "groupid", "in": "path", "description": "ID of the consumer group to which the consumer belongs.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Name of the consumer.", "required": true, "schema": { "type": "string" } } ] }, "/healthy": { "get": { "responses": { "200": { "description": "The bridge is healthy." }, "500": { "description": "The bridge is not healthy." } }, "operationId": "healthy", "description": "Check if the bridge is running. This does not necessarily imply that it is ready to accept requests." } }, "/ready": { "get": { "responses": { "200": { "description": "The bridge is ready." }, "500": { "description": "The bridge is not ready." } }, "operationId": "ready", "description": "Check if the bridge is ready and can accept requests." } }, "/openapi": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OpenAPI v3 specification in JSON format retrieved successfully." } }, "operationId": "openapi", "description": "Retrieves the OpenAPI v3 specification in JSON format." } }, "/openapi/v3": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OpenAPI v3 specification in JSON format retrieved successfully." } }, "operationId": "openapiv3", "description": "Retrieves the OpenAPI v3 specification in JSON format." } }, "/metrics": { "get": { "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Metrics in Prometheus format retrieved successfully." }, "404": { "description": "The metrics endpoint is not enabled." } }, "operationId": "metrics", "description": "Retrieves the bridge metrics in Prometheus format." } }, "/": { "get": { "responses": { "200": { "description": "Information about HTTP Bridge instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BridgeInfo" } } } } }, "operationId": "info", "description": "Retrieves information about the HTTP Bridge instance, in JSON format." } } }, "components": { "schemas": { "KafkaHeader": { "title": "KafkaHeader", "description": "A Kafka record header containing a key-value pair.", "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "description": "Header key name." }, "value": { "type": "string", "format": "byte", "description": "The header value in binary format, encoded as Base64." } }, "example": { "key": "key1", "value": "dmFsdWUx" } }, "KafkaHeaderList": { "title": "KafkaHeaderList", "description": "List of Kafka record headers.", "type": "array", "items": { "$ref": "#/components/schemas/KafkaHeader" }, "example": [ { "key": "key1", "value": "dmFsdWUx" }, { "key": "key2", "value": "dmFsdWUy" } ] }, "ConsumerRecord": { "title": "ConsumerRecord", "description": "A record consumed from a Kafka topic.", "type": "object", "properties": { "topic": { "type": "string", "description": "Topic name from which the record was consumed." }, "key": { "$ref": "#/components/schemas/RecordKey" }, "value": { "$ref": "#/components/schemas/RecordValue" }, "partition": { "type": "integer", "format": "int32", "description": "Partition number from which the record was consumed." }, "offset": { "type": "integer", "format": "int64", "description": "Offset of the record in the partition." }, "timestamp": { "type": "integer", "format": "int64", "description": "The record timestamp, in milliseconds since the Unix epoch." }, "headers": { "$ref": "#/components/schemas/KafkaHeaderList" } }, "example": { "key": "key1", "offset": 2, "partition": 0, "topic": "topic", "value": "value1", "timestamp": 1591897790000, "headers": [ { "key": "key1", "value": "dmFsdWUx" }, { "key": "key2", "value": "dmFsdWUy" } ] } }, "ConsumerRecordList": { "title": "ConsumerRecordList", "description": "List of records consumed from Kafka topics.", "type": "array", "items": { "$ref": "#/components/schemas/ConsumerRecord" }, "example": [ { "topic": "topic", "key": "key1", "value": "value1", "partition": 0, "offset": 2, "timestamp": 1591897790000 }, { "topic": "topic", "key": "key2", "value": "value2", "partition": 1, "offset": 3, "timestamp": 1591897790000 } ] }, "CreatedConsumer": { "title": "CreatedConsumer", "description": "Response containing details of a newly created consumer instance.", "type": "object", "properties": { "instance_id": { "type": "string", "description": "Unique ID for the consumer instance in the group." }, "base_uri": { "type": "string", "description": "Base URI used to construct URIs for subsequent requests against this consumer instance." } }, "example": { "instance_id": "my-consumer", "base_uri": "http://localhost:8080/consumers/my-group/instances/my-consumer" } }, "OffsetRecordSent": { "title": "OffsetRecordSent", "description": "Offset information for a successfully sent record.", "type": "object", "properties": { "partition": { "type": "integer", "format": "int32", "description": "Partition to which the record was sent." }, "offset": { "type": "integer", "format": "int64", "description": "Offset of the record in the partition." } }, "example": { "partition": 31, "offset": 86 } }, "OffsetRecordSentList": { "title": "OffsetRecordSentList", "description": "List of offset information for sent records, which might include errors for individual records.", "type": "object", "properties": { "offsets": { "type": "array", "description": "Array of offset information or errors for each record sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/OffsetRecordSent" }, { "$ref": "#/components/schemas/Error" } ] } } }, "example": { "offsets": [ { "partition": 92, "offset": 98 }, { "error_code": 404, "message": "Topic my-topic not present in metadata after 60000 ms." }, { "partition": 65, "offset": 91 } ] } }, "OffsetsSummary": { "title": "OffsetsSummary", "description": "Summary of offset positions for a topic partition.", "type": "object", "properties": { "beginning_offset": { "type": "integer", "format": "int64", "description": "Earliest available offset in the partition." }, "end_offset": { "type": "integer", "format": "int64", "description": "Latest offset in the partition (offset of the next message to be appended)." } }, "example": { "beginning_offset": 10, "end_offset": 50 } }, "Error": { "title": "Error", "description": "Error response returned by the HTTP Bridge.", "type": "object", "properties": { "error_code": { "type": "integer", "format": "int32", "description": "HTTP status code or Kafka error code." }, "message": { "type": "string", "description": "Detailed error message." }, "validation_errors": { "type": "array", "description": "List of validation errors (if applicable).", "items": { "type": "string" } } }, "example": { "error_code": 404, "message": "resource not found" } }, "Consumer": { "title": "Consumer", "type": "object", "properties": { "name": { "description": "The unique name for the consumer instance. The name is unique within the scope of the consumer group. The name is used in URLs. If a name is not specified, a randomly generated name is assigned.", "type": "string" }, "format": { "description": "The allowable message format for the consumer, which can be `binary` (default) or `json`. The messages are converted into a JSON format.", "type": "string" }, "auto.offset.reset": { "description": "Resets the offset position for the consumer. If set to `latest` (default), messages are read from the latest offset. If set to `earliest`, messages are read from the first offset.", "type": "string" }, "fetch.min.bytes": { "description": "Sets the minimum amount of data, in bytes, for the consumer to receive. The broker waits until the data to send exceeds this amount. Default is `1` byte.", "type": "integer" }, "consumer.request.timeout.ms": { "description": "Sets the maximum amount of time, in milliseconds, for the consumer to wait for messages for a request. If the timeout period is reached without a response, an error is returned. Default is `30000` (30 seconds).", "type": "integer" }, "enable.auto.commit": { "description": "If set to `true` (default), message offsets are committed automatically for the consumer. If set to `false`, message offsets must be committed manually.", "type": "boolean" }, "isolation.level": { "description": "If set to `read_uncommitted` (default), all transaction records are retrieved, indpendent of any transaction outcome. If set to `read_committed`, the records from committed transactions are retrieved.", "type": "string" } }, "additionalProperties": false, "example": { "name": "consumer1", "format": "binary", "auto.offset.reset": "earliest", "enable.auto.commit": false, "fetch.min.bytes": 512, "consumer.request.timeout.ms": 30000, "isolation.level": "read_committed" } }, "OffsetCommitSeek": { "title": "OffsetCommitSeek", "description": "Offset position for committing or seeking to a specific offset in a topic partition.", "type": "object", "required": [ "topic", "partition", "offset" ], "properties": { "topic": { "type": "string", "description": "Topic name." }, "partition": { "type": "integer", "format": "int32", "description": "Partition number." }, "offset": { "type": "integer", "format": "int64", "description": "Offset position in the partition." } }, "additionalProperties": false, "example": { "topic": "topic", "partition": 43, "offset": 92 } }, "OffsetCommitSeekList": { "title": "OffsetCommitSeekList", "description": "List of offset positions for committing or seeking across multiple topic partitions.", "type": "object", "properties": { "offsets": { "type": "array", "description": "Array of offset positions for topic partitions.", "items": { "$ref": "#/components/schemas/OffsetCommitSeek" } } }, "additionalProperties": false, "example": { "offsets": [ { "topic": "topic", "partition": 0, "offset": 15 }, { "topic": "topic", "partition": 1, "offset": 42 } ] } }, "Partition": { "title": "Partition", "description": "A topic partition identifier.", "type": "object", "properties": { "topic": { "type": "string", "description": "Topic name" }, "partition": { "type": "integer", "format": "int32", "description": "Partition number" } }, "additionalProperties": false }, "Partitions": { "title": "Partitions", "description": "List of topic partitions for assignment to a consumer.", "type": "object", "properties": { "partitions": { "type": "array", "description": "Array of topic partition identifiers.", "items": { "$ref": "#/components/schemas/Partition" } } }, "additionalProperties": false, "example": { "partitions": [ { "topic": "topic", "partition": 0 }, { "topic": "topic", "partition": 1 } ] } }, "ProducerRecord": { "title": "ProducerRecord", "description": "A record to be sent to a Kafka topic.", "type": "object", "required": [ "value" ], "properties": { "value": { "$ref": "#/components/schemas/RecordValue" }, "key": { "$ref": "#/components/schemas/RecordKey" }, "partition": { "type": "integer", "format": "int32", "description": "The target partition for the record. If not specified, the partitioner determines the partition." }, "timestamp": { "type": "integer", "format": "int64", "description": "The record timestamp, in milliseconds since the Unix epoch. If not specified, the current time is used." }, "headers": { "$ref": "#/components/schemas/KafkaHeaderList" } }, "additionalProperties": false, "example": { "key": "key1", "partition": 0, "timestamp": 1591897790000, "value": "value1", "headers": [ { "key": "key1", "value": "dmFsdWUx" }, { "key": "key2", "value": "dmFsdWUy" } ] } }, "ProducerRecordList": { "title": "ProducerRecordList", "description": "List of records to be sent to a Kafka topic.", "type": "object", "properties": { "records": { "type": "array", "description": "Array of records to send.", "items": { "$ref": "#/components/schemas/ProducerRecord" } } }, "additionalProperties": false, "example": { "records": [ { "key": "key1", "value": "value1" }, { "value": "value2", "partition": 1 }, { "value": "value3" } ] } }, "ProducerRecordToPartition": { "title": "ProducerRecordToPartition", "description": "A record to be sent to a specific Kafka topic partition.", "type": "object", "required": [ "value" ], "properties": { "value": { "$ref": "#/components/schemas/RecordValue" }, "key": { "$ref": "#/components/schemas/RecordKey" }, "headers": { "$ref": "#/components/schemas/KafkaHeaderList" } }, "additionalProperties": false, "example": { "value": { "v": 128 }, "key": { "k": "key" } } }, "ProducerRecordToPartitionList": { "title": "ProducerRecordToPartitionList", "description": "List of records to be sent to a specific Kafka topic partition.", "type": "object", "properties": { "records": { "type": "array", "description": "Array of records to send to the partition.", "items": { "$ref": "#/components/schemas/ProducerRecordToPartition" } } }, "additionalProperties": false, "example": { "records": [ { "key": "key1", "value": "value1" }, { "value": "value2" } ] } }, "Topics": { "title": "Topics", "description": "Topic subscription specification using either a list of topic names or a regex pattern.", "type": "object", "properties": { "topics": { "type": "array", "description": "List of topic names to subscribe to.", "items": { "type": "string" } }, "topic_pattern": { "type": "string", "description": "A regex topic pattern for matching multiple topics." } }, "additionalProperties": false, "example": { "topics": [ "topic1", "topic2" ] } }, "AssignedTopicPartitions": { "title": "AssignedTopicPartitions", "description": "Map of topic names to their assigned partition numbers.", "type": "object", "additionalProperties": { "type": "array", "description": "Array of partition numbers for the topic.", "items": { "type": "integer", "format": "int32" } }, "example": { "my-topic1": [ 1, 2, 3 ] } }, "SubscribedTopicList": { "title": "SubscribedTopicList", "description": "List of topics and partitions to which a consumer is subscribed or assigned.", "type": "object", "properties": { "topics": { "$ref": "#/components/schemas/Topics" }, "partitions": { "type": "array", "description": "List of assigned topic partitions.", "items": { "$ref": "#/components/schemas/AssignedTopicPartitions" } } }, "example": { "topics": [ "my-topic1", "my-topic2" ], "partitions": [ { "my-topic1": [ 1, 2, 3 ] }, { "my-topic2": [ 1 ] } ] } }, "TopicMetadata": { "title": "TopicMetadata", "description": "Metadata information about a Kafka topic.", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the topic." }, "configs": { "type": "object", "description": "Per-topic configuration overrides.", "additionalProperties": { "type": "string" } }, "partitions": { "type": "array", "description": "List of partition metadata for the topic.", "items": { "$ref": "#/components/schemas/PartitionMetadata" } } }, "additionalProperties": false, "example": { "name": "topic", "offset": 2, "configs": { "cleanup.policy": "compact" }, "partitions": [ { "partition": 1, "leader": 1, "replicas": [ { "broker": 1, "leader": true, "in_sync": true }, { "broker": 2, "leader": false, "in_sync": true } ] }, { "partition": 2, "leader": 2, "replicas": [ { "broker": 1, "leader": false, "in_sync": true }, { "broker": 2, "leader": true, "in_sync": true } ] } ] } }, "PartitionMetadata": { "title": "PartitionMetadata", "description": "Metadata information about a topic partition.", "type": "object", "properties": { "partition": { "type": "integer", "format": "int32", "description": "Partition number" }, "leader": { "type": "integer", "format": "int32", "description": "Broker ID of the partition leader." }, "replicas": { "type": "array", "description": "List of replica information for the partition.", "items": { "$ref": "#/components/schemas/Replica" } } }, "additionalProperties": false, "example": { "partition": 1, "leader": 1, "replicas": [ { "broker": 1, "leader": true, "in_sync": true }, { "broker": 2, "leader": false, "in_sync": true } ] } }, "Replica": { "title": "Replica", "description": "Information about a partition replica.", "type": "object", "properties": { "broker": { "type": "integer", "format": "int32", "description": "Broker ID hosting this replica." }, "leader": { "type": "boolean", "description": "Indicates whether the replica is the partition leader." }, "in_sync": { "type": "boolean", "description": "Indicates whether the replica is in-sync with the leader." } }, "additionalProperties": false, "example": { "broker": 1, "leader": true, "in_sync": true } }, "BridgeInfo": { "title": "BridgeInfo", "description": "Information about HTTP Bridge instance.", "type": "object", "properties": { "bridge_version": { "type": "string", "description": "Version of the Strimzi Kafka Bridge." } }, "example": { "bridge_version": "0.16.0" } }, "RecordKey": { "title": "RecordKey", "description": "Key representation for a record. It can be an array, a JSON object, or a string depending on the content type.", "oneOf": [ { "type": "array", "items": {}, "description": "Array representation of the key." }, { "type": "object", "description": "JSON object representation of the key." }, { "type": "string", "description": "String representation of the key (text or base64-encoded binary)." } ] }, "RecordValue": { "title": "RecordValue", "description": "Value representation for a record. It can be an array, a JSON object, a string, or null depending on the content type.", "oneOf": [ { "type": "array", "items": {}, "description": "Array representation of the value." }, { "type": "object", "description": "JSON object representation of the value." }, { "type": "string", "description": "String representation of the value (text or base64-encoded binary)." }, { "type": "null", "description": "Null value (tombstone record)." } ] }, "NewTopic": { "title": "NewTopic", "description": "Specification for creating a new Kafka topic.", "type": "object", "required": ["topic_name"], "properties": { "topic_name": { "type": "string", "description": "Name of the topic to create." }, "partitions_count": { "type": ["integer", "null"], "description": "The number of partitions for the topic. If not specified, the broker default is used." }, "replication_factor": { "type": ["integer", "null"], "description": "The number of replicas for each partition. If not specified, the broker default is used." } }, "additionalProperties": false, "example": { "topic_name": "my-topic", "partitions_count": 3, "replication_factor": 2 } } } }, "tags": [ { "name": "Consumers", "description": "Consumer operations to create consumers in your Kafka cluster and perform common actions, such as subscribing to topics, retrieving processed records, and committing offsets." }, { "name": "Topics", "description": "Topic operations to send messages to a specified topic or topic partition, optionally including message keys in requests. You can also retrieve topics and topic metadata." }, { "name": "Seek", "description": "Seek operations that enable a consumer to begin receiving messages from a given offset position." }, { "name": "Producer", "description": "Producer operations to send records to a specified topic or topic partition." } ] }