<commit_before>.. _schemaregistry_api:

API Reference
=============

Overview
--------

Compatibility
^^^^^^^^^^^^^

The schema registry server can enforce certain compatibility rules when new schemas are registered in a subject. Currently, we support the following compatibility rules.

  * Backward compatibility (default): A new schema is backward compatible if it can be used to read the data written in all previous schemas. Backward compatibility is useful for loading data into systems like Hadoop since one can always query data of all versions using the latest schema.
  * Forward compatibility: A new schema is forward compatible if all previous schemas can read data written in this schema. Forward compatibility is useful for consumer applications that can only deal with data in a particular version that may not always be the latest version.
  * Full compatibility: A new schema is fully compatible if it’s both backward and forward compatible.
  * No compatibility: A new schema can be any schema as long as it’s a valid Avro.

We recommend keeping the default backward compatibility since it's common to have all data loaded into Hadoop.

.. ifconfig:: platform_docs

   More details on Avro schema resolution can be found :ref:`here <serialization_and_evolution>`.

.. ifconfig:: not platform_docs

   More details on Avro schema resolution can be found `here <http://avro.apache.org/docs/1.7.7/spec.html#Schema+Resolution>`_.

Content Types
^^^^^^^^^^^^^

The schema registry 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 OK
      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.


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

   :>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**:
<commit_msg>Fix status message for 422 example in API docs.<commit_after>.. _schemaregistry_api:

API Reference
=============

Overview
--------

Compatibility
^^^^^^^^^^^^^

The schema registry server can enforce certain compatibility rules when new schemas are registered in a subject. Currently, we support the following compatibility rules.

  * Backward compatibility (default): A new schema is backward compatible if it can be used to read the data written in all previous schemas. Backward compatibility is useful for loading data into systems like Hadoop since one can always query data of all versions using the latest schema.
  * Forward compatibility: A new schema is forward compatible if all previous schemas can read data written in this schema. Forward compatibility is useful for consumer applications that can only deal with data in a particular version that may not always be the latest version.
  * Full compatibility: A new schema is fully compatible if it’s both backward and forward compatible.
  * No compatibility: A new schema can be any schema as long as it’s a valid Avro.

We recommend keeping the default backward compatibility since it's common to have all data loaded into Hadoop.

.. ifconfig:: platform_docs

   More details on Avro schema resolution can be found :ref:`here <serialization_and_evolution>`.

.. ifconfig:: not platform_docs

   More details on Avro schema resolution can be found `here <http://avro.apache.org/docs/1.7.7/spec.html#Schema+Resolution>`_.

Content Types
^^^^^^^^^^^^^

The schema registry 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.


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

   :>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**:

{'fraction_non_alphanumeric': 0.07079979879275654, 'fraction_numerical': 0.01119215291750503, 'mean_word_length': 4.081789137380191, 'pattern_counts': {'":': 4, '<': 7, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3892001', 'n_tokens_mistral': 2000, 'n_tokens_neox': 1871, 'n_words': 1075}