IBM Event Streams Schema Registry API

Introduction IBM Event Streams also provides the following APIs: Event Streams Admin REST API Referencehttps://cloud.ibm.com/apidocs/event-streams/adminrest Event Streams REST Producer API Referencehttps://cloud.ibm.com/apidocs/event-streams/restproducer Event Streams REST Producer v2 endpointhttps://cloud.ibm.com/apidocs/event-streams/restproducerv2 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. Apache Kafka can handle any data, but it does not validate the information in the messages. However, efficient handling of data often requires that the data includes specific information in a certain format. By using schemas, you can define the structure of the data in a message, ensuring that both producers and consumers use the correct structure. The Event Streams Schema Registry REST API allows you to manage schema associated with an instance of Event Streams. More specifically, you can complete the following tasks: Create, read, and delete schemas Create, read, and delete individual versions of a schema Read and update the global compatibility rule for the registry Create, read, update, and delete compatibility rules that apply to individual schemas The Schema Registry is enabled by default for the Event Streams Enterprise plan. It is not automatically enabled for the Satellite plan. For information about how to enable it for the Satellite plan, see Enable the schema registry APIhttps://cloud.ibm.com/docs/EventStreams?topic=EventStreams-satellite-provisioningsatellite-enable-schema-registry. The Schema Registry is not available for other Event Streams plans. For more information, see Event Streams Schema Registryhttps://cloud.ibm.com/docs/EventStreams?topic=EventStreams-ESschemaregistry. You can downloadhttps://cloud.ibm.com/apidocs/event-streams/schemaregistry.json the OpenAPI specification compliant descriptors for this REST interface. Alternatively, click the three vertical dots next to the IBM Event Streams Schema Registry API title in the top left corner of this app, then click the Download OpenAPI definition link that appears. Endpoint URLs The Schema Registry API endpoint is the kafkahttpurl property in the service key for the service instance. To retrieve this property, use the following command: ibmcloud resource service-key "${serviceinstancekeyname}" --output json | jq -r '.|.credentials.kafkahttpurl' Authentication You can authenticate to the Schema Registry using an API key. This is supplied as the password portion of a HTTP basic authentication header. Set the username portion of this header to the word “token”. You can also grant a bearer token for a system ID or user and supply this as a credential. To do this, specify an HTTP header in the format: "Authorization: Bearer $TOKEN" where $TOKEN is the bearer token. For example: curl –H "Authorization: Bearer $TOKEN" ... 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 | The request was successful. The response body is a JSON array containing the information you requested. | | 204 | OK | The schema version was successfully deleted. | | 400 | Bad request | The request was not valid. Consult the error information returned in the response body for details. | | 403 | Forbidden | The client is not authorized to perform this request. | | 404 | Not found | Either the registry does not contain a schema with the specified schema ID, or the schema identified by the schema ID does not contain a version corresponding to the specified version number, or the schema is not configured with the specified type of rule. | | 409 | Conflict | This code indicates one of the following conflicts: \n A schema with the specified schema ID already exists \n A schema rule with the same type already exists for this schema. \n The schema does not have a rule of the specified type. \n Either the schema already has the maximum number of permitted versions, or creating a new schema version would fail the required compatibility checks based on existing versions of the schema. | 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: Apache Kafka client for Javahttp://kafka.apache.org/downloads node-rdkafka client for Node.jshttps://github.com/Blizzard/node-rdkafka confluent-kafka-python client for Pythonhttps://github.com/confluentinc/confluent-kafka-python confluent-kafka-go client for Golanghttps://github.com/confluentinc/confluent-kafka-go librdkafka client for C or C++https://github.com/edenhill/librdkafka You can find details of what is supported by Event Streams at: Support summary for all recommended clientshttps://cloud.ibm.com/docs/services/EventStreams?topic=eventstreams-kafkausingclientsummary. For information about how to install and use the SDKs, see Using the Kafka Java clienthttps://cloud.ibm.com/docs/services/EventStreams?topic=eventstreams-kafkajavausing. Event Streams samples For information about running a sample Java 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 applicationhttps://github.com/ibm-messaging/event-streams-samples/tree/master/kafka-java-console-sample uses String serializer IBM Event Streams Kafka Java console schema sample applicationhttps://github.com/ibm-messaging/event-streams-samples/tree/master/kafka-java-console-schema-sample uses the Avro serializer