Schema Registry API Reference

This section provides a detailed reference for the Schema Registry API. The best way to test these is to use curl. For examples of using curl to test these APIs, see Schema Registry API Usage Examples.

You can also see curl API calls used in the Schema Registry Tutorial and to test drive different schema formats in the deep dive sections on Formats, Serializers, and Deserializers.

Ready to get started?

Compatibility

The Schema Registry server can enforce certain compatibility rules when new schemas are registered in a subject. These are the compatibility types:

  • BACKWARD: (default) consumers using the new schema can read data written by producers using the latest registered schema
  • BACKWARD_TRANSITIVE: consumers using the new schema can read data written by producers using all previously registered schemas
  • FORWARD: consumers using the latest registered schema can read data written by producers using the new schema
  • FORWARD_TRANSITIVE: consumers using all previously registered schemas can read data written by producers using the new schema
  • FULL: the new schema is forward and backward compatible with the latest registered schema
  • FULL_TRANSITIVE: the new schema is forward and backward compatible with all previously registered schemas
  • NONE: schema compatibility checks are disabled

We recommend keeping the default backward compatibility since it allows you to rewind consumers to the beginning of the topic.

For more details on schema resolution, see Schema Evolution and Compatibility for Schema Registry on Confluent Platform.

Content Types

The Schema Registry REST server uses content types for both requests and responses to indicate the serialization format of the data as well as the version of the API being used. Currently, the only serialization format supported is JSON and the only version of the API is v1. However, to remain compatible with future versions, you should specify preferred content types in requests and check the content types of responses.

The preferred format for content types is application/vnd.schemaregistry.v1+json, where v1 is the API version and json is the serialization format. However, other less specific content types are permitted, including application/vnd.schemaregistry+json to indicate no specific API version should be used (the most recent stable version will be used), application/json, and application/octet-stream. The latter two are only supported for compatibility and ease of use.

Your requests should specify the most specific format and version information possible via the HTTP Accept header:

Accept: application/vnd.schemaregistry.v1+json

The server also supports content negotiation, so you may include multiple, weighted preferences:

Accept: application/vnd.schemaregistry.v1+json; q=0.9, application/json; q=0.5

which can be useful when, for example, a new version of the API is preferred but you cannot be certain it is available yet.

Errors

All API endpoints use a standard error message format for any requests that return an HTTP status indicating an error (any 400 or 500 statuses). For example, a request entity that omits a required field may generate the following response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.schemaregistry.v1+json

{
    "error_code": 422,
    "message": "schema may not be empty"
}

Although it is good practice to check the status code, you may safely parse the response of any non-DELETE API calls and check for the presence of an error_code field to detect errors.

Example Requests Format and Valid JSON

The example requests below are formatted for readability. Therefore, multi-line example requests include returns (newlines). To use a multi-line example as a copy-paste test of an API, remove the newlines before running it so as not to trigger errors for invalid JSON.

For example, a direct copy-and-paste of this request will produce errors because it includes newlines to help with readability:

{
  "schema":
    "{
       \"type\": \"record\",
       \"name\": \"test\",
       \"fields\":
         [
           {
             \"type\": \"string\",
             \"name\": \"field1\"
           },
           {
             \"type\": \"int\",
             \"name\": \"field2\"
           }
         ]
     }"
}

This is the same request as that above with the newlines removed. It should run properly as a copy-and-paste example.

{"schema": "{ \"type\": \"record\", \"name\": \"test\", \"fields\": [ { \"type\": \"string\", \"name\": \"field1\" }, { \"type\": \"int\", \"name\": \"field2\" } ] }" }

Schemas

GET /schemas/ids/{int: id}

Get the schema string identified by the input ID.

Parameters:
  • id (int) – the globally unique identifier of the schema
  • format (string) – Desired output format, dependent on schema type. For AVRO schemas, valid values are: "" (default) or resolved. For PROTOBUF schemas, valid values are: "" (default), ignore_extensions, or serialized. (The parameter does not apply to JSON schemas.)
  • subject (string) – Add ?subject=<someSubjectName> at the end of this request to look for the subject in all contexts starting with the default context, and return the schema with the id from that context. To learn more about contexts, see the exporters API reference and the quick start and concepts guides for Schema Linking on Confluent Platform and Schema Linking on Confluent Cloud.
Response JSON Object:
 
  • schema (string) – Schema string identified by the ID
Status Codes:

Example request:

GET /schemas/ids/1 HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "schema": "{\"type\": \"string\"}"
}
GET /schemas/ids/{int: id}/schema

Retrieves only the schema identified by the input ID.

Parameters:
  • id (int) – the globally unique identifier of the schema
  • format (string) – Desired output format, dependent on schema type. For AVRO schemas, valid values are: "" (default) or resolved. For PROTOBUF schemas, valid values are: "" (default), ignore_extensions, or serialized. (The parameter does not apply to JSON schemas.)
  • subject (string) – Add ?subject=<someSubjectName> at the end of this request to look for the subject in all contexts starting with the default context, and return the schema with the ID from that context. To learn more about contexts, see the exporters API reference and the quick start and concepts guides for Schema Linking on Confluent Platform and Schema Linking on Confluent Cloud.
