Schema Registry API Reference

Overview

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 Schema Formats, Serializers, and Deserializers.

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’s common to have all data loaded into Hadoop.

For more details on schema resolution, see Schema Evolution and Compatibility.

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
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/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 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>-key” or “<topic>-value” depending on whether you are registering the key schema for that topic or the value schema.

Tip

Currently, there is no built-in lookup API to find subjects for a given ID. See List all subjects associated with a given ID for a two-step process to use instead.

GET /subjects

Get a list of registered subjects.

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. See also, 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. See also, Hard delete a schema in Schema Deletion Guidelines, and Schema Registry in Confluent Cloud.
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. Note that there may be a new latest schema that gets registered right after this request is served.
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:

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:

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

{
  "name": "test",
  "version": 1,
  "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. Note that there may be a new latest schema that gets registered right after this request is served.
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.

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
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.
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\": \"int\",
             \"name\": \"com.acme.Referenced\"
           }
          ]
     }",
  "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
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. 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. See also, 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. See also, Hard delete a schema in Schema Deletion Guidelines, and Schema Registry in Confluent Cloud.
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. 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
]

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 are shown as a part of the procedure to Migrate Schemas.

GET /mode

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

Request JSON Object:
 
  • mode (string) – Schema Registry mode. Will be 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.

Request JSON Object:
 
  • mode (string) – New mode. Must be one of IMPORT, READONLY, READWRITE
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
Request JSON Object:
 
  • mode (string) – Mode for the subject. Will be 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
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",
}

Compatibility

The compatibility resource allows the user to test schemas for compatibility against specific versions of a subject’s schema.

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
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
}

Config

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

PUT /config

Update global compatibility level.

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:
 
  • compatibility (string) – New global compatibility level. Must be one of BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, NONE
Status Codes:
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 global compatibility level.

Request JSON Object:
 
  • compatibility (string) – Global compatibility level. Will be one of BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, NONE
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:
 
  • compatibility (string) – New compatibility level for the subject. Must be one of BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, NONE
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:
 
  • compatibility (string) – Compatibility level for the subject. Will be one of BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, NONE
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"
}

Schema Registry in Confluent Cloud

Maximum Schemas Limit

Schema Registry in Confluent Cloud limits the number of schema versions supported in the registry for basic clusters, standard clusters, and dedicated clusters as described in Confluent Cloud Cluster Types.

When the maximum limit is reached and the registry is full, any requests to register new schemas will generate the following HTTP response:

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

{
    "error_code": 403,
    "message": "Schema Limit Exceeded"
}

See the topic below for how you can free up storage space for new schemas if needed.

To learn more about Confluent Cloud features, see Supported Features for Confluent Cloud.

Free Up Storage Space in the Registry for New Schemas

Simply deleting schemas will not free up space in the registry because this will always result in a soft delete and schema IDs are not reusable. The schema count tracks IDs, so the used number will increase as new schemas are added, regardless of whether you soft deleted schemas.

Confluent Cloud now supports “hard delete” of a schema as a two-step process (soft delete, followed by hard delete) with the use of the query string, ?permanent=true on the second delete. If your Schema Registry reaches the maximum schemas limit, you can free up space for additional schemas by following the procedure described in Hard delete a schema in Schema Deletion Guidelines.