Paths

GET /

Description

Retrieves information about the Kafka Bridge instance, in JSON format.

Responses

HTTP Code	Description	Schema
200	Information about Kafka Bridge instance.	BridgeInfo

Produces

application/json

Example HTTP response

Response 200

{
  "bridge_version" : "0.16.0"
}

POST /consumers/{groupid}

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.

Parameters

Type	Name	Description	Schema
Path	groupid required	ID of the consumer group in which to create the consumer.	string
Body	body required	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.	Consumer

Responses

HTTP Code	Description	Schema
200	Consumer created successfully.	CreatedConsumer
409	A consumer instance with the specified name already exists in the Kafka Bridge.	Error
422	One or more consumer configuration options have invalid values.	Error

Consumes

application/vnd.kafka.v2+json

Produces

application/vnd.kafka.v2+json

Tags

Consumers

Example HTTP request

Request body

{
  "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"
}

Example HTTP response

Response 200

{
  "instance_id" : "consumer1",
  "base_uri" : "http://localhost:8080/consumers/my-group/instances/consumer1"
}

Response 409

{
  "error_code" : 409,
  "message" : "A consumer instance with the specified name already exists in the Kafka Bridge."
}

Response 422

{
  "error_code" : 422,
  "message" : "One or more consumer configuration options have invalid values."
}

DELETE /consumers/{groupid}/instances/{name}

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.

Parameters

Type	Name	Description	Schema
Path	groupid required	ID of the consumer group to which the consumer belongs.	string
Path	name required	Name of the consumer to delete.	string

Responses

HTTP Code	Description	Schema
204	Consumer removed successfully.	No Content
404	The specified consumer instance was not found.	Error

Consumes

application/vnd.kafka.v2+json

Produces

application/vnd.kafka.v2+json

Tags

Consumers

Example HTTP response

Response 404

{
  "error_code" : 404,
  "message" : "The specified consumer instance was not found."
}

POST /consumers/{groupid}/instances/{name}/assignments

Description

Assigns one or more topic partitions to a consumer.

Parameters

Type	Name	Description	Schema
Path	groupid required	ID of the consumer group to which the consumer belongs.	string
Path	name required	Name of the consumer to assign topic partitions to.	string
Body	body required	List of topic partitions to assign to the consumer.	Partitions

Responses

HTTP Code	Description	Schema
204	Partitions assigned successfully.	No Content
404	The specified consumer instance was not found.	Error
409	Subscriptions to topics, partitions, and patterns are mutually exclusive.	Error

Consumes

application/vnd.kafka.v2+json

Produces

application/vnd.kafka.v2+json

Tags

Consumers

Example HTTP request

Request body

{
  "partitions" : [ {
    "topic" : "topic",
    "partition" : 0
  }, {
    "topic" : "topic",
    "partition" : 1
  } ]
}

Example HTTP response

Response 404

{
  "error_code" : 404,
  "message" : "The specified consumer instance was not found."
}

Response 409

{
  "error_code" : 409,
  "message" : "Subscriptions to topics, partitions, and patterns are mutually exclusive."
}

POST /consumers/{groupid}/instances/{name}/offsets

Description

Commits a list of consumer offsets. To commit offsets for all records fetched by the consumer, leave the request body empty.

Parameters

Type	Name	Description	Schema
Path	groupid required	ID of the consumer group to which the consumer belongs.	string
Path	name required	Name of the consumer.	string
Body	body optional	List of consumer offsets to commit to the consumer offsets commit log. You can specify one or more topic partitions to commit offsets for.	OffsetCommitSeekList

Responses

HTTP Code	Description	Schema
204	Commit made successfully.	No Content
404	The specified consumer instance was not found.	Error

Consumes

application/vnd.kafka.v2+json

Produces

application/vnd.kafka.v2+json

Tags

Consumers

Example HTTP request

Request body

{
  "offsets" : [ {
    "topic" : "topic",
    "partition" : 0,
    "offset" : 15
  }, {
    "topic" : "topic",
    "partition" : 1,
    "offset" : 42
  } ]
}