Response JSON Object:
 
  • schema (string) – Schema identified by the ID
Status Codes:

Example request:

GET /schemas/ids/1/schema HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

"string"
GET /schemas/types/

Get the schema types that are registered with Schema Registry.

Response JSON Object:
 
  • schema (string) – Schema types currently available on Schema Registry.
Status Codes:

Example request:

GET /schemas/types HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  ["JSON", "PROTOBUF", "AVRO"]
}
GET /schemas/ids/{int: id}/versions

Get the subject-version pairs identified by the input ID.

Parameters:
  • id (int) – the globally unique identifier of the schema
Response JSON Array of Objects:
 
  • subject (string) – Name of the subject
  • version (int) – Version of the returned schema
Status Codes:

Example request:

GET /schemas/ids/1/versions HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

[{"subject":"test-subject1","version":1}]

Subjects

The subjects resource provides a list of all registered subjects across all contexts in your Schema Registry. A subject refers to the name under which the schema is registered. If you are using Schema Registry for Kafka, then a subject refers to either a “<topic>-value” or “<topic>-key” depending on whether you are registering the value schema for that topic or the key schema. To learn more about subject name strategies, see How the naming strategies work.

Tip

To find subjects for a given ID, see GET /schemas/ids/{int: id}/versions.

GET /subjects

Get a list of registered subjects. (For API usage examples, see List all subjects.)

Parameters:
  • subjectPrefix (string) – Add ?subjectPrefix= (as an empty string) at the end of this request to list subjects in the default context. If this flag is not included, GET /subjects returns all subjects across all contexts. To learn more about contexts, see the exporters API reference and the quick start and concepts guides for Schema Linking on Confluent Platform and Schema Linking on Confluent Cloud.
  • deleted (boolean) – Add ?deleted=true at the end of this request to list both current and soft-deleted subjects. The default is false. If this flag is not included, only current subjects are listed (not those that have been soft-deleted). Hard and soft delete are explained below in the description of the delete API.
Response JSON Array of Objects:
 
  • name (string) – Subject
Status Codes:

Example request:

GET /subjects HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

["subject1", "subject2"]
GET /subjects/(string: subject)/versions

Get a list of versions registered under the specified subject.

Parameters:
  • subject (string) – the name of the subject
Response JSON Array of Objects:
 
  • version (int) – version of the schema registered under this subject
Status Codes:

Example request:

GET /subjects/test/versions HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

[
  1, 2, 3, 4
]
DELETE /subjects/(string: subject)

Deletes the specified subject and its associated compatibility level if registered. It is recommended to use this API only when a topic needs to be recycled or in a development environment. To learn more, see Schema Deletion Guidelines.

Parameters:
  • subject (string) – the name of the subject
  • permanent (boolean) – Add ?permanent=true at the end of this request to specify a hard delete of the subject, which removes all associated metadata including the schema ID. The default is false. If the flag is not included, a soft delete is performed. You must perform a soft delete first, then the hard delete. This flag is now supported on both Confluent Platform and Confluent Cloud, which sets limits on the number of schema versions supported in the registry. A hard delete frees up space in a way that a soft delete does not. To learn more, see Hard delete a schema in Schema Deletion Guidelines.
Response JSON Array of Objects:
 
  • version (int) – version of the schema deleted under this subject
Status Codes:

Example request:

DELETE /subjects/test HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

[
  1, 2, 3, 4
]
GET /subjects/(string: subject)/versions/(versionId: version)

Get a specific version of the schema registered under this subject

Parameters:
  • subject (string) – Name of the subject
  • version (versionId) – Version of the schema to be returned. Valid values for versionId are between [1,2^31-1] or the string latest, which returns the last registered schema under the specified subject. The value -1 is equivalent to latest. Note that there may be a new latest schema that gets registered right after this request is served. Note that there may be a new latest schema that gets registered right after this request is served.
  • format (string) – Desired output format, dependent on schema type. For AVRO schemas, valid values are: "" (default) or resolved. For PROTOBUF schemas, valid values are: "" (default), ignore_extensions, or serialized. (The parameter does not apply to JSON schemas.)
Response JSON Object:
 
  • subject (string) – Name of the subject that this schema is registered under
  • id (int) – Globally unique identifier of the schema
  • version (int) – Version of the returned schema
  • schemaType (string) – The schema format: AVRO is the default (if no schema type is shown on the response, the type is AVRO), PROTOBUF, JSON
  • schema (string) – The schema string
Status Codes:

Example request:

GET /subjects/test/versions/1 HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response (AVRO):

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "name": "test",
  "version": 1,
  "schema": "{\"type\": \"string\"}"
}

