IBM Event Streams Schema Registry API

Introduction

Last updated: 2023-04-17

IBM Event Streams also provides the following APIs:

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 API.

The Schema Registry is not available for other Event Streams plans.

For more information, see Event Streams Schema Registry.

You can download 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 kafka_http_url property in the service key for the service instance. To retrieve this property, use the following command:

ibmcloud resource service-key "${service_instance_key_name}" --output json | jq -r '.[]|.credentials.kafka_http_url'

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: A schema with the specified schema ID already exists A schema rule with the same type already exists for this schema. The schema does not have a rule of the specified type. 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:

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.

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 application (uses String serializer)
IBM Event Streams Kafka Java console schema sample application (uses the Avro serializer)

Returns an array containing the schema IDs of all of the schemas that are stored in the registry.

GET /artifacts

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

string[]

Status Code

200
The list schema IDs request was successful. The response body is a JSON array containing a list of schema IDs.
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.

Example responses

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Create a new schema and populate it with an initial schema version containing the AVRO document in the request body.

POST /artifacts

Request

Custom Headers

X-Registry-ArtifactId
string
The name to assign to the new schema. This must be unique. If this value is not specified then a UUID is used.

Request Body

Required*

avroSchema

The AVRO schema to use as the first version of this new schema.

Examples:

Response

Response Body

schemaMetadata

Information about a schema version.

Status Code

200
The schema was successfully created. Information about the newly created schema is included in the response body.
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.
409
A schema with the specified schema ID already exists.

Example responses

Status 200

{
  "id": "my-schemada",
  "type": "AVRO",
  "version": 1,
  "createdOn": 1579267788258,
  "modifiedOn": 1579267788258,
  "globalId": 75
}
Copy to clipboard

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 409

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Retrieves the lastest version of the specified schema.

GET /artifacts/{id}

Request

Path Parameters

id
Required*
string
The ID of a schema.

Response

Response Body

avroSchema

Status Code

200
The latest version of the schema was successfully retrieved. This schema version is included in the response body.
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.
404
The registry does not contain a schema with the specified schema ID.

Example responses

Status 200

{
  "type": "record",
  "name": "book",
  "fields": [
    {
      "name": "title",
      "type": "string"
    },
    {
      "name": "author",
      "type": "string"
    }
  ]
}
Copy to clipboard

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 404

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Deletes a schema and all of its versions from the schema registry.

DELETE /artifacts/{id}

Request

Path Parameters

id
Required*
string
The ID of the schema to delete.

Response

Status Code

204
The schema was successfully deleted from the registry.
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.
404
The registry does not contain a schema with the specified schema ID.

Example responses

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 404

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Updates a schema

PUT /artifacts/{id}

Request

Path Parameters

id
Required*
string
The ID of the schema to update.

Request Body

Required*

avroSchema

The AVRO schema to update

Examples:

Response

Response Body

schemaMetadata

Information about a schema version.

Status Code

200
The schema was successfully updated
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.
404
The registry does not contain a schema with the specified schema ID.

Example responses

Status 200

{
  "id": "my-schemada",
  "type": "AVRO",
  "version": 1,
  "createdOn": 1579267788258,
  "modifiedOn": 1579267788258,
  "globalId": 75
}
Copy to clipboard

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 404

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Returns an array containing the version numbers of all of the versions of the specified schema.

GET /artifacts/{id}/versions

Request

Path Parameters

id
Required*
string
The schema ID for which the list of versions will be returned.

Response

Response Body

integer[]

Schema version number

Status Code

200
The request to list the versions of a schema was successful. The body of the response contains an array of schema version numbers.
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.
404
The registry does not contain a schema with the specified schema ID.

Example responses

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 404

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Creates a new version of a schema using the AVRO schema supplied in the request body.

POST /artifacts/{id}/versions

Request

Path Parameters

id
Required*
string
A schema ID. This identifies the schema for which a new version will be created.

Request Body

Required*

avroSchema

The AVRO schema to use for the new schema version.

Examples:

Response

Response Body

schemaMetadata

Information about a schema version.

Status Code

200
The new schema version was successfully created. Information about the newly created schema is returned in the response body.
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.
404
The registry does not contain a schema with the specified schema ID.
409
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. Consult the error information returned in the response body for details.

Example responses

Status 200

{
  "id": "my-schemada",
  "type": "AVRO",
  "version": 1,
  "createdOn": 1579267788258,
  "modifiedOn": 1579267788258,
  "globalId": 75
}
Copy to clipboard

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 404

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 409

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Retrieve a particular version of the schema.

GET /artifacts/{id}/versions/{version}

Request

Path Parameters

id
Required*
string
The schema ID identifying which schema to return a version from.
version
Required*
integer
The version number that identifies the particular schema version to return.

Response

Response Body

avroSchema

Status Code

200
The AVRO schema corresponding to the requested schema version.
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.
404
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.

Example responses

Status 200

{
  "type": "record",
  "name": "book",
  "fields": [
    {
      "name": "title",
      "type": "string"
    },
    {
      "name": "author",
      "type": "string"
    }
  ]
}
Copy to clipboard

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 404

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Delete a version of the schema. If this was the only version of the schema then the whole schema will be deleted.

DELETE /artifacts/{id}/versions/{version}

Request

Path Parameters

id
Required*
string
A schema ID that identifies the schema to delete a version from.
version
Required*
integer
The schema version number to delete.

Response

Status Code

204
The schema version was successfully deleted.
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.
404
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.

Example responses

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 404

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Create a new rule that controls compatibility checks for a particular schema. Schema rules override the registries global compatibility rule setting.

POST /artifacts/{id}/rules

Request

Path Parameters