Example HTTP response

Response 404

{
  "error_code" : 404,
  "message" : "The specified consumer instance was not found."
}

POST /consumers/{groupid}/instances/{name}/positions

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.

Parameters

Type	Name	Description	Schema
Path	groupid required	ID of the consumer group to which the consumer belongs.	string
Path	name required	Name of the subscribed consumer.	string
Body	body required	List of partition offsets from which the subscribed consumer will next fetch records.	OffsetCommitSeekList

Responses

HTTP Code	Description	Schema
204	Seek performed successfully.	No Content
404	The specified consumer instance was not found, or the specified consumer instance did not have one of the specified partitions assigned.	Error

Consumes

application/vnd.kafka.v2+json

Produces

application/vnd.kafka.v2+json

Tags

Consumers
Seek

Example HTTP request

Request body

{
  "offsets" : [ {
    "topic" : "topic",
    "partition" : 0,
    "offset" : 15
  }, {
    "topic" : "topic",
    "partition" : 1,
    "offset" : 42
  } ]
}

Example HTTP response

Response 404

{
  "error_code" : 404,
  "message" : "The specified consumer instance was not found."
}

POST /consumers/{groupid}/instances/{name}/positions/beginning

Description

Configures a subscribed consumer to seek (and subsequently read from) the first offset in one or more given topic partitions.

Parameters

Type	Name	Description	Schema
Path	groupid required	ID of the consumer group to which the subscribed consumer belongs.	string
Path	name required	Name of the subscribed consumer.	string
Body	body required	List of topic partitions to which the consumer is subscribed. The consumer will seek the first offset in the specified partitions.	Partitions

Responses

HTTP Code	Description	Schema
204	Seek to the beginning performed successfully.	No Content
404	The specified consumer instance was not found, or the specified consumer instance did not have one of the specified partitions assigned.	Error

Consumes

application/vnd.kafka.v2+json

Produces

application/vnd.kafka.v2+json

Tags

Consumers
Seek

Example HTTP request

Request body

{
  "partitions" : [ {
    "topic" : "topic",
    "partition" : 0
  }, {
    "topic" : "topic",
    "partition" : 1
  } ]
}

Example HTTP response

Response 404

{
  "error_code" : 404,
  "message" : "The specified consumer instance was not found."
}

POST /consumers/{groupid}/instances/{name}/positions/end

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.

Parameters

Type	Name	Description	Schema
Path	groupid required	ID of the consumer group to which the subscribed consumer belongs.	string
Path	name required	Name of the subscribed consumer.	string
Body	body optional	List of topic partitions to which the consumer is subscribed. The consumer will seek the last offset in the specified partitions.	Partitions

Responses

HTTP Code	Description	Schema
204	Seek to the end performed successfully.	No Content
404	The specified consumer instance was not found, or the specified consumer instance did not have one of the specified partitions assigned.	Error

Consumes

application/vnd.kafka.v2+json

Produces

application/vnd.kafka.v2+json

Tags

Consumers
Seek

Example HTTP request

Request body

{
  "partitions" : [ {
    "topic" : "topic",
    "partition" : 0
  }, {
    "topic" : "topic",
    "partition" : 1
  } ]
}

Example HTTP response

Response 404

{
  "error_code" : 404,
  "message" : "The specified consumer instance was not found."
}

GET /consumers/{groupid}/instances/{name}/records

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.

Parameters

Type	Name	Description	Schema
Path	groupid required	ID of the consumer group to which the subscribed consumer belongs.	string
Path	name required	Name of the subscribed consumer to retrieve records from.	string
Query	max_bytes optional	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.	integer
Query	timeout optional	The maximum amount of time, in milliseconds, that the HTTP Bridge spends retrieving records before timing out the request.	integer

Responses

HTTP Code	Description	Schema
200	Poll request executed successfully.	ConsumerRecordList
404	The specified consumer instance was not found.	Error
406	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.	Error
422	Response exceeds the maximum number of bytes the consumer can receive	Error