Example response (PROTOBUF):

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "name": "test",
  "version": 1,
  "schemaType": "PROTOBUF"
  "schema": "{\"type\": \"string\"}"
}
GET /subjects/(string: subject)/versions/(versionId: version)/schema

Get the schema for the specified version of this subject. The unescaped schema only is returned.

Parameters:
  • subject (string) – Name of the subject
  • version (versionId) – Version of the schema to be returned. Valid values for versionId are between [1,2^31-1] or the string latest, which returns the last registered schema under the specified subject. The value -1 is equivalent to latest. Note that there may be a new latest schema that gets registered right after this request is served.
  • format (string) – Desired output format, dependent on schema type. For AVRO schemas, valid values are: "" (default) or resolved. For PROTOBUF schemas, valid values are: "" (default), ignore_extensions, or serialized. (The parameter does not apply to JSON schemas.)
Response JSON Object:
 
  • schema (string) – The schema string (unescaped)
Status Codes:

Example request:

GET /subjects/test/versions/1/schema HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{"type": "string"}
POST /subjects/(string: subject)/versions

Register a new schema under the specified subject. (Essentially, create a new schema.) If successfully registered, this returns the unique identifier of this schema in the registry. The returned identifier should be used to retrieve this schema from the schemas resource and is different from the schema’s version which is associated with the subject. If the same schema is registered under a different subject, the same identifier will be returned. However, the version of the schema may be different under different subjects.

A schema should be compatible with the previously registered schema or schemas (if there are any) as per the configured compatibility level. If a compatibility level has been set on a subject, the configured compatibility level can be obtained by issuing a GET http:get:: /config/(string: subject). If this returns an error, it means that no subject-specific compatibility level is set for the subject. In that case, use GET http:get:: /config to find the global compatibility level, which applies to all subjects. (Subject-specific compatibility, when configured, overrides global.) For examples, see Update compatibility requirements on a subject and Get compatibility requirements on a subject.

If you register a schema that is identical to an existing schema in Schema Registry, a new version will not be created. Instead, Schema Registry recognizes the schema as already existing and returns the existing schema’s ID and its current version number. The latest version number will increment only if the schema being registered is different from any existing schema under that subject.

When there are multiple instances of Schema Registry running in the same cluster, the schema registration request will be forwarded to one of the instances designated as the primary. If the primary is not available, the client will get an error code indicating that the forwarding has failed.

If no schemaType is supplied, schemaType is assumed to be AVRO.

Parameters:
  • subject (string) – Subject under which the schema will be registered
  • normalize (boolean) – Add ?normalize=true at the end of this request to normalize the schema. The default is false. To learn more, see Schema normalization.
  • format (string) – Desired output format, dependent on schema type. For AVRO schemas, valid values are: "" (default) or resolved. For PROTOBUF schemas, valid values are: "" (default), ignore_extensions, or serialized. (The parameter does not apply to JSON schemas.)
Request JSON Object:
 
  • schema – The schema string
  • schemaType – Defines the schema format: AVRO (default), PROTOBUF, JSON (Optional)
  • references – Specifies the names of referenced schemas (Optional). To learn more, see Schema references.
  • metadata – Specifies the metadata for the schema (Optional). To learn more, see “Metadata Properties” in Data Contracts for Schema Registry .
  • ruleSet – Specifies the ruleSet for the schema (Optional). To learn more, see “Rules” in Data Contracts for Schema Registry .
Response JSON Object:
 
  • id (int) – Globally unique identifier of the schema
Status Codes:

Example request:

POST /subjects/test/versions HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

{
  "schema":
    "{
       \"type\": \"record\",
       \"name\": \"test\",
       \"fields\":
         [
           {
             \"type\": \"string\",
             \"name\": \"field1\"
           },
           {
             \"type\": \"com.acme.Referenced\",
             \"name\": \"int\"
           }
          ]
     }",
  "schemaType": "AVRO",
  "references": [
    {
       "name": "com.acme.Referenced",
       "subject":  "childSubject",
       "version": 1
    }
  ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{"id":1}
POST /subjects/(string: subject)

Check if a schema has already been registered under the specified subject. If so, this returns the schema string along with its globally unique identifier, its version under this subject and the subject name.

Parameters:
  • subject (string) – Subject under which the schema will be registered
  • normalize (boolean) – Add ?normalize=true at the end of this request to normalize the schema. The default is false. To learn more, see Schema normalization.
  • format (string) – Desired output format, dependent on schema type. For AVRO schemas, valid values are: "" (default) or resolved. For PROTOBUF schemas, valid values are: "" (default), ignore_extensions, or serialized. (The parameter does not apply to JSON schemas.)
Request JSON Object:
 
  • schema – The schema string
  • schemaType – Defines the schema format: AVRO (default), PROTOBUF, JSON (Optional)
  • references – Specifies the names of referenced schemas (Optional). To learn more, see Schema references.
  • metadata – Specifies the metadata for the schema (Optional). To learn more, see “Metadata Properties” in Data Contracts for Schema Registry .
  • ruleSet – Specifies the ruleSet for the schema (Optional). To learn more, see “Rules” in Data Contracts for Schema Registry .
Response JSON Object:
 
  • subject (string) – Name of the subject that this schema is registered under
  • id (int) – Globally unique identifier of the schema
  • version (int) – Version of the returned schema
  • schema (string) – The schema string
Status Codes:

Example request:

POST /subjects/test HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

{
      "schema":
         "{
                \"type\": \"record\",
                \"name\": \"test\",
                \"fields\":
                  [
                    {
                      \"type\": \"string\",
                      \"name\": \"field1\"
                    },
                    {
                      \"type\": \"int\",
                      \"name\": \"field2\"
                    }
                  ]
              }"
    }

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
      "subject": "test",
      "id": 1
      "version": 3
      "schema":
         "{
                \"type\": \"record\",
                \"name\": \"test\",
                \"fields\":
                  [
                    {
                      \"type\": \"string\",
                      \"name\": \"field1\"
                    },
                    {
                      \"type\": \"int\",
                      \"name\": \"field2\"
                    }
                  ]
              }"
    }
