.. _schemaregistry_api: |sr| API Reference ================== This section provides a detailed reference for the |sr| API. The best way to test these is to use `curl `__. For examples of using ``curl`` to test these APIs, see :ref:`schemaregistry_using`. You can also see curl API calls used in the :ref:`Schema Registry Tutorial ` and to test drive different schema formats in the deep dive sections on `Formats, Serializers, and Deserializers `__. .. include:: ../../.hidden/docs-common/home/includes/cloud-platform-cta.rst Compatibility ^^^^^^^^^^^^^ The |sr| server can enforce certain compatibility rules when new schemas are registered in a subject. These are the compatibility types: .. include:: ../includes/compatibility_list.rst We recommend keeping the default backward compatibility since it allows you to rewind consumers to the beginning of the topic. For more details on schema resolution, see :ref:`schema_evolution_and_compatibility`. Content Types ^^^^^^^^^^^^^ The |sr| REST server uses content types for both requests and responses to indicate the serialization format of the data as well as the version of the API being used. Currently, the only serialization format supported is JSON and the only version of the API is ``v1``. However, to remain compatible with future versions, you *should* specify preferred content types in requests and check the content types of responses. The preferred format for content types is ``application/vnd.schemaregistry.v1+json``, where ``v1`` is the API version and ``json`` is the serialization format. However, other less specific content types are permitted, including ``application/vnd.schemaregistry+json`` to indicate no specific API version should be used (the most recent stable version will be used), ``application/json``, and ``application/octet-stream``. The latter two are only supported for compatibility and ease of use. Your requests *should* specify the most specific format and version information possible via the HTTP ``Accept`` header:: Accept: application/vnd.schemaregistry.v1+json The server also supports content negotiation, so you may include multiple, weighted preferences:: Accept: application/vnd.schemaregistry.v1+json; q=0.9, application/json; q=0.5 which can be useful when, for example, a new version of the API is preferred but you cannot be certain it is available yet. Errors ^^^^^^ All API endpoints use a standard error message format for any requests that return an HTTP status indicating an error (any 400 or 500 statuses). For example, a request entity that omits a required field may generate the following response: .. sourcecode:: http HTTP/1.1 422 Unprocessable Entity Content-Type: application/vnd.schemaregistry.v1+json { "error_code": 422, "message": "schema may not be empty" } Although it is good practice to check the status code, you may safely parse the response of any non-DELETE API calls and check for the presence of an ``error_code`` field to detect errors. Example Requests Format and Valid JSON ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The example requests below are formatted for readability. Therefore, multi-line example requests include returns (newlines). To use a multi-line example as a copy-paste test of an API, remove the newlines before running it so as not to trigger errors for invalid JSON. For example, a direct copy-and-paste of this request will produce errors because it includes newlines to help with readability: .. sourcecode:: http { "schema": "{ \"type\": \"record\", \"name\": \"test\", \"fields\": [ { \"type\": \"string\", \"name\": \"field1\" }, { \"type\": \"int\", \"name\": \"field2\" } ] }" } This is the same request as that above with the newlines removed. It should run properly as a copy-and-paste example. .. sourcecode:: http {"schema": "{ \"type\": \"record\", \"name\": \"test\", \"fields\": [ { \"type\": \"string\", \"name\": \"field1\" }, { \"type\": \"int\", \"name\": \"field2\" } ] }" } Schemas ------- .. http:get:: /schemas/ids/{int: id} Get the schema string identified by the input ID. :param int id: the globally unique identifier of the schema :param string subject: Add ``?subject=`` at the end of this request to look for the subject in all contexts starting with the default context, and return the schema with the ID from that context. To learn more about contexts, see the :ref:`exporters ` API reference and the quick start and concepts guides for :ref:`schema-linking-cp-overview` and :cloud:`Schema Linking on Confluent Cloud|sr/schema-linking.html`. :>json string schema: Schema string identified by the ID :statuscode 404: * Error code 40403 -- Schema not found :statuscode 500: * Error code 50001 -- Error in the backend datastore **Example request**: .. sourcecode:: http GET /schemas/ids/1 HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "schema": "{\"type\": \"string\"}" } .. http:get:: /schemas/ids/{int: id}/schema Retrieves only the schema identified by the input ID. :param int id: the globally unique identifier of the schema :param string subject: Add ``?subject=`` at the end of this request to look for the subject in all contexts starting with the default context, and return the schema with the ID from that context. To learn more about contexts, see the :ref:`exporters ` API reference and the quick start and concepts guides for :ref:`schema-linking-cp-overview` and :cloud:`Schema Linking on Confluent Cloud|sr/schema-linking.html`. :>json string schema: Schema identified by the ID :statuscode 404: * Error code 40403 -- Schema not found :statuscode 500: * Error code 50001 -- Error in the backend datastore **Example request**: .. sourcecode:: http GET /schemas/ids/1/schema HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json "string" .. http:get:: /schemas/types/ Get the schema types that are registered with |sr|. :>json string schema: Schema types currently available on |sr|. :statuscode 404: * Error code 40403 -- Schema not found :statuscode 500: * Error code 50001 -- Error in the backend datastore **Example request**: .. sourcecode:: http GET /schemas/types HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { ["JSON", "PROTOBUF", "AVRO"] } .. http:get:: /schemas/ids/{int: id}/versions Get the subject-version pairs identified by the input ID. :param int id: the globally unique identifier of the schema :>jsonarr string subject: Name of the subject :>jsonarr int version: Version of the returned schema :statuscode 404: * Error code 40403 -- Schema not found :statuscode 500: * Error code 50001 -- Error in the backend datastore **Example request**: .. sourcecode:: http GET /schemas/ids/1/versions HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json [{"subject":"test-subject1","version":1}] .. _schemaregistry-api-subjects: Subjects -------- The subjects resource provides a list of all registered subjects across all contexts in your |sr|. A subject refers to the name under which the schema is registered. If you are using |sr| for |ak|, then a subject refers to either a "-value" or "-key" depending on whether you are registering the value schema for that topic or the key schema. To learn more about subject name strategies, see :ref:`sr-schemas-subject-name-strategies-work`. .. tip:: To find subjects for a given ID, see `GET /schemas/ids/{int: id}/versions `__. .. http:get:: /subjects Get a list of registered subjects. (For API usage examples, see :ref:`kafka-key-listing-all-subjects`.) :param string subjectPrefix: Add ``?subjectPrefix=`` (as an empty string) at the end of this request to list subjects in the default context. If this flag is not included, ``GET /subjects`` returns all subjects across all contexts. To learn more about contexts, see the :ref:`exporters ` API reference and the quick start and concepts guides for :ref:`schema-linking-cp-overview` and :cloud:`Schema Linking on Confluent Cloud|sr/schema-linking.html`. :param boolean deleted: Add ``?deleted=true`` at the end of this request to list both current and soft-deleted subjects. The default is ``false``. If this flag is not included, only current subjects are listed (not those that have been soft-deleted). Hard and soft delete are explained below in the description of the ``delete`` API. :>jsonarr string name: Subject :statuscode 500: * Error code 50001 -- Error in the backend datastore **Example request**: .. sourcecode:: http GET /subjects HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json ["subject1", "subject2"] .. http:get:: /subjects/(string: subject)/versions Get a list of versions registered under the specified subject. :param string subject: the name of the subject :>jsonarr int version: version of the schema registered under this subject :statuscode 404: * Error code 40401 -- Subject not found :statuscode 500: * Error code 50001 -- Error in the backend datastore **Example request**: .. sourcecode:: http GET /subjects/test/versions HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json [ 1, 2, 3, 4 ] .. http:delete:: /subjects/(string: subject) Deletes the specified subject and its associated compatibility level if registered. It is recommended to use this API only when a topic needs to be recycled or in a development environment. To learn more, see :ref:`schemaregistry_deletion`. :param string subject: the name of the subject :param boolean permanent: Add ``?permanent=true`` at the end of this request to specify a hard delete of the subject, which removes all associated metadata including the schema ID. The default is ``false``. If the flag is not included, a soft delete is performed. You must perform a soft delete first, then the hard delete. This flag is now supported on both |cp| and |ccloud|, which sets limits on the number of schema versions supported in the registry. A hard delete frees up space in a way that a soft delete does not. To learn more, see :ref:`hard-delete-schema` in :ref:`schemaregistry_deletion`. :>jsonarr int version: version of the schema deleted under this subject :statuscode 404: * Error code 40401 -- Subject not found :statuscode 500: * Error code 50001 -- Error in the backend datastore **Example request**: .. sourcecode:: http DELETE /subjects/test HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json [ 1, 2, 3, 4 ] .. http:get:: /subjects/(string: subject)/versions/(versionId: version) Get a specific version of the schema registered under this subject :param string subject: Name of the subject :param versionId version: Version of the schema to be returned. Valid values for versionId are between [1,2^31-1] or the string ``latest``, which returns the last registered schema under the specified subject. The value ``-1`` is equivalent to latest. Note that there may be a new latest schema that gets registered right after this request is served. Note that there may be a new latest schema that gets registered right after this request is served. :>json string subject: Name of the subject that this schema is registered under :>json int id: Globally unique identifier of the schema :>json int version: Version of the returned schema :>json string schemaType: The schema format: AVRO is the default (if no schema type is shown on the response, the type is AVRO), PROTOBUF, JSON :>json string schema: The schema string :statuscode 404: * Error code 40401 -- Subject not found * Error code 40402 -- Version not found :statuscode 422: * Error code 42202 -- Invalid version :statuscode 500: * Error code 50001 -- Error in the backend data store **Example request**: .. sourcecode:: http GET /subjects/test/versions/1 HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response (AVRO)**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "name": "test", "version": 1, "schema": "{\"type\": \"string\"}" } **Example response (PROTOBUF)**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "name": "test", "version": 1, "schemaType": "PROTOBUF" "schema": "{\"type\": \"string\"}" } .. http:get:: /subjects/(string: subject)/versions/(versionId: version)/schema Get the schema for the specified version of this subject. The unescaped schema only is returned. :param string subject: Name of the subject :param versionId version: Version of the schema to be returned. Valid values for versionId are between [1,2^31-1] or the string ``latest``, which returns the last registered schema under the specified subject. The value ``-1`` is equivalent to latest. Note that there may be a new latest schema that gets registered right after this request is served. :>json string schema: The schema string (unescaped) :statuscode 404: * Error code 40401 -- Subject not found * Error code 40402 -- Version not found :statuscode 422: * Error code 42202 -- Invalid version :statuscode 500: * Error code 50001 -- Error in the backend data store **Example request**: .. sourcecode:: http GET /subjects/test/versions/1/schema HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json {"type": "string"} .. _api-example-avro-schema-references: .. http:post:: /subjects/(string: subject)/versions Register a new schema under the specified subject. (Essentially, create a new schema.) If successfully registered, this returns the unique identifier of this schema in the registry. The returned identifier should be used to retrieve this schema from the schemas resource and is different from the schema's version which is associated with the subject. If the same schema is registered under a different subject, the same identifier will be returned. However, the version of the schema may be different under different subjects. A schema should be compatible with the previously registered schema or schemas (if there are any) as per the configured compatibility level. If a compatibility level has been set on a subject, the configured compatibility level can be obtained by issuing a ``GET http:get:: /config/(string: subject)``. If this returns an error, it means that no `subject-specific` compatibility level is set for the subject. In that case, use ``GET http:get:: /config`` to find the `global` compatibility level, which applies to all subjects. (Subject-specific compatibility, when configured, overrides global.) For examples, see :ref:`set-compatibility-on-subject` and :ref:`get-compatibility-on-subject`. When there are multiple instances of |sr| running in the same cluster, the schema registration request will be forwarded to one of the instances designated as the primary. If the primary is not available, the client will get an error code indicating that the forwarding has failed. If no ``schemaType`` is supplied, ``schemaType`` is assumed to be AVRO. :param string subject: Subject under which the schema will be registered :param boolean normalize: Add ``?normalize=true`` at the end of this request to normalize the schema. The default is ``false``. To learn more, see :ref:`schema-normalization`. :reqjson schema: The schema string :reqjson schemaType: Defines the schema format: AVRO (default), PROTOBUF, JSON (Optional) :reqjson references: Specifies the names of referenced schemas (Optional). To learn more, see :ref:`referenced-schemas`. :reqjson metadata: Specifies the metadata for the schema (Optional). To learn more, see "Metadata Properties" in :platform:`Data Contracts for Schema Registry |schema-registry/fundamentals/data-contracts.html`. :reqjson ruleSet: Specifies the ruleSet for the schema (Optional). To learn more, see "Rules" in :platform:`Data Contracts for Schema Registry |schema-registry/fundamentals/data-contracts.html`. :>json int id: Globally unique identifier of the schema :statuscode 409: Incompatible schema :statuscode 422: * Error code 42201 -- Invalid schema :statuscode 500: * 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 **Example request**: .. sourcecode:: http POST /subjects/test/versions HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json { "schema": "{ \"type\": \"record\", \"name\": \"test\", \"fields\": [ { \"type\": \"string\", \"name\": \"field1\" }, { \"type\": \"com.acme.Referenced\", \"name\": \"int\" } ] }", "schemaType": "AVRO", "references": [ { "name": "com.acme.Referenced", "subject": "childSubject", "version": 1 } ] } **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json {"id":1} .. http:post:: /subjects/(string: subject) Check if a schema has already been registered under the specified subject. If so, this returns the schema string along with its globally unique identifier, its version under this subject and the subject name. :param string subject: Subject under which the schema will be registered :param boolean normalize: Add ``?normalize=true`` at the end of this request to normalize the schema. The default is ``false``. To learn more, see :ref:`schema-normalization`. :reqjson schema: The schema string :reqjson schemaType: Defines the schema format: AVRO (default), PROTOBUF, JSON (Optional) :reqjson references: Specifies the names of referenced schemas (Optional). To learn more, see :ref:`referenced-schemas`. :reqjson metadata: Specifies the metadata for the schema (Optional). To learn more, see "Metadata Properties" in :platform:`Data Contracts for Schema Registry |schema-registry/fundamentals/data-contracts.html`. :reqjson ruleSet: Specifies the ruleSet for the schema (Optional). To learn more, see "Rules" in :platform:`Data Contracts for Schema Registry |schema-registry/fundamentals/data-contracts.html`. :>json string subject: Name of the subject that this schema is registered under :>json int id: Globally unique identifier of the schema :>json int version: Version of the returned schema :>json string schema: The schema string :statuscode 404: * Error code 40401 -- Subject not found * Error code 40403 -- Schema not found :statuscode 500: Internal server error **Example request**: .. sourcecode:: http POST /subjects/test HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json { "schema": "{ \"type\": \"record\", \"name\": \"test\", \"fields\": [ { \"type\": \"string\", \"name\": \"field1\" }, { \"type\": \"int\", \"name\": \"field2\" } ] }" } **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "subject": "test", "id": 1 "version": 3 "schema": "{ \"type\": \"record\", \"name\": \"test\", \"fields\": [ { \"type\": \"string\", \"name\": \"field1\" }, { \"type\": \"int\", \"name\": \"field2\" } ] }" } .. http:delete:: /subjects/(string: subject)/versions/(versionId: version) Deletes a specific version of the schema registered under this subject. Unless you perform a hard delete (with ``?permanent=true`` as noted below), this only deletes the version, leaving the schema ID intact and making it still possible to decode data using the schema ID. This API is recommended to be used only in development environments or under extreme circumstances where-in, its required to delete a previously registered schema for compatibility purposes or re-register previously registered schema. :param string subject: Name of the subject :param versionId version: Version of the schema to be deleted. Valid values for versionId are between [1,2^31-1] or the string ``latest``, which deletes the last registered schema under the specified subject. The value ``-1`` is equivalent to latest. Note that there may be a new latest schema that gets registered right after this request is served. Note that there may be a new latest schema that gets registered right after this request is served. For hard-delete of a schema version, you must provide a version number as input; `not` ``version:latest``, which results in a soft delete only, even with the ``?permanent=true`` flag appended. To learn more, see :ref:`schemaregistry_deletion`. :param boolean permanent: Add ``?permanent=true`` at the end of this request to specify a hard delete for a specific version of the subject, which removes all associated metadata including the schema ID. The default is ``false``. If the flag is not included, a soft delete is performed. You must perform a soft delete first, then the hard delete. This flag is now supported on both |cp| and |ccloud|, which sets limits on the number of schema versions supported in the registry. A hard delete frees up space in a way that a soft delete does not. To learn more, see :ref:`hard-delete-schema` in :ref:`schemaregistry_deletion`. :>json int: Version of the deleted schema :statuscode 404: * Error code 40401 -- Subject not found * Error code 40402 -- Version not found :statuscode 422: * Error code 42202 -- Invalid version :statuscode 500: * Error code 50001 -- Error in the backend data store **Example request**: .. sourcecode:: http DELETE /subjects/test/versions/1 HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json 1 .. http:get:: /subjects/(string: subject)/versions/{versionId: version}/referencedby Get a list of IDs of schemas that reference the schema with the given subject and version. :param string subject: Name of the subject :param versionId version: Version of the schema to be returned. Valid values for versionId are between [1,2^31-1] or the string ``latest``, which returns the last registered schema under the specified subject. The value ``-1`` is equivalent to latest. Note that there may be a new latest schema that gets registered right after this request is served. Note that there may be a new latest schema that gets registered right after this request is served. :>jsonarr int id: Globally unique identifier of the schema :statuscode 404: * Error code 40401 -- Subject not found :statuscode 500: * Error code 50001 -- Error in the backend datastore **Example request**: .. sourcecode:: http GET /subjects/test/versions/1/referencedby HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json [ 1, 2, 3, 4 ] .. _schemaregistry-api-mode: Mode ---- You can use the mode resource to set the mode on |sr| at a global level or to set the mode on a specific subject. The following modes are available: - IMPORT - READONLY - READWRITE .. tip:: To enable mode changes on a |sr| cluster, you must also set ``mode.mutability=true`` in the |sr| properties file before starting |sr|. Examples of setting this property and changing the mode on |sr| at a global level and at the subject level are shown as a part of the procedure to :ref:`schemaregistry_migrate`. .. http:get:: /mode Get the current mode for |sr| at a global level. :>json string mode: |sr| mode. Returns one of IMPORT, READONLY, READWRITE (default) :statuscode 500: * Error code 50001 -- Error in the backend data store **Example request**: .. sourcecode:: http GET /mode HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "mode": "READWRITE" } .. http:put:: /mode Update the global |sr| mode. This will work only if |sr| was started with ``mode.mutability=true`` set in the |sr| properties file. :param boolean force: Add ``?force=true`` at the end of this request to force a mode change even if the |sr| has existing schemas. This can be useful in disaster recovery (DR) scenarios using :ref:`Schema Linking `. The default is ``false``, which does not allow a mode change to IMPORT if |sr| has registered schemas. :json string mode: Mode for the subject. Returns one of IMPORT, READONLY, READWRITE (default) :statuscode 404: Subject not found :statuscode 500: * Error code 50001 -- Error in the backend data store **Example request**: .. sourcecode:: http GET /mode/test HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "mode": "READWRITE" } .. http:put:: /mode/(string: subject) Update the mode for the specified subject. This will work only if |sr| was started with ``mode.mutability=true`` set in the |sr| properties file. :param string subject: Name of the subject :param boolean force: Add ``?force=true`` at the end of this request to force a mode change even if the |sr| has existing schemas. This can be useful in disaster recovery (DR) scenarios using :ref:`Schema Linking `. The default is ``false``, which does not allow a mode change to IMPORT if |sr| has registered schemas. :json boolean is_compatible: True, if compatible. False otherwise :statuscode 404: * Error code 40401 -- Subject not found * Error code 40402 -- Version not found :statuscode 422: * Error code 42201 -- Invalid schema * Error code 42202 -- Invalid version :statuscode 500: * Error code 50001 -- Error in the backend data store **Example request**: .. sourcecode:: http POST /compatibility/subjects/test/versions/latest HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json { "schema": "{ \"type\": \"record\", \"name\": \"test\", \"fields\": [ { \"type\": \"string\", \"name\": \"field1\" }, { \"type\": \"int\", \"name\": \"field2\" } ] }" } **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "is_compatible": true } .. http:post:: /compatibility/subjects/(string: subject)/versions Perform a compatibility check on the schema against one or more versions in the subject, :ref:`depending on how the compatibility is set `. For example, if compatibility on the subject is set to ``BACKWARD``, ``FORWARD``, or ``FULL``, the compatibility check is against the latest version. If compatibility is set to one of the ``TRANSITIVE`` types, the check is against all previous versions. The compatibility level applied for the check is the configured compatibility level for the subject (``http:get:: /config/(string: subject)``). If this subject's compatibility level was never changed, then the global compatibility level applies (``http:get:: /config``). This API endpoint, which tests a schema for compatibility against all versions, is new in |cp| 7.0.0. :param string subject: Subject of the schema version against which compatibility is to be tested :param boolean verbose: Add ``?verbose=true`` at the end of this request to output the reason a schema fails the compatibility test, in cases where it fails. The default is ``false`` (the reason a schema fails compatibility test is not given). :reqjson schema: The schema string :reqjson schemaType: Defines the schema format: AVRO (default), PROTOBUF, JSON (Optional) :reqjson references: Specifies the names of referenced schemas (Optional). To learn more, see :ref:`referenced-schemas`. :>json boolean is_compatible: True, if compatible. False otherwise :statuscode 404: * Error code 40401 -- Subject not found :statuscode 422: * Error code 42201 -- Invalid schema :statuscode 500: * Error code 50001 -- Error in the backend data store **Example request**: .. sourcecode:: http POST /compatibility/subjects/test/versions Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json { "schema": "{ \"type\": \"record\", \"name\": \"test\", \"fields\": [ { \"type\": \"string\", \"name\": \"field1\" }, { \"type\": \"int\", \"name\": \"field2\" } ] }" } **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "is_compatible": true } .. _sr_api_config_resource: Config ------ The config resource allows you to inspect and update the cluster-level configuration values as well as subject overrides. .. http:put:: /config Update the configuration for global compatibility level, compatibility group, schema normalization, default metadata, and rule set. When there are multiple instances of |sr| running in the same cluster, the update request will be forwarded to one of the instances designated as the primary. If the primary is not available, the client will get an error code indicating that the forwarding has failed. :` for the subject. Must be one of BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, NONE :` for the subject. Returns one of BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, NONE :` for the subject. Must be one of BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, NONE :` level for the subject. Returns one of BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, NONE :jsonarr string name: Name of the exporter **Example request**: .. sourcecode:: http GET /exporters HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json ["exporter1", "exporter2"] .. http:get:: /contexts Gets a list of contexts. The list will always include the default context, and any custom contexts that were created in the registry. :>jsonarr string name: Name of the context :statuscode 500: * Error code 50001 internal server error -- Error in the backend datastore **Example request**: .. sourcecode:: http GET /contexts HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json [":.:", ".mycontext"] .. http:post:: /exporters Creates a new schema exporter. All attributes in request body are optional except config. :json string name: Name of the exporter :statuscode 409: * Error code 40950 -- Missing or invalid exporter name * Error code 40951 -- Missing or invalid exporter config * Error code 40952 -- Invalid exporter subjects * Error code 40960 -- Exporter already exists * Error code 40964 -- Too many exporters **Example request**: .. sourcecode:: http POST /exporters HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json { "name": "test-exporter", "contextType": "CUSTOM", "context": "test-context", "subjects": ["foo"], "config": { "schema.registry.url": "", "basic.auth.credentials.source": "USER_INFO", "basic.auth.user.info": "" } } **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "name": "test-exporter" } .. http:put:: /exporters/(string: name) Updates the information or configurations of the schema exporter. All attributes in request body are optional. :param string name: Name of the exporter :json string name: Name of the exporter :statuscode 404: * Error code 40450 -- Exporter not found :statuscode 409: * Error code 40952 -- Invalid exporter subjects * Error code 40963 -- Exporter not paused **Example request**: .. sourcecode:: http PUT /exporters/test-exporter HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json { "contextType": "CUSTOM", "context": "test-context" } **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "name": "test-exporter" } .. http:put:: /exporters/(string: name)/config Updates the configurations of the schema exporter. .. note:: The payload is not wrapped in ``{"config": {}}`` as in the POST request. The configuration is directly provided. :param string name: Name of the exporter :json string name: Name of the exporter :statuscode 404: * Error code 40450 -- Exporter not found :statuscode 409: * Error code 40963 -- Exporter not paused **Example request**: .. sourcecode:: http PUT /exporters/test-exporter/config HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json { "schema.registry.url": "", "basic.auth.credentials.source": "USER_INFO", "basic.auth.user.info": "" } **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "name": "test-exporter" } .. http:get:: /exporters/(string: name) Gets the information of the schema exporter. :param string name: Name of the exporter :>json string name: Name of the exporter :>json string contextType: Context type of the exporter. One of CUSTOM, NONE or AUTO (default) :>json string context: Customized context of the exporter if contextType equals CUSTOM. :>json string subjects[i]: Name of each exporter subject :>json string subjectRenameFormat: Format string for the subject name in the destination cluster, which may contain ``${subject}`` as a placeholder for the originating subject name :>json map config: The map containing exporter's configurations :statuscode 404: * Error code 40450 -- Exporter not found **Example request**: .. sourcecode:: http GET /exporters/test-exporter HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "name": "test-exporter", "contextType": "CUSTOM", "context": "test-context", "subjects": ["foo"], "config": { "schema.registry.url": "", "basic.auth.credentials.source": "USER_INFO", "basic.auth.user.info": "[hidden]" } } .. note:: The credentials in the response will be replaced with [hidden], meaning no one is able to query the credentials through the API. .. http:get:: /exporters/(string: name)/status Gets the status of the schema exporter. :param string name: Name of the exporter :>json string name: Name of the exporter :>json string state: State of the exporter. Could be STARTING, RUNNING or PAUSED :>json long offset: Offset of the exporter :>json long ts: Timestamp of the exporter :>json string trace: Error trace of the exporter :statuscode 404: * Error code 40450 -- Exporter not found **Example request**: .. sourcecode:: http GET /exporters/test-exporter/status HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "name": "test-exporter", "state": "RUNNING", "offset": 100, "ts": 1631206325, "trace": "" } .. http:get:: /exporters/(string: name)/config Gets the configurations of the schema exporter. .. note:: The response payload is not wrapped in ``{"config": {}}`` as in the POST request. The configuration is directly provided. :param string name: Name of the exporter :>json map config: The map containing exporter's configurations :statuscode 404: * Error code 40450 -- Exporter not found **Example request**: .. sourcecode:: http GET /exporters/test-exporter/config HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "schema.registry.url": "", "basic.auth.credentials.source": "USER_INFO", "basic.auth.user.info": "[hidden]" } .. http:put:: /exporters/(string: name)/pause Pauses the schema exporter. :param string name: Name of the exporter :>json string name: Name of the exporter :statuscode 404: * Error code 40450 -- Exporter not found :statuscode 409: * Error code 40962 -- Exporter already starting **Example request**: .. sourcecode:: http PUT /exporters/test-exporter/pause HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "name": "test-exporter" } .. http:put:: /exporters/(string: name)/reset Resets the schema exporter. :param string name: Name of the exporter :>json string name: Name of the exporter :statuscode 404: * Error code 40450 -- Exporter not found :statuscode 409: * Error code 40963 -- Exporter not paused **Example request**: .. sourcecode:: http PUT /exporters/test-exporter/reset HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "name": "test-exporter" } .. http:put:: /exporters/(string: name)/resume Resumes the schema exporter. :param string name: Name of the exporter :>json string name: Name of the exporter :statuscode 404: * Error code 40450 -- Exporter not found :statuscode 409: * Error code 40961 -- Exporter already running **Example request**: .. sourcecode:: http PUT /exporters/test-exporter/resume HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/vnd.schemaregistry.v1+json { "name": "test-exporter" } .. http:delete:: /exporters/(string: name) Deletes the schema exporter. :param string name: Name of the exporter :statuscode 404: * Error code 40450 -- Exporter not found **Example request**: .. sourcecode:: http DELETE /exporters/test-exporter HTTP/1.1 Host: schemaregistry.example.com Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json **Example response**: .. sourcecode:: http HTTP/1.1 204 No Content Related Content --------------- * :ref:`schemaregistry_using` * :ref:`schema_registry_onprem_tutorial`