Register Schema
POST /subjects/$SUBJECT/versions?normalize=[true/false]
Registers the schema under given $SUBJECT
only if the new schema is compatible.
normalize
is false by default. If passed, the schema will be normalized.
Normalization enables semantically same but syntactically different schemas to be accounted as the same schema.
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/$SUBJECT/versions -u myuser:mypass -d '
{
"schema": "{
\"type\": \"record\",
\"name\": \"myRecord\",
\"fields\":
[
{\"type\": \"string\",\"name\": \"field1\"},
{\"type\": \"int\" ,\"name\": \"field2\"}
]
}",
"schemaType": "AVRO"
}'
Success Response:
The schema ID returned as the response:
Fail Response:
- 409 Conflict – Incompatible schema
- 422 Unprocessable Entity
- Error code 42201 – Invalid 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 primary
Check schema
POST /subjects/$SUBJECT?normalize=[true/false]&deleted=[true/false]
Check if the given schema is registered under the $SUBJECT
. Returns the schema along with subject, version, and schema type.
normalize
is false by default. If set to true
, the schema will be normalized.
Normalization enables semantically same but syntactically different schemas to be accounted as the same schema.
deleted
is false by default. If set to true
, the soft-deleted schemas under the subject will also be taken into account.
See Delete Subject or Delete Schema for details.
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/my-subject/$SUBJECT -u myuser:mypass -d '
{
"schema": "{
\"type\": \"record\",
\"name\": \"myRecord\",
\"fields\":
[
{\"type\": \"string\",\"name\": \"field1\"},
{\"type\": \"int\" ,\"name\": \"field2\"}
]
}",
"schemaType": "AVRO"
}'
**Success Response:**
```json
{
"subject": "my-subject",
"id": 2
"version": 3
"schema":
"
{
"schema": "{
\"type\": \"record\",
\"name\": \"myRecord\",
\"fields\":
[
{\"type\": \"string\",\"name\": \"field1\"},
{\"type\": \"int\" ,\"name\": \"field2\"}
]
}",
"schemaType": "AVRO"
}
"
}
Fail Response
- 404 Not Found
- Error code 40401 – Subject not found
- Error code 40403 – Schema not found
- 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 primary
Set Config
PUT /config
Sets the global compatibility. Global compatibility is effective if a subject is not assigned a compatibility by default.
See Compatibility for options.
curl -X PUT https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/config -u myuser:mypass -d '
{
"compatibility" : "FULL"
}'
PUT /config/$SUBJECT
Sets the compatibility of a subject.
See Compatibility for options.
curl -X PUT https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/config/my-subject -u myuser:mypass -d '
{
"compatibility" : "FULL"
}'
Success Response:
{
"compatibilityLevel" : "FULL"
}
Fail Response
- 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 primary
Get Config
GET /config
Retrieves the global config. Note that the default global config is BACKWARD_TRANSITIVE
by default if not set.
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/config -u myuser:mypass
GET /config/$SUBJECT?defaultToGlobal=[true/false]
Retrieves the config of the given $SUBJECT
.
defaultToGlobal
is false by default. When set to true
, this endpoint will show the effective compatibility on a register
operation. When set to false
, it may return 404 Not found if a subject level compatibility is not set.
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/config/my-subject -u myuser:mypass
Success Response:
{
"compatibilityLevel" : "FULL"
}
Fail Response
- 404 Not Found – Subject not found
- 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 primary
Get All Schemas
GET /schemas?deleted=[false/true]
Returns all schemas registered under subjects. Note that this endpoint will return the same schema multiple times if the same schema registered
under different subjects.
deleted
is false by default. If set to true
, the soft-deleted schemas under the subject will also be taken into account.
See Delete Subject or Delete Schema for details.
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/schemas -u myuser:mypass
Success Response:
[
{
"subject": "subject1",
"version": 1,
"id": 1,
"schemaType": "AVRO",
"schema": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"}]}"
},
{
"subject": "subject2",
"version": 1,
"id": 2,
"schemaType": "AVRO",
"schema": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"},{\"name\":\"field2\",\"type\":\"string\",\"default\":\"x\"}]}"
}
]
Fail Response
- 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 primary
Get Schema With SchemaId
GET /schemas/ids/$SCHEMA_ID
Returns the schema corresponding to the given $SCHEMA_ID
.
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/schema/ids/1 -u myuser:mypass
Success Response:
{
"schema": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"}]}"
}
Fail Response
- 404 Not Found
- Error code 40403 – Schema not found
- 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 primary
GET /schemas/ids/$SCHEMA_ID/schema
Returns the schema corresponding to the given $SCHEMA_ID
. Additionally unwraps the inner schema field.
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/schema/ids/1/schema -u myuser:mypass
Success Response:
{
"type": "record",
"name": "test",
"fields": [
{
"name": "field1",
"type": "string"
}
]
}
Fail Response
- 404 Not Found
- Error code 40403 – Schema not found
- 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 primary
Get Schema With Subject And Version
GET /subjects/$SUBJECT/versions/$VERSION?deleted=[true/false]
Returns the schema with its metadata corresponding to the given $SUBJECT
and $VERSION
.
VERSION could be an int or string latest
.
deleted
is false by default. If set to true
, the soft-deleted schemas under the subject will also be taken into account.
See Delete Subject or Delete Schema for details.
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/subject1/versions/1 -u myuser:mypass
Success Response:
{
"subject": "s1",
"version": 1,
"id": 1,
"schemaType": "AVRO",
"schema": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"}]}"
}
Fail Response
- 404 Not Found
- Error code 40403 – Schema not found
- 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 primary
GET /subjects/$SUBJECT/versions/$VERSION?deleted=[true/false]
Returns only the schema corresponding to the given $SUBJECT
and $VERSION
.
VERSION could be an int or string latest
.
deleted
is false by default. If set to true
, the soft-deleted schemas under the subject will also be taken into account.
See Delete Subject or Delete Schema for details.
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/subject1/versions/1/schema -u myuser:mypass
Success Response:
{
"type": "record",
"name": "test",
"fields": [
{
"name": "field1",
"type": "string"
}
]
}
Fail Response
- 404 Not Found
- Error code 40401 – Subject not found
- Error code 40402 – Version not found
- 422 Unprocessable Entity
- Error code 42202 – Invalid version
- 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 primary
Get All Subjects
GET /subjects?deleted=[false/true]
Returns all subjects.
deleted
is false by default. If set to true
, the soft-deleted subjects will also be taken into account.
See Delete Subject or Delete Schema for details.
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects -u myuser:mypass
Success Response:
Fail Response
- 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 primary
Get Subject Versions
GET /subjects/$SUBJECT/versions?deleted=[false/true]
Returns the versions of the given $SUBJECT
.
deleted
is false by default. If set to true
, the soft-deleted subject versions will also be taken into account.
See Delete Subject or Delete Schema for details.
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/subject1/versions -u myuser:mypass
Success Response:
Fail Response
- 404 Not Found
- Error code 40401 – Subject not found
- 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 primary
Delete Subject
DELETE /subjects/$SUBJECT?permanent=[true/false]
Deletes the given $SUBJECT
. Returns the deleted versions as the response.
This endpoint should rarely be needed in production and needs to be used with caution.
The use-case for this endpoint is mostly cleaning up the resources after testing in development environments.
permanent
is false by default. In this case, the subject only will be soft-deleted. The corresponding schemas and schema-ids
will not be deleted. Any serializer/deserializer needing these schemas still will be able to use them.
if permanent
is set to true. The schemas and schema-ids will also be deleted from the system only if these schemas are not
registered under any other subjects. The schemas will be deleted only after the last related subject is permanently deleted.
Note that a subject can not be permanently deleted before it is soft-deleted.
curl -X DELETE https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/my-subject -u myuser:mypass
Success Response:
Returns the deleted versions as the response.
Fail Response:
- 404 Not Found
- Error code 40401 – Subject not found
- Error code 40404 - Subject '$SUBJECT' was soft deleted. Set permanent=true to delete permanently
- Error code 40405 - Subject '$SUBJECT' was not deleted first before being permanently deleted
- 422 Unprocessable Entity
- Error code 42202 – Invalid version
- 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 primary
Delete Schema
DELETE /subjects/$SUBJECT/versions/$VERSION?permanent=[true/false]
Deletes the schema corresponding to the $SUBJECT
and $VERSION
. Returns the version as the response.
VERSION could be an int or string latest
.
This endpoint should rarely be needed in production and needs to be used with caution.
The use-case for this endpoint is mostly cleaning up the resources after testing in development environments.
permanent
is false by default. In this case, the subject-version only will be soft-deleted. The corresponding schema and schema-id
will not be deleted. Any serializer/deserializer needing this schema still will be able to use them.
if permanent
is set to true. The schema and schema-id will also be deleted from the system only if this schema is not
registered under any other subjects. The schemas will be deleted only after the last related subject is permanently deleted.
Note that a subject-version can not be permanently deleted before it is soft-deleted.
curl -X DELETE https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/my-subject/versions/2 -u myuser:mypass
Success Response:
Returns the deleted version as the response.
Fail Response:
- 404 Not Found
- Error code 40401 – Subject not found
- Error code 40402 – Version not found
- Error code 40406 - Subject '$SUBJECT' Version $VERSION was soft deleted. Set permanent=true to delete permanently
- Error code 40407 - Subject '$SUBJECT' Version $VERSION was not deleted first before being permanently deleted
- 422 Unprocessable Entity
- Error code 42202 – Invalid version
- 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 primary