DELETE /subjects/(string: subject)/versions/(versionId: version)

Deletes a specific version of the schema registered under this subject. Unless you perform a hard delete (with ?permanent=true as noted below), this only deletes the version, leaving the schema ID intact and making it still possible to decode data using the schema ID. This API is recommended to be used only in development environments or under extreme circumstances where-in, its required to delete a previously registered schema for compatibility purposes or re-register previously registered schema.

Parameters:
  • subject (string) – Name of the subject
  • version (versionId) – Version of the schema to be deleted. Valid values for versionId are between [1,2^31-1] or the string latest, which deletes the last registered schema under the specified subject. The value -1 is equivalent to latest. Note that there may be a new latest schema that gets registered right after this request is served. Note that there may be a new latest schema that gets registered right after this request is served. For hard-delete of a schema version, you must provide a version number as input; not version:latest, which results in a soft delete only, even with the ?permanent=true flag appended. To learn more, see Schema Deletion Guidelines.
  • permanent (boolean) – Add ?permanent=true at the end of this request to specify a hard delete for a specific version of the subject, which removes all associated metadata including the schema ID. The default is false. If the flag is not included, a soft delete is performed. You must perform a soft delete first, then the hard delete. This flag is now supported on both Confluent Platform and Confluent Cloud, which sets limits on the number of schema versions supported in the registry. A hard delete frees up space in a way that a soft delete does not. To learn more, see Hard delete a schema in Schema Deletion Guidelines.
Response JSON Object:
 
  • int – Version of the deleted schema
Status Codes:

Example request:

DELETE /subjects/test/versions/1 HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

1
GET /subjects/(string: subject)/versions/{versionId: version}/referencedby

Get a list of IDs of schemas that reference the schema with the given subject and version.

Parameters:
  • subject (string) – Name of the subject
  • version (versionId) – Version of the schema to be returned. Valid values for versionId are between [1,2^31-1] or the string latest, which returns the last registered schema under the specified subject. The value -1 is equivalent to latest. Note that there may be a new latest schema that gets registered right after this request is served. Note that there may be a new latest schema that gets registered right after this request is served.
Response JSON Array of Objects:
 
  • id (int) – Globally unique identifier of the schema
Status Codes:

Example request:

GET /subjects/test/versions/1/referencedby HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

[
  1, 2, 3, 4
]
GET /subjects/(string: subject)/metadata

Retrieve the latest version with the given metadata. The given metadata takes the form of key-value pairs.

Parameters:
  • key (boolean) – Add ?key=<key> at the end of this request to match a metadata key. This query parameter can appear multiple times. Each instance is matched with a corresponding value query parameter, in order.
  • value (boolean) – Add ?value=<value> at the end of this request to match a metadata value. This query parameter can appear multiple times. Each instance is matched with a corresponding key query parameter, in order.
  • format (string) – Desired output format, dependent on schema type. For AVRO schemas, valid values are: "" (default) or resolved. For PROTOBUF schemas, valid values are: "" (default), ignore_extensions, or serialized. (The parameter does not apply to JSON schemas.)
  • deleted (boolean) – Add ?deleted=true at the end of this request to list both current and soft-deleted subjects. The default is false. If this flag is not included, only current subjects are listed (not those that have been soft-deleted). Hard and soft delete are explained below in the description of the delete API.
Response JSON Object:
 
  • subject (string) – Name of the subject that this schema is registered under
  • id (int) – Globally unique identifier of the schema
  • version (int) – Version of the returned schema
  • schemaType (string) – The schema format: AVRO is the default (if no schema type is shown on the response, the type is AVRO), PROTOBUF, JSON
  • schema (string) – The schema string
Status Codes:

Mode

You can use the mode resource to set the mode on Schema Registry at a global level or to set the mode on a specific subject. The following modes are available:

  • IMPORT
  • READONLY
  • READWRITE

Tip

