Introduction

"Kafka REST" usually refers to the Kafka REST Proxy, which exposes Kafka operations over HTTP. It is useful when the calling application cannot use a native Kafka client library but can send standard REST requests.

The core workflow is simple: produce records with POST, create a consumer instance, subscribe it to topics, read records, and clean up the consumer instance afterward.

Produce JSON Records

A common example is sending JSON records into a topic.

curl -X POST   -H "Content-Type: application/vnd.kafka.json.v2+json"   --data '{"records":[{"value":{"event":"signup","userId":42}}]}'   http://localhost:8082/topics/events

This sends one JSON record to the events topic.

The content type matters because the REST Proxy needs to know how to interpret the payload format.

Produce Plain String Records

If you are sending plain text instead of JSON objects, use the appropriate content type and value shape.

curl -X POST   -H "Content-Type: application/vnd.kafka.json.v2+json"   --data '{"records":[{"value":"hello from rest"}]}'   http://localhost:8082/topics/logs

The exact content type and serializer mode depend on how the REST Proxy is configured and what kind of data your topic expects.

Create a Consumer Instance

To consume records, first create a consumer instance inside a consumer group.

curl -X POST   -H "Content-Type: application/vnd.kafka.v2+json"   --data '{"name":"example-consumer","format":"json","auto.offset.reset":"earliest"}'   http://localhost:8082/consumers/example-group

The response includes a base URI for that consumer instance. Subsequent calls are made against that instance path.

Subscribe the Consumer to a Topic

curl -X POST   -H "Content-Type: application/vnd.kafka.v2+json"   --data '{"topics":["events"]}'   http://localhost:8082/consumers/example-group/instances/example-consumer/subscription

At this point, the consumer is subscribed and can fetch records.

Read Records

curl -X GET   -H "Accept: application/vnd.kafka.json.v2+json"   http://localhost:8082/consumers/example-group/instances/example-consumer/records

If records are available, the response contains an array of consumed messages.

For a real application, you would repeat this fetch step in a controlled loop or behind an HTTP client wrapper.

Delete the Consumer Instance

When you are done, delete the consumer instance so resources are cleaned up.

curl -X DELETE   http://localhost:8082/consumers/example-group/instances/example-consumer

This step is easy to forget in quick examples, but it matters in real workflows.

When Kafka REST Is a Good Fit

Kafka REST Proxy is useful when:

• the client platform cannot run a native Kafka library
• you need quick integration from scripts or tools
• HTTP is easier to manage than the Kafka protocol in your environment

It is less attractive when high-throughput, low-latency streaming is the main goal. Native Kafka clients are usually better for long-lived production consumers and producers.

Common Pitfalls

The biggest mistake is using the wrong content type or accept header. REST Proxy relies heavily on media types to know how to parse and return data.

Another common issue is forgetting the consumer lifecycle. You create an instance, subscribe it, poll records, and eventually delete it.

People also expect Kafka REST to behave exactly like a native client in every performance-sensitive case. It is a convenience layer, not a perfect substitute for the protocol-native approach.

Finally, make sure the REST Proxy itself has working connectivity and authorization to the Kafka cluster. HTTP success to the proxy does not help if the proxy cannot reach Kafka.

Summary

• Kafka REST usually means Kafka REST Proxy.
• Use POST /topics/... to produce records over HTTP.
• Create a consumer instance before subscribing and reading records.
• Use the correct media types in request and response headers.
• Delete consumer instances when you are finished.
• REST Proxy is convenient for integration, but native clients are usually better for heavy streaming workloads.