id
Required*
string
The ID of the schema that the rule is to be associated with.

Request Body

Required*

rule

A JSON object representing the schema rule to create.

Examples:

Response

Response Body

rule

Rules define constraints on whether the schema registry will accept a new version of a schema.

Status Code

200
The schema rule was created successfully. The value of the schema rule is returned in the body of the response.
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.
404
The registry does not contain a schema with the specified schema ID.
409
A schema rule with the same type already exists for this schema. Use the REST request that specifies the PUT verb to a path of /artifacts/{id}/rules/{rule} to update the rule.

Example responses

Status 200

{
  "type": "COMPATIBILITY",
  "config": "BACKWARD"
}
Copy to clipboard

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 404

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 409

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Retrieves the current configuration for a schema rule. If a schema rule exists then it overrides the corresponding global rule that would otherwise be applied.

GET /artifacts/{id}/rules/{rule}

Request

Path Parameters

id
Required*
string
The ID of the schema to retrieve the rule for.
rule
Required*
string
The type of rule to retrieve. Currently only the value that can be specified is COMPATIBILITY.

Allowable values: [COMPATIBILITY]

Response

Response Body

rule

Rules define constraints on whether the schema registry will accept a new version of a schema.

Status Code

200
The schema rule was successfully retrieved. The value of the schema rule is returned in the body of the response.
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.
404
Either the registry does not contain a schema with the specified schema ID, or the schema is not configured with the specified type of rule.

Example responses

Status 200

{
  "type": "COMPATIBILITY",
  "config": "BACKWARD"
}
Copy to clipboard

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 404

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Updates the configuration of an existing schema rule. The updated rule will be applied to the specified schema, overriding the value set for the corresponding global rule.

PUT /artifacts/{id}/rules/{rule}

Request

Path Parameters

id
Required*
string
The ID of the schema for which to update the rule configuration.
rule
Required*
string
The type of rule to update. Currently only the value that can be specified is COMPATIBILITY.

Allowable values: [COMPATIBILITY]

Request Body

Required*

rule

A JSON object representing the updated values to use for the schema rule.

Examples:

Response

Response Body

rule

Rules define constraints on whether the schema registry will accept a new version of a schema.

Status Code

200
The schema rule was successfully retrieved. The value of the schema rule is returned in the body of the response.
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.
409
This schema does not have a rule of the specified type. Use the REST request that specifies the POST verb to a path of /artifacts/{id}/rules to create a schema rule.

Example responses

Status 200

{
  "type": "COMPATIBILITY",
  "config": "BACKWARD"
}
Copy to clipboard

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 409

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Delete a rule that controls compatibility checks for a particular schema. After this operation completes the schema will be subject to compatibility checking defined by the global compatibility rule setting for the registry.

DELETE /artifacts/{id}/rules/{rule}

Request

Path Parameters

id
Required*
string
The ID of the schema that the rule is to be deleted from.
rule
Required*
string
The type of rule to delete. Currently only the value that can be specified is COMPATIBILITY.

Allowable values: [COMPATIBILITY]

Response

Status Code

204
The schema rule was successfully deleted.
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.
404
Either the registry does not contain a schema with the specified schema ID, or the schema is not configured with the specified type of rule.

Example responses

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 404

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Retrieves the configuration for the specified global rule. The value of the global rule is used as the default when a schema does not have a corresponding schema compatibility rule defined.

GET /rules/{rule}

Request

Path Parameters

rule
Required*
string
The type of the global rule to retrieve. Currently only COMPATIBILITY is supported.

Allowable values: [COMPATIBILITY]

Response

Response Body

rule

Rules define constraints on whether the schema registry will accept a new version of a schema.

Status Code

200
The global rule was successfully retrieved. The value of the global rule is returned in the body of the response.
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.

Example responses

Status 200

{
  "type": "COMPATIBILITY",
  "config": "BACKWARD"
}
Copy to clipboard

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Update the configuration for the specified global rule. The value of the global rule is used as the default when a schema does not have a corresponding schema compatibility rule defined.

PUT /rules/{rule}

Request

Path Parameters

rule
Required*
string
The type of the global rule to update. Currently only COMPATIBILITY is supported.

Allowable values: [COMPATIBILITY]

Request Body

Required*

rule

A JSON object representing the schema rule to update.

Examples:

Response

Response Body

rule

Rules define constraints on whether the schema registry will accept a new version of a schema.

Status Code

200
The global rule was successfully updated. The new value for the global rule is returned in the body of the response.
400
The request was not valid. Consult the error information returned in the response body for details.
403
The client is not authorized to perform this request.

Example responses

Status 200

{
  "type": "COMPATIBILITY",
  "config": "BACKWARD"
}
Copy to clipboard

Status 400

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Status 403

{
  "error_code": 404,
  "message": "No schema with ID 1234 was found in the registry"
}
Copy to clipboard

Introduction

Endpoint URLs

Authentication

Error handling

Kafka SDKs

Event Streams samples

Methods

List schema IDs

Request

No Request Parameters

Response

Response Body

Status Code

200

400

403

Create a new schema

Request

Custom Headers

X-Registry-ArtifactId

Request Body

schema

Response

Response Body

createdOn

globalId

id

modifiedOn

type

version

Status Code

200

400

403

409

Get the latest version of a schema

Request

Path Parameters

id

Response

Response Body

schema

Status Code

200

400

403

404

Delete a schema

Request

Path Parameters

id

Response

Status Code

204

400

403

404

Update a schema

Request

Path Parameters

id

Request Body

schema

Response

Response Body

createdOn

globalId

id

modifiedOn

type

version

Status Code

200

400

403

404

List the versions of a schema

Request

Path Parameters

id