To enable mode changes on a Schema Registry cluster, you must also set mode.mutability=true in the Schema Registry properties file before starting Schema Registry. Examples of setting this property and changing the mode on Schema Registry at a global level and at the subject level are shown as a part of the procedure to Migrate Schemas.

GET /mode

Get the current mode for Schema Registry at a global level.

Response JSON Object:
 
  • mode (string) – Schema Registry mode. Returns one of IMPORT, READONLY, READWRITE (default)
Status Codes:

Example request:

GET /mode HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "mode": "READWRITE"
}
PUT /mode

Update the global Schema Registry mode. This will work only if Schema Registry was started with mode.mutability=true set in the Schema Registry properties file.

Parameters:
  • force (boolean) – Add ?force=true at the end of this request to force a mode change even if the Schema Registry has existing schemas. This can be useful in disaster recovery (DR) scenarios using Schema Linking. The default is false, which does not allow a mode change to IMPORT if Schema Registry has registered schemas.
Request JSON Object:
 
  • mode (string) – New mode. Must be one of IMPORT, READONLY, READWRITE (default)
Status Codes: 
PUT /mode HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

{
  "mode": "IMPORT"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "mode": "IMPORT"
}
GET /mode/(string: subject)

Get the mode for a subject.

Parameters:
  • subject (string) – Name of the subject
Response JSON Object:
 
  • mode (string) – Mode for the subject. Returns one of IMPORT, READONLY, READWRITE (default)
Status Codes:

Example request:

GET /mode/test HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
   "mode": "READWRITE"
}
PUT /mode/(string: subject)

Update the mode for the specified subject. This will work only if Schema Registry was started with mode.mutability=true set in the Schema Registry properties file.

Parameters:
  • subject (string) – Name of the subject
  • force (boolean) – Add ?force=true at the end of this request to force a mode change even if the Schema Registry has existing schemas. This can be useful in disaster recovery (DR) scenarios using Schema Linking. The default is false, which does not allow a mode change to IMPORT if Schema Registry has registered schemas.
Request JSON Object:
 
  • mode (string) – New mode for the subject. Must be one of IMPORT, READONLY, READWRITE (default)
Status Codes:

Example request:

PUT /mode/test HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

{
  "mode": "READONLY"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "mode": "READONLY"
}
DELETE /mode/(string: subject)

Deletes the subject-level mode for the specified subject and reverts to the global default.

Parameters:
  • subject (string) – Name of the subject
Status Codes:

Example request:

DELETE /mode/test HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "mode": "READONLY"
}

Compatibility

The compatibility resource allows the user to test schemas for compatibility against a specific version or all versions of a subject’s schema. See Test compatibility of a schema with the latest schema under subject “Kafka-value” for usage examples.

POST /compatibility/subjects/(string: subject)/versions/(versionId: version)

Test input schema against a particular version of a subject’s schema for compatibility. Note that the compatibility level applied for the check is the configured compatibility level for the subject (http:get:: /config/(string: subject)). If this subject’s compatibility level was never changed, then the global compatibility level applies (http:get:: /config).

Parameters:
  • subject (string) – Subject of the schema version against which compatibility is to be tested
  • version (versionId) – Version of the subject’s schema against which compatibility is to be tested. Valid values for versionId are between [1,2^31-1] or the string latest, which checks compatibility of the input schema with the last registered schema under the specified subject. The value -1 is equivalent to latest. Note that there may be a new latest schema that gets registered right after this request is served.
  • verbose (boolean) – Add ?verbose=true at the end of this request to output the reason a schema fails the compatibility test, in cases where it fails. The default is false (the reason a schema fails compatibility test is not given).
Request JSON Object:
 
  • schema – The schema string
  • schemaType – Defines the schema format: AVRO (default), PROTOBUF, JSON (Optional)
  • references – Specifies the names of referenced schemas (Optional). To learn more, see Schema references.
  • metadata – Specifies the ruleSet for the schema (Optional). To learn more, see “Rules” in Data Contracts for Schema Registry .
  • ruleSet – Specifies the ruleSet for the schema (Optional). To learn more, see “Rules” in Data Contracts for Schema Registry .
Response JSON Object:
 
  • is_compatible (boolean) – True, if compatible. False otherwise
Status Codes:

Example request:

POST /compatibility/subjects/test/versions/latest HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

{
  "schema":
    "{
       \"type\": \"record\",
       \"name\": \"test\",
       \"fields\":
         [
           {
             \"type\": \"string\",
             \"name\": \"field1\"
           },
           {
             \"type\": \"int\",
             \"name\": \"field2\"
           }
         ]
     }"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "is_compatible": true
}
POST /compatibility/subjects/(string: subject)/versions

Perform a compatibility check on the schema against one or more versions in the subject, depending on how the compatibility is set. For example, if compatibility on the subject is set to BACKWARD, FORWARD, or FULL, the compatibility check is against the latest version. If compatibility is set to one of the TRANSITIVE types, the check is against all previous versions.

