Schema Registry REST API for Confluent Cloud

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 referred to as the <SCHEMA-REGISTRY-URL>. You can find this on Cloud Console by navigating to the Schema Registry tab for your environment, or log on to Confluent Cloud with the unified Confluent CLI, make sure you have the appropriate environment selected (confluent env list, confluent env use <environment-ID>), and enter confluent 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 and jq, 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 for 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 OAuth for 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

GET /schemas/ids/{id}

curl -u <API-KEY>:<API-SECRET> --request GET \
--url '<SCHEMA-REGISTRY-URL>/schemas/ids/{id}?subject=SOME_STRING_VALUE&format=SOME_STRING_VALUE&fetchMaxId=SOME_BOOLEAN_VALUE' \

Get schema by ID

GET /schemas/ids/{id}/schema

curl -u <API-KEY>:<API-SECRET> --request GET \
--url '<SCHEMA-REGISTRY-URL>/schemas/ids/{id}/schema?subject=SOME_STRING_VALUE&format=SOME_STRING_VALUE' \

List supported schema types

GET /schemas/types

curl -u <API-KEY>:<API-SECRET> --request GET \
--url <SCHEMA-REGISTRY-URL>/schemas/types \

List schemas

GET /schemas

curl -u <API-KEY>:<API-SECRET> --request GET \
--url '<SCHEMA-REGISTRY-URL>/schemas?subjectPrefix=SOME_STRING_VALUE&deleted=SOME_BOOLEAN_VALUE&latestOnly=SOME_BOOLEAN_VALUE&offset=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE' \

List subjects associated to schema ID

GET /schemas/ids/{id}/subjects

curl -u <API-KEY>:<API-SECRET> --request GET \
--url '<SCHEMA-REGISTRY-URL>/schemas/ids/{id}/subjects?subject=SOME_STRING_VALUE&deleted=SOME_BOOLEAN_VALUE' \

List subject-versions associated to schema ID

GET /schemas/ids/{id}/versions

curl -u <API-KEY>:<API-SECRET>  --request GET \
--url '<SCHEMA-REGISTRY-URL>/schemas/ids/{id}/versions?subject=SOME_STRING_VALUE&deleted=SOME_BOOLEAN_VALUE' \

Subjects (V1) API Usage Examples

Get schema by version

GET /subjects/{subject}/versions/{version}

curl -u <API-KEY>:<API-SECRET> --request GET \
--url '<SCHEMA-REGISTRY-URL>/subjects/{subject}/versions/{version}?deleted=SOME_BOOLEAN_VALUE' \

Delete schema version

DELETE /subjects/{subject}/versions/{version}

curl -u <API-KEY>:<API-SECRET> --request DELETE \
--url '<SCHEMA-REGISTRY-URL>/subjects/{subject}/versions/{version}?permanent=SOME_BOOLEAN_VALUE' \

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' \

Get schema string by version

GET /subjects/{subject}/versions/{version}/schema

curl -u <API-KEY>:<API-SECRET> --request GET \
--url '<SCHEMA-REGISTRY-URL>/subjects/{subject}/versions/{version}/schema?deleted=SOME_BOOLEAN_VALUE' \

List versions under subject

GET /subjects/{subject}/versions

curl -u <API-KEY>:<API-SECRET> --request GET \
--url '<SCHEMA-REGISTRY-URL>/subjects/{subject}/versions?deleted=SOME_BOOLEAN_VALUE' \

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

POST /subjects/{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

DELETE /subjects/{subject}

curl -u <API-KEY>:<API-SECRET> --request DELETE \
--url '<SCHEMA-REGISTRY-URL>/{subject}?permanent=SOME_BOOLEAN_VALUE' \

List all subjects

GET /subjects

curl -u <API-KEY>:<API-SECRET> --request GET \
--url '<SCHEMA-REGISTRY-URL>/subjects?subjectPrefix=SOME_STRING_VALUE&deleted=SOME_BOOLEAN_VALUE' \

Suggested Reading