Produces

application/vnd.kafka.json.v2+json
application/vnd.kafka.binary.v2+json
application/vnd.kafka.text.v2+json
application/vnd.kafka.v2+json

Tags

Consumers

Example HTTP response

Response 200

[ {
  "topic" : "topic",
  "key" : "key1",
  "value" : {
    "foo" : "bar"
  },
  "partition" : 0,
  "offset" : 2
}, {
  "topic" : "topic",
  "key" : "key2",
  "value" : [ "foo2", "bar2" ],
  "partition" : 1,
  "offset" : 3
} ]

[
  {
    "topic": "test",
    "key": "a2V5",
    "value": "Y29uZmx1ZW50",
    "partition": 1,
    "offset": 100,
  },
  {
    "topic": "test",
    "key": "a2V5",
    "value": "a2Fma2E=",
    "partition": 2,
    "offset": 101,
  }
]

Response 404

{
  "error_code" : 404,
  "message" : "The specified consumer instance was not found."
}

Response 406

{
  "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."
}

Response 422

{
  "error_code" : 422,
  "message" : "Response exceeds the maximum number of bytes the consumer can receive"
}

POST /consumers/{groupid}/instances/{name}/subscription

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.

Parameters

Type	Name	Description	Schema
Path	groupid required	ID of the consumer group to which the subscribed consumer belongs.	string
Path	name required	Name of the consumer to subscribe to topics.	string
Body	body required	List of topics to which the consumer will subscribe.	Topics

Responses

HTTP Code	Description	Schema
204	Consumer subscribed successfully.	No Content
404	The specified consumer instance was not found.	Error
409	Subscriptions to topics, partitions, and patterns are mutually exclusive.	Error
422	A list (of `Topics` type) or a `topic_pattern` must be specified.	Error

Consumes

application/vnd.kafka.v2+json

Produces

application/vnd.kafka.v2+json

Tags

Consumers

Example HTTP request

Request body

{
  "topics" : [ "topic1", "topic2" ]
}

Example HTTP response

Response 404

{
  "error_code" : 404,
  "message" : "The specified consumer instance was not found."
}

Response 409

{
  "error_code" : 409,
  "message" : "Subscriptions to topics, partitions, and patterns are mutually exclusive."
}

Response 422

{
  "error_code" : 422,
  "message" : "A list (of Topics type) or a topic_pattern must be specified."
}

GET /consumers/{groupid}/instances/{name}/subscription

Description

Retrieves a list of the topics to which the consumer is subscribed.

Parameters

Type	Name	Description	Schema
Path	groupid required	ID of the consumer group to which the subscribed consumer belongs.	string
Path	name required	Name of the subscribed consumer.	string

Responses

HTTP Code	Description	Schema
200	List of subscribed topics and partitions.	SubscribedTopicList
404	The specified consumer instance was not found.	Error

Produces

application/vnd.kafka.v2+json

Tags

Consumers

Example HTTP response

Response 200

{
  "topics" : [ "my-topic1", "my-topic2" ],
  "partitions" : [ {
    "my-topic1" : [ 1, 2, 3 ]
  }, {
    "my-topic2" : [ 1 ]
  } ]
}

Response 404

{
  "error_code" : 404,
  "message" : "The specified consumer instance was not found."
}

DELETE /consumers/{groupid}/instances/{name}/subscription

Description

Unsubscribes a consumer from all topics.

Parameters

Type	Name	Description	Schema
Path	groupid required	ID of the consumer group to which the subscribed consumer belongs.	string
Path	name required	Name of the consumer to unsubscribe from topics.	string

Responses

HTTP Code	Description	Schema
204	Consumer unsubscribed successfully.	No Content
404	The specified consumer instance was not found.	Error

Tags

Consumers

Example HTTP response

Response 404

{
  "error_code" : 404,
  "message" : "The specified consumer instance was not found."
}

GET /healthy

Description

Check if the bridge is running. This does not necessarily imply that it is ready to accept requests.