The compatibility level applied for the check is the configured compatibility level for the subject (http:get:: /config/(string: subject)). If this subject’s compatibility level was never changed, then the global compatibility level applies (http:get:: /config). This API endpoint, which tests a schema for compatibility against all versions, is new in Confluent Platform 7.0.0.

Parameters:
  • subject (string) – Subject of the schema version against which compatibility is to be tested
  • verbose (boolean) – Add ?verbose=true at the end of this request to output the reason a schema fails the compatibility test, in cases where it fails. The default is false (the reason a schema fails compatibility test is not given).
Request JSON Object:
 
  • schema – The schema string
  • schemaType – Defines the schema format: AVRO (default), PROTOBUF, JSON (Optional)
  • references – Specifies the names of referenced schemas (Optional). To learn more, see Schema references.
Response JSON Object:
 
  • is_compatible (boolean) – True, if compatible. False otherwise
Status Codes:

Example request:

POST /compatibility/subjects/test/versions
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

{
  "schema":
    "{
       \"type\": \"record\",
       \"name\": \"test\",
       \"fields\":
         [
           {
             \"type\": \"string\",
             \"name\": \"field1\"
           },
           {
             \"type\": \"int\",
             \"name\": \"field2\"
           }
         ]
     }"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "is_compatible": true
}

Config

The config resource allows you to inspect and update the cluster-level configuration values as well as subject overrides.

PUT /config

Update the configuration for global compatibility level, compatibility group, schema normalization, default metadata, and rule set.

When there are multiple instances of Schema Registry running in the same cluster, the update request will be forwarded to one of the instances designated as the primary. If the primary is not available, the client will get an error code indicating that the forwarding has failed.

Request JSON Object:
 
  • alias (string) – If alias is specified, then this subject is an alias for the the subject named by the alias. That means that any reference to this subject will be replaced by the alias. To learn more, see Subject aliases.
  • normalize (boolean) – If true, then schemas are automatically normalized when registered or when passed during lookups. This means that clients do not have to pass the “normalize” query parameter to have normalization occur. To learn more, see Schema normalization.
  • compatibility (string) – New global compatibility level for the subject. Must be one of BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, NONE
  • compatibilityGroup (string) – Only schemas that belong to the same compatibility group will be checked for compatibility. To learn more, see Configuration Enhancements in Data Contracts.
  • defaultMetadata (object) – Default value for the metadata to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
  • overrideMetadata (object) – Override value for the metadata to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
  • defaultRuleSet (object) – Default value for the ruleSet to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
  • overrideRuleSet (object) – Override value for the ruleSet to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
Status Codes:

Example request:

PUT /config HTTP/1.1
Host: kafkaproxy.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

{
  "compatibility": "FULL"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "compatibility": "FULL"
}
GET /config

Get configuration for global compatibility level, compatibility group, normalization, default metadata, and rule set.

Request JSON Object:
 
  • alias (string) – If alias is specified, shows the alias for the subject. References to this subject will be replaced by the alias. To learn more, see Subject aliases.
  • normalize (boolean) – If true, then schemas are automatically normalized when registered or when passed during lookups. The default is false. To learn more, see Schema normalization.
  • compatibilityLevel (string) – Shows global compatibility level for the subject. Returns one of BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, NONE
  • compatibilityGroup (string) – Shows compatibility group, if any is specified. Only schemas that belong to the same compatibility group will be checked for compatibility. To learn more, see Configuration Enhancements in Data Contracts.
  • defaultMetadata (object) – Default value for the metadata to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
  • overrideMetadata (object) – Override value for the metadata to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
  • defaultRuleSet (object) – Default value for the ruleSet to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
  • overrideRuleSet (object) – Override value for the ruleSet to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
Status Codes:

Example request:

GET /config HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "compatibilityLevel": "FULL"
}
PUT /config/(string: subject)

Update compatibility level for the specified subject. For more usage examples, see Update compatibility requirements on a subject.

Parameters:
  • subject (string) – Name of the subject
Request JSON Object:
 
  • alias (string) – If alias is specified, then this subject is an alias for the the subject named by the alias. That means that any reference to this subject will be replaced by the alias. To learn more, see Subject aliases.
  • normalize (boolean) – If true, then schemas are automatically normalized when registered or when passed during lookups. This means that clients do not have to pass the “normalize” query parameter to have normalization occur. To learn more, see Schema normalization.
  • compatibility (string) – New compatibility level for the subject. Must be one of BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, NONE
  • compatibilityGroup (string) – Only schemas that belong to the same compatibility group will be checked for compatibility. To learn more, see Configuration Enhancements in Data Contracts.
  • defaultMetadata (object) – Default value for the metadata to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
  • overrideMetadata (object) – Override value for the metadata to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
  • defaultRuleSet (object) – Default value for the ruleSet to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
  • overrideRuleSet (object) – Override value for the ruleSet to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
Status Codes:

Example request:

PUT /config/test HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

