IBM Cloud API Docs

Introduction

IBM Event Streams for IBM Cloud® is a high-throughput message bus built with Apache Kafka. It is optimized for event ingestion into IBM Cloud and event stream distribution between your services and applications.

Event Streams provides a REST API to help connect your existing systems to your Event Streams Kafka cluster. Using the API, you can integrate Event Streams with any system that supports RESTful APIs.

The REST producer API is a scalable REST interface for producing messages to Event Streams over a secure HTTP endpoint. Send event data to Event Streams, utilize Kafka technology to handle data feeds, and take advantage of Event Streams features to manage your data.

Use the API to connect existing systems to Event Streams. Create produce requests from your systems into Event Streams, including specifying the message key, headers, and the topics that you want to write messages to.

The REST producer API is available as part of the Event Streams Standard and Enterprise plans only.

You can download the OpenAPI specification compliant descriptors for this REST interface. Alternatively, click the three vertical dots next to the IBM Event Streams REST Producer title in the top left corner of this app, then click the Download OpenAPI definition link that appears.

For more information about Event Streams, see What is Event Streams?.

Other Event Streams APIs

Endpoint URLs

The URL for the API's endpoint is provided in the kafka_http_url property.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

HTTP status code Description Recovery
200 OK Message successfully sent to Event Streams.
400 Bad request Not a valid request.
401 Unauthorized You are unauthorized to produce to this topic.
403 Forbidden The token that you have provided does not have sufficient permissions to produce to a topic. Check if you have provided the token with the required access role.
404 Not found The topic does not exist. If Kafka setting auto.create.topics.enable is set to true (the default), Kafka automatically creates the topic with the default replication factor and number of partitions. If Kafka setting auto.create.topics.enable is set to false, this error message is displayed when attempting to produce to a topic that does not exist.
429 Too many requests Too many consecutive requests.
415 Unsupported Media Type The provided value for Content-Type header is unsupported.
408 Request timeout The request timed out producing to Event Streams.
500 Internal server error The request failed due to an internal server error.
503 Service unavailable The request failed due to Event Streams brokers being unavailable.

Authentication

Use one of the following methods to authenticate:

  • To authenticate using Basic Auth: Use the user and api_key properties of the above objects as the username and password. Place these values into the Authorization header of the HTTP request in the form Basic <base64 encoding of username and password joined by a single colon (:)>.

  • To authenticate using a bearer token: To obtain your token using the IBM Cloud CLI, first log in to IBM Cloud, then run the following command:

    ibmcloud iam oauth-tokens
    

    Place this token in the Authorization header of the HTTP request in the form Bearer<token>. Both API key or JWT tokens are supported.

  • To authenticate directly using the api_key: Place the key directly as the value of the X-Auth-Token HTTP header.

Note that producing to a topic using v2 endpoint of REST Producer API supports only bearer token authentication.

The following code shows an example of sending a message using curl:

curl -v -X POST -H "Authorization: Basic <base64 username:password>" -H "Content-Type: text/plain" -H "Accept: application/json" -d 'test message' "<kafka_http_url>/topics/<topic_name>/records"

Kafka SDKs

Event Streams is based on the open source Apache Kafka, therefore all SDKs are provided for by the open-source community, covering the core runtimes listed. For the most up-to-date information about these libraries refer to the project homepages. For example:

You can find details of what is supported by Event Streams at: Support summary for all recommended clients.

For information about how to install and use the SDKs, see Using the Kafka Java client.

For information about running a Java sample application that demonstrates how to connect to Event Streams and how to send and receive messages using the Kafka Java API, see IBM Event Streams Kafka Java console sample application.

Methods

Produce a message.

Produce the body of the request as a message in IBM Event Streams.

POST /topics/{topic_name}/records

Request

Custom Headers

  • Allowable values: [application/json,vnd.ibm-event-streams.json.v1,text/plain,vnd.ibm-event-streams.text.v1,application/octet-stream,vnd.ibm-event-streams.binary.v1]

Path Parameters

  • The name of the topic you want to produce the messages to.

Query Parameters

  • The record key to use when producing a Kafka message. If omitted the default round robin partitioner is used.

  • The type of the key, either text or binary.

    Allowable values: [text,binary]

  • Comma separated list of key:value pairs to be set as message properties. The value must be expressed in base16 encoding, for example: /records?headers=colour:726463,size:666f726d696461626c65

The message to be produced to the topic.

Response

Object returned on successful request.

Status Code

  • Message successfully sent to IBM Event Streams.

  • Not a valid request.

  • Unauthorized to produce to this topic.

  • The topic does not exist. If Kafka setting auto.create.topics.enable is set to true (default), Kafka automatically creates the topic with the default replication factor and number of partitions. If Kafka setting auto.create.topics.enable is set to false, this error message is displayed when attempting to produce to a topic that does not exist.

  • The request timed out producing to IBM Event Streams.

  • The request failed due to an internal server error.

  • The request failed due to IBM Event Streams brokers being unavailable.

No Sample Response

This method does not specify any sample responses.