Responses

HTTP Code	Description	Schema
204	The bridge is healthy	No Content
500	The bridge is not healthy	No Content

GET /metrics

Description

Retrieves the bridge metrics in Prometheus format.

Responses

HTTP Code	Description	Schema
200	Metrics in Prometheus format retrieved successfully.	string

Produces

text/plain

GET /openapi

Description

Retrieves the OpenAPI v2 specification in JSON format.

Responses

HTTP Code	Description	Schema
204	OpenAPI v2 specification in JSON format retrieved successfully.	string

Produces

application/json

GET /ready

Description

Check if the bridge is ready and can accept requests.

Responses

HTTP Code	Description	Schema
204	The bridge is ready	No Content
500	The bridge is not ready	No Content

GET /topics

Description

Retrieves a list of all topics.

Responses

HTTP Code	Description	Schema
200	List of topics.	< string > array

Produces

application/vnd.kafka.v2+json

Tags

Topics

Example HTTP response

Response 200

[ "topic1", "topic2" ]

POST /topics/{topicname}

Description

Sends one or more records to a given topic, optionally specifying a partition, key, or both.

Parameters

Type	Name	Description	Schema
Path	topicname required	Name of the topic to send records to or retrieve metadata from.	string
Query	async optional	Whether to return immediately upon sending records, instead of waiting for metadata. No offsets will be returned if specified. Defaults to false.	boolean
Body	body required		ProducerRecordList

Responses

HTTP Code	Description	Schema
200	Records sent successfully.	OffsetRecordSentList
404	The specified topic was not found.	Error
422	The record list is not valid.	Error

Consumes

application/vnd.kafka.json.v2+json
application/vnd.kafka.binary.v2+json
application/vnd.kafka.text.v2+json

Produces

application/vnd.kafka.v2+json

Tags

Producer
Topics

Example HTTP request

Request body

{
  "records" : [ {
    "key" : "key1",
    "value" : "value1"
  }, {
    "value" : "value2",
    "partition" : 1
  }, {
    "value" : "value3"
  } ]
}

Example HTTP response

Response 200

{
  "offsets" : [ {
    "partition" : 2,
    "offset" : 0
  }, {
    "partition" : 1,
    "offset" : 1
  }, {
    "partition" : 2,
    "offset" : 2
  } ]
}

Response 404

{
  "error_code" : 404,
  "message" : "The specified topic was not found."
}

Response 422

{
  "error_code" : 422,
  "message" : "The record list contains invalid records."
}

GET /topics/{topicname}

Description

Retrieves the metadata about a given topic.

Parameters

Type	Name	Description	Schema
Path	topicname required	Name of the topic to send records to or retrieve metadata from.	string

Responses

HTTP Code	Description	Schema
200	Topic metadata	TopicMetadata

Produces

application/vnd.kafka.v2+json

Tags

Topics

Example HTTP response

Response 200

{
  "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
    } ]
  } ]
}

GET /topics/{topicname}/partitions

Description

Retrieves a list of partitions for the topic.

Parameters

Type	Name	Description	Schema
Path	topicname required	Name of the topic to send records to or retrieve metadata from.	string

Responses

HTTP Code	Description	Schema
200	List of partitions	< PartitionMetadata > array
404	The specified topic was not found.	Error

Produces

application/vnd.kafka.v2+json

Tags

Topics

Example HTTP response

Response 200

[ {
  "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
  } ]
} ]

Response 404

{
  "error_code" : 404,
  "message" : "The specified topic was not found."
}

POST /topics/{topicname}/partitions/{partitionid}

Description

Sends one or more records to a given topic partition, optionally specifying a key.

Parameters

Type	Name	Description	Schema
Path	partitionid required	ID of the partition to send records to or retrieve metadata from.	integer
Path	topicname required	Name of the topic to send records to or retrieve metadata from.	string
Query	async optional	Whether to return immediately upon sending records, instead of waiting for metadata. No offsets will be returned if specified. Defaults to false.	boolean
Body	body required	List of records to send to a given topic partition, including a value (required) and a key (optional).	ProducerRecordToPartitionList