{
  "compatibility": "FULL"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "compatibility": "FULL"
}
GET /config/(string: subject)

Get compatibility level for a subject. For more usage examples, see Get compatibility requirements on a subject.

Parameters:
  • subject (string) – Name of the subject
  • defaultToGlobal (boolean) – Add ?defaultToGlobal=false at the end of this request to show the compatibility, if any, set at the subject level. Add ?defaultToGlobal=true to show what requirements will be used for compatibility checks. For examples, see Show compatibility requirements in effect for a subject.
Request JSON Object:
 
  • alias (string) – If alias is specified, shows the alias for the subject. References to this subject will be replaced by the alias. To learn more, see Subject aliases.
  • normalize (boolean) – If true, then schemas are automatically normalized when registered or when passed during lookups. The default is false. To learn more, see Schema normalization.
  • compatibilityLevel (string) – Shows compatibility level level for the subject. Returns one of BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, NONE
  • compatibilityGroup (string) – Shows compatibility group, if any is specified. Only schemas that belong to the same compatibility group will be checked for compatibility. To learn more, see Configuration Enhancements in Data Contracts.
  • defaultMetadata (object) – Default value for the metadata to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
  • overrideMetadata (object) – Override value for the metadata to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
  • defaultRuleSet (object) – Default value for the ruleSet to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
  • overrideRuleSet (object) – Override value for the ruleSet to be used during schema registration. To learn more, see Configuration Enhancements in Data Contracts.
Status Codes:

Example request:

GET /config/test HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
   "compatibilityLevel": "FULL"
}
DELETE /config/(string: subject)

Deletes the specified subject-level compatibility level config and reverts to the global default.

Parameters:
  • subject (string) – Name of the subject
Status Codes:

Example request:

DELETE /config/test HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
   "compatibility": "NONE"
}

Exporters

These APIs are already available to support both Schema Linking on Confluent Platform and Schema Linking on Confluent Cloud.

To enable Schema Linking for Confluent Platform, set the configuration properties shown below.

resource.extension.class=io.confluent.schema.exporter.SchemaExporterResourceExtension
kafkastore.update.handlers=io.confluent.schema.exporter.storage.SchemaExporterUpdateHandler
password.encoder.secret=mysecret

Also, to allow for more than 10 exporters (the default maximum) to be created, you can set

exporter.max.exporters=1000

The exporters resource allows you to query the information or manipulate the lifecycle of schema exporters.

GET /exporters

Gets a list of schema exporters that have been created.

Response JSON Array of Objects:
 
  • name (string) – Name of the exporter

Example request:

GET /exporters HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

["exporter1", "exporter2"]
GET /contexts

Gets a list of contexts. The list will always include the default context, and any custom contexts that were created in the registry.

Response JSON Array of Objects:
 
  • name (string) – Name of the context
Status Codes:

Example request:

GET /contexts HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

[":.:", ".mycontext"]
POST /exporters

Creates a new schema exporter. All attributes in request body are optional except config.

Request JSON Object:
 
  • name (string) – Name of the exporter
  • contextType (string) – Context type of the exporter. One of CUSTOM, NONE or AUTO (default)
  • context (string) – Context of the exporter if contextType equals CUSTOM
  • subjects[i] (string) – Name of each exporter subject
  • kekRenameFormat (string) – Format string for the KEK name in the destination cluster, which may contain ${kek} as a placeholder for the originating KEK name. For example, dc_${kek} for the KEK aws_key will map to the destination KEK name dc_aws_key.
  • subjectRenameFormat (string) – Format string for the subject name in the destination cluster, which may contain ${subject} as a placeholder for the originating subject name. For example, dc_${subject} for the subject orders will map to the destination subject name dc_orders.
  • config (map) – The map containing exporter’s configurations
Response JSON Object:
 
  • name (string) – Name of the exporter
Status Codes:
  • 409 Conflict –
    • Error code 40950 – Missing or invalid exporter name
    • Error code 40951 – Missing or invalid exporter config
    • Error code 40952 – Invalid exporter subjects
    • Error code 40960 – Exporter already exists
    • Error code 40964 – Too many exporters

Example request:

POST /exporters HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

{
  "name": "test-exporter",
  "contextType": "CUSTOM",
  "context": "test-context",
  "subjects": ["foo"],
  "config": {
    "schema.registry.url": "<Physical SR Endpoint>",
    "basic.auth.credentials.source": "USER_INFO",
    "basic.auth.user.info": "<SR Credentials>"
  }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "name": "test-exporter"
}
PUT /exporters/(string: name)

Updates the information or configurations of the schema exporter. All attributes in request body are optional.

Parameters:
  • name (string) – Name of the exporter
