Schema Registry API Reference

Overview

This section provides a detailed reference for the Schema Registry API. For example API calls using curl, see Schema Registry API Usage Examples. You can also see curl API calls used to test the serializers and deserializers for different schema formats in Schema Formats, Serializers, and Deserializers and in the Schema Registry Tutorial.

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.

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 development environment.

Parameters:
  • subject (string) – the name of the subject
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”. “latest” 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”. “latest” 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. 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. The configured compatibility level can be obtained by issuing a GET http:get:: /config/(string: subject). If that returns null, then GET http:get:: /config

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)
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\": \"field2\"
           }
         ]
     }",
  "schemaType": "AVRO"
}

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. This only deletes the version and the schema ID remains intact 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”. “latest” 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.
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”. “latest” 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
]

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”. “latest” 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.

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.

Parameters:
  • subject (string) – Name of the 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 sets limits on the number of schema versions supported in the registry, as listed in Supported Features for Confluent Cloud.

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

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.

If your Schema Registry reaches the maximum schemas limit, you can free up space for additional schemas as follows:

  1. Back up the schemas you want to keep, by using GET /subjects/(string: subject)/versions/latest.

  2. Delete all subjects.

    curl -X DELETE -u <schema-registry-api-key>:<schema-registry-api-secret> <schema-registry-url>/subjects/my-existing-subject
    
  3. Verify that no subjects exist.

    curl -u <schema-registry-api-key>:<schema-registry-api-secret> <schema-registry-url>/subjects
    

    If no subjects exist, your output will be empty ([]), which is what you want.

  4. Set the destination Schema Registry to IMPORT mode. For example:

    curl -u <schema-registry-api-key>:<schema-registry-api-secret> -X PUT -H "Content-Type: application/json" "https://<destination-schema-registry>/mode" --data '{"mode": "IMPORT"}'
    

    Tip

    If subjects exist on the destination Schema Registry, the import will fail with a message similar to this: {"error_code":42205,"message":"Cannot import since found existing subjects"}

  5. Restore all schemas.

    To restore a schema with the same ID and version, use the REST API to pass both the old ID and the old version while registering the schema. Use the API with a complete payload, but without the subject field, since the subject name will be determined from the URL.

    For example, given a file called schema.json:

    {
      "id": 1,
      "version": 3,
      "schema":
        "{
           "type": "record",
           "name": "test",
           "fields":
             [
               {
                 "type": "string",
                 "name": "field1"
               },
               {
                 "type": "int",
                 "name": "field2"
               }
             ]
         }"
    }
    

    This command will perform the back up and restore of this schema at version 3:

    curl --verbose -XPOST -u <schema-registry-api-key>:<schema-registry-api-secret>  -H "Content-Type: application/vnd.schemaregistry.v1+json" <destination-schema-registry>/subjects/my-existing-subject/versions/ -d @schema.json
    
  6. Set Schema Registry to READ-WRITE mode.

    curl -u <schema-registry-api-key>:<schema-registry-api-secret> -X PUT -H "Content-Type: application/json" "https://<destination-schema-registry>/mode" --data '{"mode": "READWRITE"}'