API Reference

Overview

Compatibility

The schema registry server can enforce certain compatibility rules when new schemas are registered in a subject. Currently, we support the following compatibility rules.

  • Backward compatibility (default): A new schema is backward compatible if it can be used to read the data written in all previous schemas. Backward compatibility is useful for loading data into systems like Hadoop since one can always query data of all versions using the latest schema.
  • Forward compatibility: A new schema is forward compatible if all previous schemas can read data written in this schema. Forward compatibility is useful for consumer applications that can only deal with data in a particular version that may not always be the latest version.
  • Full compatibility: A new schema is fully compatible if it’s both backward and forward compatible.
  • No compatibility: A new schema can be any schema as long as it’s a valid Avro.

We recommend keeping the default backward compatibility since it’s common to have all data loaded into Hadoop.

More details on Avro schema resolution can be found here.

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.

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

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 the 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
]
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:
 
  • name (string) – Name of the subject that this schema is registered under
  • version (int) – Version of the returned schema
  • schema (string) – The Avro 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\"}"
}
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 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 master. If the master is not available, the client will get an error code indicating that the forwarding has failed.

Parameters:
  • subject (string) – Subject under which the schema will be registered
Request JSON Object:
 
  • schema – The Avro schema string
Status Codes:
  • 409 Conflict – Incompatible Avro schema
  • 422 Unprocessable Entity –
    • Error code 42201 – Invalid Avro schema
  • 500 Internal Server Error –
    • Error code 50001 – Error in the backend data store
    • Error code 50002 – Operation timed out
    • Error code 50003 – Error while forwarding the request to the master

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\": \"integer\",
             \"name\": \"field2\"
           }
         ]
     }"
}

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 Avro 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\": \"integer\",
                      \"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\": \"integer\",
                      \"name\": \"field2\"
                    }
                  ]
              }"
    }

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\": \"integer\",
             \"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 master. If the master 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 NONE, FULL, FORWARD, BACKWARD
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.

Response JSON Object:
 
  • compatibility (string) – New global compatibility level. Will be one of NONE, FULL, FORWARD, BACKWARD
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

{
  "compatibility": "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 global compatibility level. Must be one of NONE, FULL, FORWARD, BACKWARD
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
Response JSON Object:
 
  • compatibility (string) – New global compatibility level. Will be one of NONE, FULL, FORWARD, BACKWARD
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

{
   "compatibility": "FULL"
}