Skip to main content
POST /gateway/v2/topics/{topic}/records produces Kafka records to a topic through Gateway, without a Kafka client. This feature is in preview from Gateway 3.23.0. It’s disabled by default and its request and response format can change between releases. Gateway serves the endpoint on a listener of its own, on port 8889 by default, with its own TLS settings. To produce your first records, follow produce records over REST. The endpoint is also listed in the Gateway API reference.

How it works

The endpoint takes the caller’s Kafka credentials as HTTP basic authentication. Gateway uses them as the SASL/PLAIN credentials of a producer that connects to Gateway’s own SASL_PLAINTEXT listener. The same authentication, ACLs, Virtual Cluster and Interceptors apply as for any other Kafka client connecting to Gateway.

Requirements

The producer connects to the listener’s bind address, or to localhost when the listener binds every interface, then follows the advertised addresses. Gateway itself has to be able to reach these addresses.

Request

The body holds one record object, or several record objects one after the other. Gateway writes the records in the order they appear. type is mandatory in key and value, and takes one of these values: Schema Registry types aren’t supported and return 400. Gateway ignores unknown fields.

Partitioning

Without partitionId, the Java client’s default partitioner picks the partition: a hash of the key bytes for keyed records, sticky partitioning for records without a key. A librdkafka client producing the same key can pick another partition.

Response

Gateway returns one result per record, in the same order as the request.

Errors

With a single record, the record’s error is the HTTP response: The body uses the Gateway API’s error format:
With several records, a record that fails doesn’t stop the others. The HTTP status of the response is still 200, so check the errorCode of each result. A failed record gets an error in place of its result:

Differences from Confluent REST Proxy v3

The request and response fields follow Confluent REST Proxy v3, with these differences:
  • Fields are in camelCase and the response has no cluster_id.
  • The path has no /v3/clusters/{cluster_id} segment.
  • type is mandatory in key and value.
  • Gateway reads the whole body before producing, rather than streaming it.
  • A single-record error, or an error about the whole request, uses the Gateway API’s {"title": ...} format.