CLIENTS-286 CLIENTS-288

docs/api.rst

@@ -142,7 +142,7 @@ The subjects resource provides a list of all registered subjects in your schema
 
    :statuscode 404:
       * Error code 40401 -- Subject not found
-   :statuscode 500: 
+   :statuscode 500:
       * Error code 50001 -- Error in the backend datastore
 
    **Example request**:
@@ -164,6 +164,38 @@ The subjects resource provides a list of all registered subjects in your schema
         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 development environment.
+
+   :param string subject: the name of the subject
+
+   :>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
@@ -332,6 +364,40 @@ The subjects resource provides a list of all registered subjects in your schema
 		    }"
 	  }
 
+.. http:delete:: /subjects/(string: subject)/versions/(versionId: version)
+
+   Deletes a specific version of the schema registered under this subject. This only deletes the version and the schema id remains intact 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". "latest" deletes the last registered schema under the specified subject. Note that there may be a new latest schema that gets registered right after this request is served.
+
+   :>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
+
 Compatibility
 -------------
 

docs/index.rst

@@ -19,4 +19,5 @@ Contents:
    operations
    security
    serializer-formatter
+   schema-deletion-guidelines
    maven-plugin

docs/intro.rst

@@ -51,15 +51,35 @@ Start by running the Schema Registry and the services it depends on: ZooKeeper a
     $ curl -X GET http://localhost:8081/subjects/Kafka-value/versions/1
       {"subject":"Kafka-value","version":1,"id":1,"schema":"\"string\""}
 
-    # Fetch the most recently registered schema under subject "Kafka-value"
-    $ curl -X GET http://localhost:8081/subjects/Kafka-value/versions/latest
-      {"subject":"Kafka-value","version":1,"id":1,"schema":"\"string\""}
+    # Deletes version 1 of the schema registered under subject "Kafka-value"
+    $ curl -X DELETE http://localhost:8081/subjects/Kafka-value/versions/1
+      1
+
+    # Register the same schema under the subject "Kafka-value"
+    $ curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
+        --data '{"schema": "{\"type\": \"string\"}"}' \
+         http://localhost:8081/subjects/Kafka-value/versions
+      {"id":1}
+
+    # Deletes the most recently registered schema under subject "Kafka-value"
+    $ curl -X DELETE http://localhost:8081/subjects/Kafka-value/versions/latest
+      2
+
+    # Register the same schema under the subject "Kafka-value"
+    $ curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
+        --data '{"schema": "{\"type\": \"string\"}"}' \
+         http://localhost:8081/subjects/Kafka-value/versions
+      {"id":1}
+
+    # Fetch the schema again by globally unique id 1
+    $ curl -X GET http://localhost:8081/schemas/ids/1
+      {"schema":"\"string\""}
 
     # Check whether a schema has been registered under subject "Kafka-key"
     $ 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":1,"id":1,"schema":"\"string\""}
+      {"subject":"Kafka-key","version":3,"id":1,"schema":"\"string\""}
 
     # Test compatibility of a schema with the latest schema under subject "Kafka-value"
     $ curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
@@ -83,6 +103,14 @@ Start by running the Schema Registry and the services it depends on: ZooKeeper a
         http://localhost:8081/config/Kafka-value
       {"compatibility":"BACKWARD"}
 
+    # Deletes all schema versions registered under the subject "Kafka-value"
+    $ curl -X DELETE http://localhost:8081/subjects/Kafka-value
+      [3]
+
+    # List all subjects
+    $ curl -X GET http://localhost:8081/subjects
+      ["Kafka-key"]
+
 Installation
 ------------
 

docs/schema-deletion-guidelines.rst

@@ -0,0 +1,29 @@
+.. _schemaregistry_api:
+
+Schema Deletion Guidelines
+==========================
+
+Schema Registry API supports deleting a specific schema version or all versions of a subject. The API only deletes the version and the underlying schema id would still be available for any lookup.
+
+.. sourcecode:: bash
+
+    # Deletes all schema versions registered under the subject "Kafka-value"
+    $ curl -X DELETE http://localhost:8081/subjects/Kafka-value
+      [1]
+
+    # Deletes version 1 of the schema registered under subject "Kafka-value"
+    $ curl -X DELETE http://localhost:8081/subjects/Kafka-value/versions/1
+      1
+
+    # Deletes the most recently registered schema under subject "Kafka-value"
+    $ curl -X DELETE http://localhost:8081/subjects/Kafka-value/versions/latest
+      1
+
+The above API's are primarily intended to be used be in development environment where it's common to go through iterations before finalizing a schema. While it's not recommended to be used in a production environment, there are few scenarios where these API's can be used in production but with utmost care.
+
+- A new schema to be registered has compatibility issues with one of the existing schema versions
+- An old version of the schema needs to be registered again for the same subject
+- The schema's are used only in real-time streaming systems and the older version(s) are absolutely no longer required
+- A topic needs to be recycled
+
+It is also important to note that any registered compatibility settings for the subject would also be deleted while using Delete Subject or when you delete the only available schema version.