Confluent Cloud Schema Registry REST API Usage Examples¶
The Schema Registry REST API allows you to register new schemas, list, look up, and delete schemas and subjects, and view these entities by version, by ID, and more. For the full API reference, see Schemas (V1) and Subjects (V1).
Setup and Suggestions¶
You’ll need to know the following to make API calls to the Schemas (V1) and Subjects (V1) APIs per the usage examples provided here:
API endpoint URL for the Confluent Cloud Schema Registry cluster in the environment you want to use. In the examples below, this is typically referred to as the
<SCHEMA-REGISTRY-URL>
or$SCHEMA_REGISTRY_URL
. To find this on the Cloud Console, navigate an environment and locate Stream Governance API > Endpoint on the right panel. Alternatively, log on to Confluent Cloud with the Confluent CLI, make sure you have the appropriate environment selected (confluent env list
,confluent env use <environment-ID>
), and enterconfluent schema-registry cluster describe
. (A handy list of CLI commands is here.)If you are using an API keys, you need an API key and secret for Schema Registry in the environment you want to use. (If needed, see Create an API Key for Confluent Cloud Schema Registry.) Schema subjects live at the level of an environment, in per-environment Schema Registry clusters, so just choose the environment that contains the Kafka clusters you want to use.
If you are using OAuth, you must provide your access token for authorization in the proper format, as described in Access token format. An OAuth example is provided below.
To get properly formatted output for search calls that include question mark (
?
) or ampersand (&
), you must enclose the URL and search parameters in either single or double quotes so that the shell does not interpret them This syntax is also shown in the examples.(Optional) You may want to store your API keys and Schema Registry URL in local shell environment variables to make testing easier. For example, to store your API key and secret:
$MYCOOLKEYS=xyz:abc
You can check the contents of the variable with
echo $MYCOOLKEYS
then, use it for authorization in subsequent commands:curl --silent -u $MYCOOLKEYS -X POST -H "Content-Type: application/json" ...
.(Optional) For your API testing, you may want to use the
--silent
flag with the curl commands and pipe the entire command through jq . to get nicely formatted output. If you don’t use--silent
andjq
, the content of the output will be the same, it just won’t be formatted as human-friendly readable. (See the Stream Catalog REST API Usage and Examples on Confluent Cloud documentation for examples of using these options.)(Optional) A Confluent Cloud login is handy for comparing API results with the Confluent Cloud Console (https://confluent.cloud/).
OAuth for Confluent Cloud Schema Registry REST API¶
Confluent Cloud Schema Registry REST API now supports OAuth, an open-standard authorization protocol for secure access. To learn more about OAuth, see Use OAuth/OIDC to Authenticate to Confluent Cloud and Configure Schema Registry clients for OAuth.
Here is an example of using Oauth to get a list of subjects from Confluent Cloud Schema Registry. The generated reference documentation for this API is here.
curl --request GET '<SCHEMA-REGISTRY-URL>/subjects/' \
--header 'Confluent-Identity-Pool-Id: <POOL-ID>' \
--header 'target-sr-cluster: <CLUSTER-ID' \
--header 'Authorization: Bearer $TOKEN'
The rest of the examples on this page use an API key and secret. If you want to use OAuth instead,
remove the -u <API-KEY>:<API-SECRET>
and follow the format shown above (specify identity pool ID, Schema Registry cluster, and OAuth bearer token).
Schemas (V1) API Usage Examples¶
Get schema string by ID¶
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET \
--url '$SCHEMA_REGISTRY_URL/schemas/ids/<schema-ID>?subject=SOME_STRING_VALUE&format=SOME_STRING_VALUE&fetchMaxId=<true|false>'
For example, the following call gets the schema my-flights
, which is associated with the schema ID 100015:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/schemas/ids/100015?subject=flights&format=Avro&fetchMaxId=true | jq .
The resulting output is:
[1] 55714
[2] 55715
[2]+ Done format=Avro
{"schema":"{\"type\":\"record\",\"name\":\"sampleRecord\",\"namespace\":\"com.mycorp.mynamespace\",\"doc\":\"Sample schema to help you get started.\",\"fields\":[{\"name\":\"my_field1\",\"type\":\"int\",\"doc\":\"The int type is a 32-bit signed integer.\"},{\"name\":\"my_field2\",\"type\":\"double\",\"doc\":\"The double type is a double precision (64-bit) IEEE 754 floating-point number.\"},{\"name\":\"my_field3\",\"type\":\"string\",\"doc\":\"The string is a unicode character sequence.\"}]}"}
Get schema by ID¶
GET /schemas/ids/{schema-ID}/schema
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET \
--url '$SCHEMA_REGISTRY_URL/schemas/ids/<schema-ID>/schema?subject=SOME_STRING_VALUE&format=SOME_STRING_VALUE'
For example, to list the schema associated with the ID 100018:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/schemas/ids/100018/ | jq .
The output is the schema:
"schema": "{\"type\":\"record\",\"name\":\"Employee\",\"namespace\":\"Example\",\"fields\":[{\"name\":\"Name\",\"type\":\"string\"},{\"name\":\"Age\",\"type\":\"int\"},{\"name\":\"Country\",\"type\":\"string\",\"default\":\"\"}]}"
List supported schema types¶
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/schemas/types | jq .
Example output:
"JSON",
"PROTOBUF",
"AVRO"
Tip
If you do not filter this through jq
, the output will resemble: ["JSON","PROTOBUF","AVRO"]
List schemas¶
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET \
--url '$SCHEMA_REGISTRY_URL/schemas?subjectPrefix=<SOME_STRING_VALUE>&deleted=<true|false>&latestOnly=<true|false>&offset=<SOME_INTEGER_VALUE>&limit=<SOME_INTEGER_VALUE>'
For example, to list all existing versions of schemas starting with subjectPrefix of my-cool
and show the subject and schema for each:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/schemas?subjectPrefix=my | jq .
Here is an example of partial output:
{
"subject": "my-cool-subject",
"version": 2,
"id": 100018,
"schema": "{\"type\":\"record\",\"name\":\"Employee\",\"namespace\":\"Example\",\"fields\":[{\"name\":\"Name\",\"type\":\"string\"},{\"name\":\"Age\",\"type\":\"int\"},{\"name\":\"Country\",\"type\":\"string\",\"default\":\"\"}]}"
},
{
"subject": "my-cooler-subject",
"version": 2,
"id": 100020,
"schema": "{\"type\":\"record\",\"name\":\"Employees\",\"namespace\":\"my.examples\",\"fields\":[{\"name\":\"Name\",\"type\":\"string\"},{\"name\":\"Age\",\"type\":\"int\"},{\"name\":\"region\",\"type\":\"string\",\"default\":\"\"}]}"
},
{
"subject": "my-cooler-subject",
"version": 3,
"id": 100021,
"schema": "{\"type\":\"record\",\"name\":\"Employees\",\"namespace\":\"my.examples\",\"fields\":[{\"name\":\"Name\",\"type\":\"string\"},{\"name\":\"Age\",\"type\":\"int\"},{\"name\":\"region\",\"type\":\"string\",\"default\":\"\"},{\"name\":\"Team\",\"type\":\"string\",\"default\":\"\"}]}"
},
...
List subjects associated to a schema ID¶
GET /schemas/ids/{schema-ID}/subjects
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/schemas/ids/<schema-ID>/subjects
For example, to list the subject associated with ID 100018:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/schemas/ids/100018/subjects
The output is:
["my-cool-subject"]
List subject-versions associated to schema ID¶
GET /schemas/ids/{schema-ID}/versions
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET \
--url '$SCHEMA_REGISTRY_URL/schemas/ids/<schema-ID>/versions?subject=SOME_STRING_VALUE&deleted=<true|false>'
For example, the following call retrieves the subject-version associated with schema ID 100008:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url \
$SCHEMA_REGISTRY_URL/schemas/ids/100008/versions?subject=stock | jq .
The output shows that version 2 of stocks-value
is associated with the given ID:
{
"subject": "stocks-value",
"version": 2
}
Subjects (V1) API Usage Examples¶
List all subjects¶
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/subjects | jq .
Here is example output, showing a list of subjects in the registry.
"hamburgers",
"my-cool-subject",
"stocks_sell-value",
"Team",
"hamburger-test",
"accounts-value",
"stocks-value",
"stocks_under_100-value",
"employees-value",
"flights-value",
"my-widget-value",
"stocks_buy-value",
"my-flights-value",
"my-cooler-subject",
"my-new-widget-value",
"Hotdogs",
"my-value"
List subject matching a given prefix¶
For example, list all versions of subjects starting with my-cool
:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/schemas?subjectPrefix=my | jq .
Here is an example of partial output:
{
"subject": "my-cool-subject",
"version": 2,
"id": 100018,
"schema": "{\"type\":\"record\",\"name\":\"Employee\",\"namespace\":\"Example\",\"fields\":[{\"name\":\"Name\",\"type\":\"string\"},{\"name\":\"Age\",\"type\":\"int\"},{\"name\":\"Country\",\"type\":\"string\",\"default\":\"\"}]}"
},
{
"subject": "my-cooler-subject",
"version": 2,
"id": 100020,
"schema": "{\"type\":\"record\",\"name\":\"Employees\",\"namespace\":\"my.examples\",\"fields\":[{\"name\":\"Name\",\"type\":\"string\"},{\"name\":\"Age\",\"type\":\"int\"},{\"name\":\"region\",\"type\":\"string\",\"default\":\"\"}]}"
},
{
"subject": "my-cooler-subject",
"version": 3,
"id": 100021,
"schema": "{\"type\":\"record\",\"name\":\"Employees\",\"namespace\":\"my.examples\",\"fields\":[{\"name\":\"Name\",\"type\":\"string\"},{\"name\":\"Age\",\"type\":\"int\"},{\"name\":\"region\",\"type\":\"string\",\"default\":\"\"},{\"name\":\"Team\",\"type\":\"string\",\"default\":\"\"}]}"
},
...
Get schema by version¶
GET /subjects/{subject}/versions/{version}
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET \
--url $SCHEMA_REGISTRY_URL/subjects/<subject>/versions/<version>?deleted=<true|false>
For example, to get version 2 of schema “my-cool-subject”:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET $SCHEMA_REGISTRY_URL/subjects/my-cool-subject/versions/2
The result will be similar to the following, where the requested version of the schema is returned:
{"subject":"my-cool-subject","version":2,"id":100018,"schema":"{\"type\":\"record\",\"name\":\"Employee\",\"namespace\":\"Example\",\"fields\":[{\"name\":\"Name\",\"type\":\"string\"},{\"name\":\"Age\",\"type\":\"int\"},{\"name\":\"Country\",\"type\":\"string\",\"default\":\"\"}]}"}
To retrieve a version of the schema that has been deleted (for example version 1 of my-cool-subject), use the following call:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET $SCHEMA_REGISTRY_URL/subjects/my-cool-subject/versions/1?deleted=true
The requested version of the deleted schema is returned in the result:
{"subject":"my-cool-subject","version":1,"id":100004,"schema":"{\"type\":\"record\",\"name\":\"Employee\",\"namespace\":\"Example\",\"fields\":[{\"name\":\"Name\",\"type\":\"string\"},{\"name\":\"Age\",\"type\":\"int\"}]}"}
Get the latest version of a schema with its schema ID¶
GET /subjects/{subject}/versions/{version}
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET \
--url $SCHEMA_REGISTRY_URL/subjects/<subject>/versions/<version>?deleted=<true|false>
For example, to get the latest version of the schema for the “stocks” topic:
curl -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/subjects/stocks-value/versions/latest
The output resembles the following:
{"subject":"stocks-value","version":2,"id":100008,"schema":"{\"type\":\"record\",\"name\":\"StockTrade\",\"namespace\":\"ksql\",\"doc\":\"Defines a hypothetical stock trade using some known test stock symbols.\",\"fields\":[{\"name\":\"side\",\"type\":\"string\",\"doc\":\"A simulated trade side (buy or sell or short)\"},{\"name\":\"quantity\",\"type\":\"int\",\"doc\":\"A simulated random quantity of the trade\"},{\"name\":\"symbol\",\"type\":\"string\",\"doc\":\"Simulated stock symbols\"},{\"name\":\"price\",\"type\":\"int\",\"doc\":\"A simulated random trade price in pennies\"},{\"name\":\"account\",\"type\":\"string\",\"doc\":\"Simulated accounts assigned to the trade\"},{\"name\":\"userid\",\"type\":\"string\",\"doc\":\"The simulated user who executed the trade\"}],\"connect.parameters\":{\"io.confluent.connect.avro.record.doc\":\"Defines a hypothetical stock trade using some known test stock symbols.\",\"io.confluent.connect.avro.field.doc.side\":\"A simulated trade side (buy or sell or short)\",\"io.confluent.connect.avro.field.doc.quantity\":\"A simulated random quantity of the trade\",\"io.confluent.connect.avro.field.doc.symbol\":\"Simulated stock symbols\",\"io.confluent.connect.avro.field.doc.price\":\"A simulated random trade price in pennies\",\"io.confluent.connect.avro.field.doc.account\":\"Simulated accounts assigned to the trade\",\"io.confluent.connect.avro.field.doc.userid\":\"The simulated user who executed the trade\"},\"connect.name\":\"ksql.StockTrade\"}"}
List schemas referencing a schema¶
GET /subjects/{subject}/versions/{version}/referencedby
curl -u <API-KEY>:<API-SECRET> --request GET \
--url <SCHEMA-REGISTRY-URL>/subjects/<subject>/versions/<version>/referencedby
For example, the following call returns the schema IDs for schemas that reference version 1 of the employees-value
schema:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/subjects/employees-value/versions/1/referencedby
The output is 100027
which is the schema ID for the widget-value
schema:
[100027]
There are a few ways to get subjects associated with schema IDs; the most direct is to List subjects associated to a schema ID using the following API call:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/schemas/ids/<schema-ID>/subjects
(You could also list all schemas, but that would mean culling through them all to find the given ID.)
For example, to retrieve the subject associated with the given schema ID of 100027
:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/schemas/ids/100027/subjects
The output is:
["my-widget-value"]
which does reference employees-value
.
If you walked through the full example with the example schemas and subject names or others of your own, you can verify this as follows:
Log on to the Confluent Cloud Console (https://confluent.cloud/).
Navigate to Environments > View & Manage Schemas (on the right side panel), then click the schema that you configured to reference another (in this example,
my-widget-value
).Click Evolve Schema in the upper right. Schemas referenced by the current schema will show under Schema References:
Tip
- To learn how to create schema references from the Confluent Cloud Console, see Work with schema references.
- To learn more about schema references for each supported format, see Schema references.
Get schema string by version¶
GET /subjects/{subject}/versions/{version}/schema
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET\
--url $SCHEMA_REGISTRY_URL/subjects/<subject>/versions/<version>/schema?deleted=<true|false>'
For example, this call returns version 1 of the schema my-cool-subject, which had been deleted:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET \
--url $SCHEMA_REGISTRY_URL/subjects/my-cool-subject/versions/1/schema?deleted=true | jq .
Example output:
{"type":"record","name":"Employees","namespace":"my.examples","fields":[{"name":"Name","type":"string"},{"name":"Age","type":"int"}]}
List versions under subject¶
GET /subjects/{subject}/versions
curl -u $SR_APIKEY:$SR_APISECRET --request GET \
--url <SCHEMA-REGISTRY-URL>/subjects/<subject>/versions?deleted=<true|false>
For example, this call lists all versions for “my-cool-subject”:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/subjects/my-cool-subject/versions
Example output showing all existing versions:
[2,3,4]
This call lists all versions for “my-cool-subjects”, including deleted versions:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/subjects/my-cool-subject/versions?deleted=true
Example output showing all versions, including those that were soft-deleted:
[1,2,3,4]
Register schema under a subject¶
POST /subjects/{subject}/versions
To register a schema, specify a POST request with the following parameters:
- The
--data
flag provides the path to the file. You must include the@
sign before the path with no spaces in between. - Subject name under which to register the schema
curl -u <API-KEY>:<API-SECRET> -X POST -H "Content-Type: application/json" \
--data @/Users/me/my.json <SCHEMA-REGISTRY-URL>/subjects/<subject>/versions
Following is an example file you can pass into the POST request.
{
"version": 0,
"id": 0,
"schemaType": "string",
"references": [
{
"name": "io.confluent.kafka.example.User",
"subject": "User",
"version": 1
}
],
"schema": "string"
}
Lookup schema under subject¶
To look up a schema, specify a POST request with the following parameters:
- The
--data
flag provides the path to the file. You must include the@
sign before the path with no spaces in between. - Subject name under which the schema is registered
curl -u <API-KEY>:<API-SECRET> -X POST -H "Content-Type: application/json" \
--data @/Users/me/my.json <SCHEMA-REGISTRY-URL>/subjects/<subject>
Following is an example file you can pass into the POST request.
{
"version": 0,
"id": 0,
"schemaType": "string",
"references": [
{
"name": "io.confluent.kafka.example.User",
"subject": "User",
"version": 1
}
],
"schema": "string"
}
Delete a subject¶
This example deletes all versions of the subject “my-value”:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request DELETE --url $SCHEMA_REGISTRY_URL/subjects/my-value | jq .
Example result showing versions 1 and 2 were deleted:
1,
2
Delete Version 1 of the schema registered under a subject¶
DELETE /subjects/{subject}/versions/{version}
This example deletes version 1 of a schema subject called “my-cool-subject”.
curl --silent -u $SR_APIKEY:$SR_APISECRET --request DELETE --url $SCHEMA_REGISTRY_URL/subjects/my-cool-subject/versions/1 | jq .
Example result shows the version that was deleted:
1
Recover a soft-deleted schema¶
You can recover a soft-deleted schema as described in Recover a soft-deleted schema.
The following example retrieves all deleted schema subjects:
curl --silent -u $SR_APIKEY:$SR_APISECRET -X GET $SCHEMA_REGISTRY_URL/subjects?deleted=true | jq .
This example re-registers a schema under the subject “my-cool-subject”:
curl --silent -u $SR_APIKEY:$SR_APISECRET -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \ --data '{"schema": "{\"type\":\"record\",\"name\":\"Employee\",\"namespace\":\"Example\",\"fields\":[{\"name\":\"Name\",\"type\":\"string\"},{\"name\":\"Age\",\"type\":\"int\"},{\"name\":\"Country\",\"type\":\"string\",\"default\":\"\"}]}"}' \ $SCHEMA_REGISTRY_URL/subjects/my-cool-subject/versions | jq .
The result is a schema ID:
"id": 100017
Tip
The new schema provided to reregister the schema must be compatible with previously registered versions; otherwise, you will get an error indicating a mismatch in the data.
Delete the most recently registered schema subject under a given subject¶
The following example deletes the latest version registered under the subject widget-value
(which has a total number of four versions as a starting point):
curl --silent -u $SR_APIKEY:$SR_APISECRET --request DELETE --url $SCHEMA_REGISTRY_URL/subjects/widget-value/versions/latest | jq .
Example result shows the version that was deleted:
4
Hard delete a schema¶
To hard delete a schema and free up schema storage space on Confluent Cloud,
first perform a soft delete of all versions of the schema, followed by a hard delete of all versions with the ?permanent=true
flag appended:
The following example executes a soft-delete of all versions registered under the subject
widget-value
:curl --silent -u $SR_APIKEY:$SR_APISECRET --request DELETE --url $SCHEMA_REGISTRY_URL/subjects/widget-value | jq .
The example result shows that versions 1, 2, and 3 were deleted. (You already soft-deleted version 4 in the previous example.):
1, 2, 3
At this point, the schema subject is “soft-deleted”. It doesn’t show on the Confluent Cloud Console or if you list subjects from the API, but it is still taking up space in the registry. To hard-delete it, continue with the next step.
The following example performs a hard-delete of the subject
widget-value
:curl --silent -u $SR_APIKEY:$SR_APISECRET --request DELETE --url $SCHEMA_REGISTRY_URL/subjects/widget-value?permanent=true | jq .
The output indicates that all versions have been permanently deleted:
1, 2, 3, 4
Schema Compatibility (V1) API Usage Examples¶
The following API calls enable you to get and set global and subject level compatibility. To learn about the compatibility types available on Confluent Cloud Schema Registry, see Schema Evolution and Compatibility.
Get the global compatibility level¶
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/config/ | jq .
Example result:
"compatibilityLevel": "BACKWARD"
Update the global compatibility level¶
curl --silent -u $SR_APIKEY:$SR_APISECRET --request PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" \
--data '{"compatibility": "<level>"}' --url $SCHEMA_REGISTRY_URL/config/
For example, to update the global compatibility level to “BACKWARD_TRANSITIVE”:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" \
--data '{"compatibility": "BACKWARD_TRANSITIVE"}' --url $SCHEMA_REGISTRY_URL/config/ | jq .
Example result:
"compatibilityLevel": "BACKWARD_TRANSITIVE"
Now, if you re-run the call to Get the global compatibility level, you will get "compatibilityLevel": "BACKWARD_TRANSITIVE"
in response.
Get the compatibility level on a subject¶
curl --silent -u $SR_APIKEY:$SR_APISECRET --request GET --url $SCHEMA_REGISTRY_URL/config/my-cool-subject | jq .
Example output:
"error_code": 40408,
"message": "Subject 'my-cool-subject' does not have subject-level compatibility configured
Update the subject compatibility level¶
curl --silent -u $SR_APIKEY:$SR_APISECRET --request PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" \
--data '{"compatibility": "<level>"}' --url $SCHEMA_REGISTRY_URL/config/<subject>
For example, to update the compatibility level for my-cool-subject
to “FULL”:
curl --silent -u $SR_APIKEY:$SR_APISECRET --request PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" \
--data '{"compatibility": "FULL"}' --url $SCHEMA_REGISTRY_URL/config/my-cool-subject | jq .
Example result:
"compatibility": "FULL"
Now, if you re-run the call to Get the compatibility level on a subject, you will get "compatibility": "FULL"
in response.