<a id="schemaregistry-using"></a>

# Schema Registry API Usage Examples for Confluent Platform

These examples show how to call the
[Schema Registry API](api.md#schemaregistry-api) using
[curl](https://curl.haxx.se/) commands.

<!-- WARNING: THIS IS A SHARED FILE AND THE SOURCE IS LOCATED IN DOCS-COMMON. DO NOT ADD TO ANY OTHER REPO. -->

You can also see a few more examples of using curl to interact with these APIs in the [Schema Registry Tutorial](../schema_registry_onprem_tutorial.md#tutorial-use-curl-with-schema-registry).

For your API testing, you may want to use [jq](https://stedolan.github.io/jq/) along with `--silent` flag for [curl](https://curl.haxx.se/)
to get nicely formatted output for the given commands. For example, the command: `curl -X GET http://localhost:8081/subjects` results in:

```bash
["my-cool-topic-value","my-other-cool-topic-value"]
```

Whereas, the same command using curl in silent mode and piped through jq: `curl --silent -X GET http://localhost:8081/subjects | jq` results in:

```bash
"my-cool-topic-value",
"my-other-cool-topic-value"
```

## Starting Schema Registry

Start Schema Registry and its dependent services KRaft and Kafka. Each service reads its configuration from its property files under `etc`.

### Development or Test Environment

Prerequisites
: - [Confluent Platform](../../installation/index.md#installation-overview)

<!-- removed CLI as it comes with CP -->

You can use the Confluent CLI [confluent local](https://docs.confluent.io/confluent-cli/current/command-reference/local/index.html) commands to start Schema Registry and its dependent services with this command:

```bash
confluent local services schema-registry start
```

#### IMPORTANT
The Confluent CLI [confluent local](https://docs.confluent.io/confluent-cli/current/command-reference/local/index.html) commands are intended for a single-node development environment and
are not suitable for a production environment. The data that are produced are transient and are intended to be
temporary. For production-ready workflows, see [Install and Upgrade Confluent Platform](../../installation/index.md#installation-overview).

### Production Environment

Start each Confluent Platform service in its own terminal using this order of operations:

1. Start ZooKeeper. Run this command in its own terminal.
   ```bash
   bin/zookeeper-server-start ./etc/kafka/zookeeper.properties
   ```
2. Start Kafka. Run this command in its own terminal.
   ```bash
   bin/kafka-server-start ./etc/kafka/server.properties
   ```
3. Start Schema Registry. Run this command in its own terminal.
   ```bash
   bin/schema-registry-start ./etc/schema-registry/schema-registry.properties
   ```

See the [Install Confluent Platform On-Premises](../../installation/overview.md#installation) for a more detailed explanation of how
to get these services up and running.

## Common Schema Registry API Usage Examples

#### SEE ALSO
- [Formats, Serializers, and Deserializers](/platform/current/schema-registry/fundamentals/serdes-develop/index.html)
- [Schema Registry API Reference for Confluent Platform](api.md#schemaregistry-api)
- For a detailed example that uses Schema Registry configured with security, see the [Confluent Platform demo](../../tutorials/cp-demo/index.md#cp-demo).

These examples use [curl](https://curl.haxx.se/docs/manual.html) commands to interact with the Schema Registry [Schema Registry API](api.md#schemaregistry-api).

Commands and results are shown separately to make it easy to copy-paste the commands into a shell.

For Schema Registry on Confluent Cloud, pass the API key and secret with the `--user` (or `-u`) flag on the curl command. For example, to view all subjects in the registry:

```bash
curl --user <schema-registry-api-key>:<schema-registry-api-secret> \
<schema-registry-url>/subjects
```

### Register a new version of a schema under the subject “Kafka-key”

```bash
curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema": "{\"type\": \"string\"}"}' \
  http://localhost:8081/subjects/Kafka-key/versions
```

Example result:

```none
{"id":1,"version":1,"guid":"xxx-xxxx-xxx-xxx","schemaType":"AVRO","schema":"{\"type\":\"string\"}"}
```

### Register a new version of a schema under the subject “Kafka-value”

```bash
curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
--data '{"schema": "{\"type\": \"string\"}"}' \
http://localhost:8081/subjects/Kafka-value/versions
```

Example result:

```none
{"id":1,"version":1,"guid":"xxx-xxxx-xxx-xxx","schemaType":"AVRO","schema":"{\"type\":\"string\"}"}
```

<a id="sr-reg-exist-schema"></a>

### Register an existing schema to a new subject name

Use case: there is an existing schema registered to a subject called `Kafka1`, and this same schema needs to be available to another subject called `Kafka2`.
The following one-line command reads the existing schema from `Kafka1-value` and registers it to `Kafka2-value`.
It assumes the tool `jq` is installed on your machine.

```bash
curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
--data "{\"schema\": $(curl -s http://localhost:8081/subjects/Kafka1-value/versions/latest | jq '.schema')}" \
http://localhost:8081/subjects/Kafka2-value/versions
```

Example result:

```none
{"id":1,"version":1,"guid":"xxx-xxxx-xxx-xxx","schemaType":"AVRO","schema":"{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"},{\"name\":\"field2\",\"type\":\"int\"}]}"}
```

<a id="kafka-key-listing-all-subjects"></a>

### List all subjects

The following API call lists all schema subjects.

```bash
curl -X GET http://localhost:8081/subjects
```

Example result:

```none
["Kafka-value","Kafka-key"]
```

You can use the `deleted` flag at the end of the request to list all subjects, including subjects that have been soft-deleted (`?deleted=true`).

```bash
curl -X GET http://localhost:8081/subjects?deleted=true
```

Example result, assuming you had a schema subject called “my-cool-topic-value” that was previously soft-deleted:

```none
["Kafka-value","Kafka-key","my-cool-topic-value"]
```

<a id="list-subjects-for-given-id"></a>

### List all subjects associated with a given ID

To find subjects associated with a given ID, use [GET /schemas/ids/{int: id}/versions](/platform/current/schema-registry/develop/api.html#get--schemas-ids-int-%20id-versions).

### Fetch a schema by globally unique ID 1

```bash
curl -X GET http://localhost:8081/schemas/ids/1
```

Example result:

```none
{"schema":"\"string\""}
```

### List all schema versions registered under the subject “Kafka-value”

```bash
curl -X GET http://localhost:8081/subjects/Kafka-value/versions
```

Example result:

```none
[1]
```

### Fetch Version 1 of the schema registered under subject “Kafka-value”

```bash
curl -X GET http://localhost:8081/subjects/Kafka-value/versions/1
```

Example result:

```none
{"subject":"Kafka-value","version":1,"id":1,"schema":"\"string\""}
```

### Delete Version 1 of the schema registered under subject “Kafka-value”

```bash
curl -X DELETE http://localhost:8081/subjects/Kafka-value/versions/1
```

Example result:

```none
1
```

#### SEE ALSO
[Delete Schemas in Confluent Platform](../schema-deletion-guidelines.md#schemaregistry-deletion)

### Delete the most recently registered schema under subject “Kafka-value”

```bash
curl -X DELETE http://localhost:8081/subjects/Kafka-value/versions/latest
```

Example result:

```none
2
```

#### SEE ALSO
[Delete Schemas in Confluent Platform](../schema-deletion-guidelines.md#schemaregistry-deletion)

### Register the same schema under the subject “Kafka-value”

```bash
curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema": "{\"type\": \"string\"}"}' \
   http://localhost:8081/subjects/Kafka-value/versions
```

Example result:

```none
{"id":1,"version":1,"guid":"xxx-xxxx-xxx-xxx","schemaType":"AVRO","schema":"{\"type\":\"string\"}"}
```

### Fetch the schema again by globally unique ID 1

```bash
curl -X GET http://localhost:8081/schemas/ids/1
```

Example result:

```none
{"schema":"\"string\""}
```

### Check if a schema Is registered under subject “Kafka-key”

```bash
curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema": "{\"type\": \"string\"}"}' \
  http://localhost:8081/subjects/Kafka-key
```

Example result:

```none
{"subject":"Kafka-key","version":3,"id":1,"schema":"\"string\""}
```

<a id="sr-test-compat-latest"></a>

### Test compatibility of a schema with the latest schema under subject “Kafka-value”

```bash
curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema": "{\"type\": \"string\"}"}' \
  http://localhost:8081/compatibility/subjects/Kafka-value/versions/latest
```

Example result:

```none
{"is_compatible":true}
```

<a id="sr-top-level-config"></a>

### Get the top level config

```bash
curl -X GET http://localhost:8081/config
```

Example result:

```none
{"compatibility":"BACKWARD"}
```

<a id="updating-compatibility-requirements-globally"></a>

### Update compatibility requirements globally

```bash
curl -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"compatibility": "NONE"}' \
  http://localhost:8081/config
```

Example result:

```none
{"compatibility":"NONE"}
```

<a id="update-compatibility-on-a-subject"></a>

### Register a schema for a new topic

Use the Schema Registry API to add a schema for the topic `my-kafka`.

```bash
curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" --data '{"schema": "{\"type\":\"record\",\"name\":\"Payment\",\"namespace\":\"my.examples\",\"fields\":[{\"name\":\"id\",\"type\":\"string\"},{\"name\":\"amount\",\"type\":\"double\"}]}"}' http://localhost:8081/subjects/my-kafka-value/versions
```

Example result:

```none
{"id":1,"version":1,"guid":"xxx-xxxx-xxx-xxx","schemaType":"AVRO","schema":"{\"type\":\"record\",\"name\":\"Payment\",\"namespace\":\"my.examples\",\"fields\":[{\"name\":\"id\",\"type\":\"string\"},{\"name\":\"amount\",\"type\":\"double\"}]}"}
```

<a id="set-compatibility-on-subject"></a>

### Update compatibility requirements on a subject

```bash
curl -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" --data '{"compatibility": "FULL"}' http://localhost:8081/config/my-kafka-value
```

Example result:

```none
{"compatibility":"FULL"}
```

<a id="get-compatibility-on-subject"></a>

### Get compatibility requirements on a subject

```bash
curl -X GET http://localhost:8081/config/my-kafka-value
```

Example result:

```none
{"compatibilityLevel":"FULL"}
```

<a id="show-compatibility-subject-or-global"></a>

### Show compatibility requirements in effect for a subject

You can use the flag `defaultToGlobal` to determine what compatibility
requirements, if any, are set at the subject level and what requirements will be
used for compatibility checks. These are often, but not always, the same if
a subject has subject-level compatibility set.

- For the subject `my-kafka-value`, which has a subject-specific compatibility set to “FULL”, `defaultToGlobal=true` and `defaultToGlobal=false` both return `{"compatibilityLevel":"FULL"}`.
  ```bash
  curl -X GET http://localhost:8081/config/my-kafka-value/?defaultToGlobal=true
  ```

  Example result:
  ```none
  {"compatibilityLevel":"FULL"}
  ```

  ```bash
  curl -X GET http://localhost:8081/config/my-kafka-value/?defaultToGlobal=false
  ```

  Example result:
  ```none
  {"compatibilityLevel":"FULL"}
  ```
- For the subject `Kafka-value`, for which you have not set subject-specific compatibility, `defaultToGlobal=true` returns the current global default, for example: `{"compatibilityLevel":"NONE"}`.
  ```bash
  curl -X GET http://localhost:8081/config/Kafka-value/?defaultToGlobal=true
  ```

  Example result:
  ```none
  {"compatibilityLevel":"NONE"}
  ```
- Whereas, `defaultToGlobal=false` on the subject `Kafka-value` returns an error code:
  ```bash
  curl -X GET http://localhost:8081/config/Kafka-value/?defaultToGlobal=false
  ```

  Example result:
  ```bash
  {"error_code":40401,"message":"Subject 'Kafka-value' not found."}
  ```

### Delete all schema versions registered under the subject “Kafka-value”

```bash
curl -X DELETE http://localhost:8081/subjects/Kafka-value
```

Example result:

```none
[3]
```

#### SEE ALSO
[Delete Schemas in Confluent Platform](../schema-deletion-guidelines.md#schemaregistry-deletion)

### List schema types currently registered in Schema Registry

```bash
curl -X GET http://localhost:8081/schemas/types
```

Example result:

```none
["JSON", "PROTOBUF", "AVRO"]
```

### List all subject-version pairs where a given ID is used

```bash
curl -X GET http://localhost:8081/schemas/ids/2/versions
```

Example result:

```none
[{"subject":"testproto-value","version":1}]
```

### List IDs of schemas that reference a given schema

```bash
curl -X GET http://localhost:8081/subjects/other.proto/versions/1/referencedby
```

Example result:

```none
[2]
```

<a id="sr-over-https-api-examples"></a>

## Using Schema Registry over HTTPS

The curl command examples provided above show how to communicate with Schema Registry over HTTP.

These examples show how to communicate with Schema Registry over [HTTPS](../security/index.md#schema-registry-http-https).
You can extrapolate from these few examples to know how to run additional commands. When communicating
with Schema Registry with HTTPS enabled, apply the patterns shown for the curl commands (specifying a certificate,
key, and so forth) to accomplish the other usage examples shown above. For more about configuring and
using Schema Registry with security enabled, see [Secure Schema Registry for Confluent Platform](../security/index.md#schemaregistry-security).

### Verify HTTPS on Schema Registry

```none
openssl s_client -connect schemaregistry:8082/subjects -cert client.certificate.pem -key client.key -tls1
```

### Register a new version of a schema under the subject “Kafka-key”

```none
curl -v -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" --data '{"schema": "{\"type\": \"string\"}"}' --cert /etc/kafka/secrets/client.certificate.pem --key /etc/kafka/secrets/client.key --tlsv1.2 --cacert /etc/kafka/secrets/snakeoil-ca-1.crt https://schemaregistry:8082/subjects/Kafka-key/versions
```

### List all subjects

```none
curl -v -X GET --cert /etc/kafka/secrets/client.certificate.pem --key /etc/kafka/secrets/client.key --tlsv1.2 --cacert /etc/kafka/secrets/snakeoil-ca-1.crt https://schemaregistry:8082/subjects/
```

<a id="sr-on-ccloud-api-curl"></a>

## Use curl to access Schema Registry in Confluent Cloud

<!-- how to access schema registry on ccloud using curl -->

You can also use [curl](https://curl.haxx.se/) commands to view and manage schemas on Confluent Cloud.

Schema Registry on Confluent Cloud requires that you pass the API Key and Secret with the `--user` (or `-u`) flag.
For example, to view all [subjects](../fundamentals/index.md#sr-subjects-topics-primer) in the registry:

```bash
curl --user <schema-registry-api-key>:<schema-registry-api-secret> \
<schema-registry-url>/subjects
```

For more about using Schema Registry on Confluent Cloud, see [Quick Start for Schema Management on Confluent Cloud](/cloud/current/get-started/schema-registry.html).

## Related Content

* [Schema Registry API Reference for Confluent Platform](api.md#schemaregistry-api)
* [Tutorial: Use Schema Registry on Confluent Platform to Implement Schemas for a Client Application](../schema_registry_onprem_tutorial.md#schema-registry-onprem-tutorial)
* [Formats, Serializers, and Deserializers](/platform/current/schema-registry/fundamentals/serdes-develop/index.html)
* [Schema Evolution and Compatibility for Schema Registry on Confluent Platform](../fundamentals/schema-evolution.md#schema-evolution-and-compatibility)
* [Monitor Schema Registry in Confluent Platform](../monitoring.md#schemaregistry-monitoring)