Responses

HTTP Code	Description	Schema
200	Records sent successfully.	OffsetRecordSentList
404	The specified topic partition was not found.	Error
422	The record is not valid.	Error

Consumes

application/vnd.kafka.json.v2+json
application/vnd.kafka.binary.v2+json
application/vnd.kafka.text.v2+json

Produces

application/vnd.kafka.v2+json

Tags

Producer
Topics

Example HTTP request

Request body

{
  "records" : [ {
    "key" : "key1",
    "value" : "value1"
  }, {
    "value" : "value2"
  } ]
}

Example HTTP response

Response 200

{
  "offsets" : [ {
    "partition" : 2,
    "offset" : 0
  }, {
    "partition" : 1,
    "offset" : 1
  }, {
    "partition" : 2,
    "offset" : 2
  } ]
}

Response 404

{
  "error_code" : 404,
  "message" : "The specified topic partition was not found."
}

Response 422

{
  "error_code" : 422,
  "message" : "The record is not valid."
}

GET /topics/{topicname}/partitions/{partitionid}

Description

Retrieves partition metadata for the topic partition.

Parameters

Type	Name	Description	Schema
Path	partitionid required	ID of the partition to send records to or retrieve metadata from.	integer
Path	topicname required	Name of the topic to send records to or retrieve metadata from.	string

Responses

HTTP Code	Description	Schema
200	Partition metadata	PartitionMetadata
404	The specified topic partition was not found.	Error

Produces

application/vnd.kafka.v2+json

Tags

Topics

Example HTTP response

Response 200

{
  "partition" : 1,
  "leader" : 1,
  "replicas" : [ {
    "broker" : 1,
    "leader" : true,
    "in_sync" : true
  }, {
    "broker" : 2,
    "leader" : false,
    "in_sync" : true
  } ]
}

Response 404

{
  "error_code" : 404,
  "message" : "The specified topic partition was not found."
}

GET /topics/{topicname}/partitions/{partitionid}/offsets

Description

Retrieves a summary of the offsets for the topic partition.

Parameters

Type	Name	Description	Schema
Path	partitionid required	ID of the partition.	integer
Path	topicname required	Name of the topic containing the partition.	string

Responses

HTTP Code	Description	Schema
200	A summary of the offsets for the topic partition.	OffsetsSummary
404	The specified topic partition was not found.	Error

Produces

application/vnd.kafka.v2+json

Tags

Topics

Example HTTP response

Response 200

{
  "beginning_offset" : 10,
  "end_offset" : 50
}

Response 404

{
  "error_code" : 404,
  "message" : "The specified topic partition was not found."
}

Files

paths.adoc

Latest commit

History

paths.adoc

File metadata and controls

Paths

GET /

Description

Responses

Produces

Example HTTP response

Response 200

POST /consumers/{groupid}

Description

Parameters

Responses

Consumes

Produces

Tags

Example HTTP request

Request body

Example HTTP response

Response 200

Response 409

Response 422

DELETE /consumers/{groupid}/instances/{name}

Description

Parameters

Responses

Consumes

Produces

Tags

Example HTTP response

Response 404

POST /consumers/{groupid}/instances/{name}/assignments

Description

Parameters

Responses

Consumes

Produces

Tags

Example HTTP request

Request body

Example HTTP response

Response 404

Response 409

POST /consumers/{groupid}/instances/{name}/offsets

Description

Parameters

Responses

Consumes

Produces

Tags

Example HTTP request

Request body

Example HTTP response

Response 404

POST /consumers/{groupid}/instances/{name}/positions

Description

Parameters

Responses

Consumes

Produces

Tags

Example HTTP request

Request body

Example HTTP response

Response 404

POST /consumers/{groupid}/instances/{name}/positions/beginning

Description

Parameters

Responses

Consumes

Produces

Tags

Example HTTP request

Request body

Example HTTP response

Response 404