.. _schemaregistry_using:

Using |sr|
==========

Starting |sr|
-------------
Start |sr| and its dependent services |zk| and Kafka. Each service reads its configuration from its property files under
``etc``.

-------------------------------
Development or Test Environment
-------------------------------

You can use the Confluent CLI to start |sr| and its dependent services with this command:

.. sourcecode:: bash

     confluent start schema-registry

.. include:: ../includes/cli.rst
      :start-after: cli_limitations_start
      :end-before: cli_limitations_end

----------------------
Production Environment
----------------------

Start each |cp| service in its own terminal using this order of operations:

#. Start |zk|. Run this command in its own terminal.

   .. sourcecode:: bash

      bin/zookeeper-server-start ./etc/kafka/zookeeper.properties

#. Start Kafka. Run this command in its own terminal.

   .. sourcecode:: bash

      bin/kafka-server-start ./etc/kafka/server.properties

#. Start |sr|. Run this command in its own terminal.

   .. sourcecode:: bash

      bin/schema-registry-start ./etc/schema-registry/schema-registry.properties

.. ifconfig:: platform_docs

   See the :ref:`installation` for a more detailed explanation of how
   to get these services up and running.

Common |sr| Usage Examples
--------------------------

.. tip:: For a detailed example that uses |sr| configured with security, see the :ref:`Confluent Platform demo <cp-demo>`.

These examples use curl commands to interact with the |sr| :ref:`API <schemaregistry_api>`.

-------------------------------------------------------------------
Registering a New Version of a Schema Under the Subject "Kafka-key"
-------------------------------------------------------------------

.. sourcecode:: bash

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


---------------------------------------------------------------------
Registering a New Version of a Schema Under the Subject "Kafka-value"
---------------------------------------------------------------------


.. sourcecode:: bash

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

.. _sr-reg-exist-schema:

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

.. sourcecode:: 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
      {"id":1}


--------------------
Listing All Subjects
--------------------

.. sourcecode:: bash

      curl -X GET http://localhost:8081/subjects
      ["Kafka-value","Kafka-key"]


-----------------------------------------
Fetching a Schema by Globally Unique ID 1
-----------------------------------------

.. sourcecode:: bash

      curl -X GET http://localhost:8081/schemas/ids/1
      {"schema":"\"string\""}

----------------------------------------------------------------------
Listing All Schema Versions Registered Under the Subject "Kafka-value"
----------------------------------------------------------------------

.. sourcecode:: bash

      curl -X GET http://localhost:8081/subjects/Kafka-value/versions
      [1]

--------------------------------------------------------------------
Fetch Version 1 of the Schema Registered Under Subject "Kafka-value"
--------------------------------------------------------------------

.. sourcecode:: bash

      curl -X GET http://localhost:8081/subjects/Kafka-value/versions/1
      {"subject":"Kafka-value","version":1,"id":1,"schema":"\"string\""}

-----------------------------------------------------------------------
Deleting Version 1 of the Schema Registered Under Subject "Kafka-value"
-----------------------------------------------------------------------

.. sourcecode:: bash

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

------------------------------------------------------------------------
Deleting the Most Recently Registered Schema Under Subject "Kafka-value"
------------------------------------------------------------------------

.. sourcecode:: bash

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

-----------------------------------------------------------
Registering the Same Schema Under the Subject "Kafka-value"
-----------------------------------------------------------

.. sourcecode:: bash

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

-------------------------------------------------
Fetching the Schema Again by Globally Unique ID 1
-------------------------------------------------

.. sourcecode:: bash

      curl -X GET http://localhost:8081/schemas/ids/1
      {"schema":"\"string\""}

------------------------------------------------------------
Checking if a Schema Is Registered Under Subject "Kafka-key"
------------------------------------------------------------

.. sourcecode:: bash

      curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
        --data '{"schema": "{\"type\": \"string\"}"}' \
        http://localhost:8081/subjects/Kafka-key
      {"subject":"Kafka-key","version":3,"id":1,"schema":"\"string\""}

.. _sr-test-compat-latest:

------------------------------------------------------------------------------------
Testing Compatibility of a Schema with the Latest Schema Under Subject "Kafka-value"
------------------------------------------------------------------------------------

.. sourcecode:: 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
      {"is_compatible":true}

.. _sr-top-level-config:

----------------------------
Getting the Top Level Config
----------------------------

.. sourcecode:: bash

      curl -X GET http://localhost:8081/config
      {"compatibility":"BACKWARD"}

.. _updating-compatibility-requirements-globally:

--------------------------------------------
Updating Compatibility Requirements Globally
--------------------------------------------

.. sourcecode:: bash

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

-----------------------------------------------------------------------
Deleting All Schema Versions Registered Under the Subject "Kafka-value"
-----------------------------------------------------------------------

.. sourcecode:: bash

      curl -X DELETE http://localhost:8081/subjects/Kafka-value
      [3]

.. _kakfa-key-listing-all-subjects:

--------------------
Listing All Subjects
--------------------

.. sourcecode:: bash

      curl -X GET http://localhost:8081/subjects
      ["Kafka-key"]