Request JSON Object:
 
  • contextType (string) – Context type of the exporter. One of CUSTOM, NONE or AUTO. Optional
  • context (string) – Context of the exporter if contextType equals CUSTOM
  • subjects[i] (string) – Name of each exporter subject
  • kekRenameFormat (string) – Format string for the KEK name in the destination cluster, which may contain ${kek} as a placeholder for the originating KEK name. For example, dc_${kek} for the KEK aws_key will map to the destination KEK name dc_aws_key.
  • subjectRenameFormat (string) – Format string for the subject name in the destination cluster, which may contain ${subject} as a placeholder for the originating subject name. For example, dc_${subject} for the subject orders will map to the destination subject name dc_orders.
  • config (map) – The map containing exporter’s configurations
Response JSON Object:
 
  • name (string) – Name of the exporter
Status Codes:
  • 404 Not Found –
    • Error code 40450 – Exporter not found
  • 409 Conflict –
    • Error code 40952 – Invalid exporter subjects
    • Error code 40963 – Exporter not paused

Example request:

PUT /exporters/test-exporter HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

{
  "contextType": "CUSTOM",
  "context": "test-context"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "name": "test-exporter"
}
PUT /exporters/(string: name)/config

Updates the configurations of the schema exporter.

Note

The payload is not wrapped in {"config": {}} as in the POST request. The configuration is directly provided.

Parameters:
  • name (string) – Name of the exporter
Request JSON Object:
 
  • config (map) – The map containing exporter’s configurations
Response JSON Object:
 
  • name (string) – Name of the exporter
Status Codes:

Example request:

PUT /exporters/test-exporter/config HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

{
  "schema.registry.url": "<Physical SR Endpoint>",
  "basic.auth.credentials.source": "USER_INFO",
  "basic.auth.user.info": "<SR Credentials>"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "name": "test-exporter"
}
GET /exporters/(string: name)

Gets the information of the schema exporter.

Parameters:
  • name (string) – Name of the exporter
Response JSON Object:
 
  • name (string) – Name of the exporter
  • contextType (string) – Context type of the exporter. One of CUSTOM, NONE or AUTO (default)
  • context (string) – Customized context of the exporter if contextType equals CUSTOM.
  • subjects[i] (string) – Name of each exporter subject
  • subjectRenameFormat (string) – Format string for the subject name in the destination cluster, which may contain ${subject} as a placeholder for the originating subject name
  • config (map) – The map containing exporter’s configurations
Status Codes:

Example request:

GET /exporters/test-exporter HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "name": "test-exporter",
  "contextType": "CUSTOM",
  "context": "test-context",
  "subjects": ["foo"],
  "config": {
    "schema.registry.url": "<Physical SR Endpoint>",
    "basic.auth.credentials.source": "USER_INFO",
    "basic.auth.user.info": "[hidden]"
  }
}

Note

The credentials in the response will be replaced with [hidden], meaning no one is able to query the credentials through the API.

GET /exporters/(string: name)/status

Gets the status of the schema exporter.

Parameters:
  • name (string) – Name of the exporter
Response JSON Object:
 
  • name (string) – Name of the exporter
  • state (string) – State of the exporter. Could be STARTING, RUNNING or PAUSED
  • offset (long) – Offset of the exporter
  • ts (long) – Timestamp of the exporter
  • trace (string) – Error trace of the exporter
Status Codes:

Example request:

GET /exporters/test-exporter/status HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "name": "test-exporter",
  "state": "RUNNING",
  "offset": 100,
  "ts": 1631206325,
  "trace": ""
}
GET /exporters/(string: name)/config

Gets the configurations of the schema exporter.

Note

The response payload is not wrapped in {"config": {}} as in the POST request. The configuration is directly provided.

Parameters:
  • name (string) – Name of the exporter
Response JSON Object:
 
  • config (map) – The map containing exporter’s configurations
Status Codes:

Example request:

GET /exporters/test-exporter/config HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "schema.registry.url": "<Physical SR Endpoint>",
  "basic.auth.credentials.source": "USER_INFO",
  "basic.auth.user.info": "[hidden]"
}
PUT /exporters/(string: name)/pause

Pauses the schema exporter.

Parameters:
  • name (string) – Name of the exporter
Response JSON Object:
 
  • name (string) – Name of the exporter
Status Codes:

Example request:

PUT /exporters/test-exporter/pause HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "name": "test-exporter"
}
PUT /exporters/(string: name)/reset

Resets the schema exporter.

Parameters:
  • name (string) – Name of the exporter
Response JSON Object:
 
  • name (string) – Name of the exporter
Status Codes:

Example request:

PUT /exporters/test-exporter/reset HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "name": "test-exporter"
}
PUT /exporters/(string: name)/resume

Resumes the schema exporter.

Parameters:
  • name (string) – Name of the exporter
Response JSON Object:
 
  • name (string) – Name of the exporter
Status Codes:

Example request:

PUT /exporters/test-exporter/resume HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.schemaregistry.v1+json

{
  "name": "test-exporter"
}
DELETE /exporters/(string: name)

Deletes the schema exporter.

Parameters:
  • name (string) – Name of the exporter
Status Codes:

Example request:

DELETE /exporters/test-exporter HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json

Example response:

HTTP/1.1 204 No Content

Related Content