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