pulsar-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From GitBox <...@apache.org>
Subject [GitHub] sijie closed pull request #2319: [website] generate swagger definitions for schema API and update schema documentation
Date Tue, 07 Aug 2018 01:52:19 GMT
sijie closed pull request #2319: [website] generate swagger definitions for schema API and
update schema documentation
URL: https://github.com/apache/incubator-pulsar/pull/2319
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/SchemasResource.java
b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/SchemasResource.java
index 8bc511d596..ab323aaa9e 100644
--- a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/SchemasResource.java
+++ b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/SchemasResource.java
@@ -24,7 +24,13 @@
 
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.Charsets;
+import io.swagger.annotations.Api;
 import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.Example;
+import io.swagger.annotations.ExampleProperty;
 import java.nio.ByteBuffer;
 import java.time.Clock;
 import javax.ws.rs.Consumes;
@@ -55,6 +61,11 @@
 import org.slf4j.LoggerFactory;
 
 @Path("/schemas")
+@Api(
+    value = "/schemas",
+    description = "Schemas related admin APIs",
+    tags = "schemas"
+)
 public class SchemasResource extends AdminResource {
 
     private static final Logger log = LoggerFactory.getLogger(SchemasResource.class);
@@ -82,7 +93,14 @@ private long getLongSchemaVersion(SchemaVersion schemaVersion) {
     @GET
     @Path("/{tenant}/{namespace}/{topic}/schema")
     @Produces(MediaType.APPLICATION_JSON)
-    @ApiOperation(value = "Get topic schema", response = GetSchemaResponse.class)
+    @ApiOperation(value = "Get the schema of a topic", response = GetSchemaResponse.class)
+    @ApiResponses(value = {
+        @ApiResponse(code = 307, message = "Current broker doesn't serve the namespace of
this topic"),
+        @ApiResponse(code = 401, message = "Client is not authorized or Don't have admin
permission"),
+        @ApiResponse(code = 403, message = "Client is not authenticated"),
+        @ApiResponse(code = 404, message = "Tenant or Namespace or Topic doesn't exist; or
Schema is not found for this topic"),
+        @ApiResponse(code = 412, message = "Failed to find the ownership for the topic"),
+    })
     public void getSchema(
         @PathParam("tenant") String tenant,
         @PathParam("namespace") String namespace,
@@ -124,7 +142,14 @@ public void getSchema(
     @GET
     @Path("/{tenant}/{namespace}/{topic}/schema/{version}")
     @Produces(MediaType.APPLICATION_JSON)
-    @ApiOperation(value = "Get topic schema")
+    @ApiOperation(value = "Get the schema of a topic at a given version", response = GetSchemaResponse.class)
+    @ApiResponses(value = {
+        @ApiResponse(code = 307, message = "Current broker doesn't serve the namespace of
this topic"),
+        @ApiResponse(code = 401, message = "Client is not authorized or Don't have admin
permission"),
+        @ApiResponse(code = 403, message = "Client is not authenticated"),
+        @ApiResponse(code = 404, message = "Tenant or Namespace or Topic doesn't exist; or
Schema is not found for this topic"),
+        @ApiResponse(code = 412, message = "Failed to find the ownership for the topic"),
+    })
     public void getSchema(
         @PathParam("tenant") String tenant,
         @PathParam("namespace") String namespace,
@@ -169,7 +194,14 @@ public void getSchema(
     @DELETE
     @Path("/{tenant}/{namespace}/{topic}/schema")
     @Produces(MediaType.APPLICATION_JSON)
-    @ApiOperation(value = "Delete topic schema")
+    @ApiOperation(value = "Delete the schema of a topic", response = DeleteSchemaResponse.class)
+    @ApiResponses(value = {
+        @ApiResponse(code = 307, message = "Current broker doesn't serve the namespace of
this topic"),
+        @ApiResponse(code = 401, message = "Client is not authorized or Don't have admin
permission"),
+        @ApiResponse(code = 403, message = "Client is not authenticated"),
+        @ApiResponse(code = 404, message = "Tenant or Namespace or Topic doesn't exist"),
+        @ApiResponse(code = 412, message = "Failed to find the ownership for the topic"),
+    })
     public void deleteSchema(
         @PathParam("tenant") String tenant,
         @PathParam("namespace") String namespace,
@@ -200,11 +232,28 @@ public void deleteSchema(
     @Path("/{tenant}/{namespace}/{topic}/schema")
     @Produces(MediaType.APPLICATION_JSON)
     @Consumes(MediaType.APPLICATION_JSON)
-    @ApiOperation(value = "Post topic schema")
+    @ApiOperation(value = "Update the schema of a topic", response = PostSchemaResponse.class)
+    @ApiResponses(value = {
+        @ApiResponse(code = 307, message = "Current broker doesn't serve the namespace of
this topic"),
+        @ApiResponse(code = 401, message = "Client is not authorized or Don't have admin
permission"),
+        @ApiResponse(code = 403, message = "Client is not authenticated"),
+        @ApiResponse(code = 404, message = "Tenant or Namespace or Topic doesn't exist"),
+        @ApiResponse(code = 412, message = "Failed to find the ownership for the topic"),
+    })
     public void postSchema(
         @PathParam("tenant") String tenant,
         @PathParam("namespace") String namespace,
         @PathParam("topic") String topic,
+        @ApiParam(
+            value = "A JSON value presenting a schema playload. An example of the expected
schema can be found down"
+                + " here.",
+            examples = @Example(
+                value = @ExampleProperty(
+                    mediaType = MediaType.APPLICATION_JSON,
+                    value = "{\"type\": \"STRING\", \"schema\": \"\", \"properties\": { \"key1\"
: \"value1\" + } }"
+                )
+            )
+        )
         PostSchemaPayload payload,
         @Suspended final AsyncResponse response
     ) {
diff --git a/site2/docs/admin-api-schemas.md b/site2/docs/admin-api-schemas.md
new file mode 100644
index 0000000000..dae258a024
--- /dev/null
+++ b/site2/docs/admin-api-schemas.md
@@ -0,0 +1,98 @@
+---
+id: admin-api-schemas
+title: Managing Schemas
+sidebar_label: Schemas
+---
+
+Schemas, like other entities in Pulsar, can be managed using the [admin API](admin-api-overview.md).

+
+## Schema resources
+
+A Pulsar schema is a fairly simple data structure stored in Pulsar for representing the structure
of messages stored in a Pulsar topic. The schema structure consists of:
+
+- *Name*: A schema's name is the topic that the schema is associated to.
+- *Type*: A schema type represents the type of the schema. The predefined schema types can
be found [here](concepts-schema-registry.md#supported-schema-formats). If it 
+  is a customized schema, it is left as an empty string.
+- *Payload*: It is a binary representation of the schema. How to interpret it is up to the
implementation of the schema.
+- *Properties*: It is a user defined properties as a string/string map. Applications can
use this bag for carrying any application specific logics. Possible properties
+  might be the Git hash associated with the schema, an environment string like `dev` or `prod`,
etc.
+
+All the schemas are versioned with versions. So you can retrieve the schema definition of
a given version if the version is not deleted.
+
+### Upload Schema
+
+#### pulsar-admin
+
+You can upload a new schema using the [`upload`](reference-pulsar-admin.md#get-5) subcommand:
+
+```shell
+$ pulsar-admin schemas upload <topic-name> --filename /path/to/schema-definition-file

+```
+
+The schema definition file should contain following json string on defining how the schema
look like:
+
+```json
+{
+    "type": "STRING",
+    "schema": "",
+    "properties": {
+        "key1" : "value1"
+    }
+}
+```
+
+An example of the schema definition file can be found at {@inject: github:SchemaExample:/conf/schema_example.conf}.
+
+#### REST
+
+{@inject: endpoint|POST|/admin/v2/schemas/:tenant/:namespace/:topic/schema|operation/uploadSchema}
+
+### Get Schema
+
+#### pulsar-admin
+
+You can get the latest version of Schema using the [`get`](reference-pulsar-admin.md#get-5)
subcommand.
+
+```shell
+$ pulsar-admin schemas get <topic-name>
+{
+    "version": 0,
+    "type": "String",
+    "timestamp": 0,
+    "data": "string",
+    "properties": {
+        "property1": "string",
+        "property2": "string"
+    }
+}
+```
+
+You can also retrieve the Schema of a given version by specifying `--version` option.
+
+```shell
+$ pulsar-admin schemas get <topic-name> --version <version>
+```
+
+#### REST API
+
+Retrieve the latest version of the schema:
+
+{@inject: endpoint|GET|/admin/v2/schemas/:tenant/:namespace/:topic/schema|operation/getSchema}
+
+Retrieve the schema of a given version:
+
+{@inject: endpoint|GET|/admin/v2/schemas/:tenant/:namespace/:topic/schema/:version|operation/getSchema}
+
+### Delete Schema
+
+#### pulsar-adnin
+
+You can delete a schema using the [`delete`](reference-pulsar-admin.md#delete-8) subcommand.
+
+```shell
+$ pulsar-admin schemas delete <topic-name>
+```
+
+#### REST API
+
+{@inject: endpoint|DELETE|/admin/v2/schemas/:tenant/:namespace/:topic/schema|operation/deleteSchema}
diff --git a/site2/docs/concepts-schema-registry.md b/site2/docs/concepts-schema-registry.md
index cd6289332f..838ff4c182 100644
--- a/site2/docs/concepts-schema-registry.md
+++ b/site2/docs/concepts-schema-registry.md
@@ -18,7 +18,7 @@ Both approaches are available in Pulsar, and you're free to adopt one or
the oth
 
 ## Basic architecture
 
-In Pulsar, schemas are uploaded to, fetched from, and update via Pulsar's {@inject: rest:REST:/}
API.
+Schemas are automatically uploaded when you create a typed Producer with a Schema. Additionally,
Schemas can be manually uploaded to, fetched from, and updated via Pulsar's {@inject: rest:REST:tag/schemas}
API.
 
 > #### Other schema registry backends
 > Out of the box, Pulsar uses the [Apache BookKeeper](concepts-architecture-overview#persistent-storage)
log storage system for schema storage. You can, however, use different backends if you wish.
Documentation for custom schema storage logic is coming soon.
@@ -75,3 +75,7 @@ For usage instructions, see the documentation for your preferred client
library:
 * [Java](client-libraries-java.md#schemas)
 
 > Support for other schema formats will be added in future releases of Pulsar.
+
+## Managing Schemas
+
+You can use Pulsar's [admin tools](admin-api-schemas.md) for managing schemas for topics.
diff --git a/site2/website/sidebars.json b/site2/website/sidebars.json
index 56de30b28e..f321d30b43 100644
--- a/site2/website/sidebars.json
+++ b/site2/website/sidebars.json
@@ -75,7 +75,8 @@
       "admin-api-permissions",
       "admin-api-persistent-topics",
       "admin-api-non-persistent-topics",
-      "admin-api-partitioned-topics"
+      "admin-api-partitioned-topics",
+      "admin-api-schemas"
     ],
     "Adaptors": [
       "adaptors-kafka",
diff --git a/site2/website/static/swagger/swagger.json b/site2/website/static/swagger/swagger.json
index b57004d4e7..19ac427ee9 100644
--- a/site2/website/static/swagger/swagger.json
+++ b/site2/website/static/swagger/swagger.json
@@ -26,6 +26,8 @@
     "name" : "persistent topic"
   }, {
     "name" : "resource-quotas"
+  }, {
+    "name" : "schemas"
   }, {
     "name" : "tenants"
   } ],
@@ -1074,6 +1076,105 @@
         }
       }
     },
+    "/namespaces/{property}/{namespace}/offloadDeletionLagMs" : {
+      "get" : {
+        "tags" : [ "namespaces" ],
+        "summary" : "Number of milliseconds to wait before deleting a ledger segment which
has been offloaded from the Pulsar cluster's local storage (i.e. BookKeeper)",
+        "description" : "A negative value denotes that deletion has been completely disabled.
'null' denotes that the topics in the namespace will fall back to the broker default for deletion
lag.",
+        "operationId" : "getOffloadDeletionLag",
+        "consumes" : [ "application/json" ],
+        "produces" : [ "application/json" ],
+        "parameters" : [ {
+          "name" : "property",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        }, {
+          "name" : "namespace",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "successful operation",
+            "schema" : {
+              "type" : "integer",
+              "format" : "int64"
+            }
+          },
+          "403" : {
+            "description" : "Don't have admin permission"
+          },
+          "404" : {
+            "description" : "Namespace doesn't exist"
+          }
+        }
+      },
+      "put" : {
+        "tags" : [ "namespaces" ],
+        "summary" : "Set number of milliseconds to wait before deleting a ledger segment
which has been offloaded from the Pulsar cluster's local storage (i.e. BookKeeper)",
+        "description" : "A negative value disables the deletion completely.",
+        "operationId" : "setOffloadDeletionLag",
+        "consumes" : [ "application/json" ],
+        "produces" : [ "application/json" ],
+        "parameters" : [ {
+          "name" : "property",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        }, {
+          "name" : "namespace",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        } ],
+        "responses" : {
+          "403" : {
+            "description" : "Don't have admin permission"
+          },
+          "404" : {
+            "description" : "Namespace doesn't exist"
+          },
+          "409" : {
+            "description" : "Concurrent modification"
+          },
+          "412" : {
+            "description" : "offloadDeletionLagMs value is not valid"
+          }
+        }
+      },
+      "delete" : {
+        "tags" : [ "namespaces" ],
+        "summary" : "Clear the namespace configured offload deletion lag. The topics in the
namespace will fallback to using the default configured deletion lag for the broker",
+        "description" : "",
+        "operationId" : "clearOffloadDeletionLag",
+        "consumes" : [ "application/json" ],
+        "produces" : [ "application/json" ],
+        "parameters" : [ {
+          "name" : "property",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        }, {
+          "name" : "namespace",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        } ],
+        "responses" : {
+          "403" : {
+            "description" : "Don't have admin permission"
+          },
+          "404" : {
+            "description" : "Namespace doesn't exist"
+          },
+          "409" : {
+            "description" : "Concurrent modification"
+          }
+        }
+      }
+    },
     "/namespaces/{property}/{namespace}/offloadThreshold" : {
       "get" : {
         "tags" : [ "namespaces" ],
@@ -5699,6 +5800,211 @@
         }
       }
     },
+    "/schemas/{tenant}/{namespace}/{topic}/schema" : {
+      "get" : {
+        "tags" : [ "schemas" ],
+        "summary" : "Get the schema of a topic",
+        "description" : "",
+        "operationId" : "getSchema",
+        "produces" : [ "application/json" ],
+        "parameters" : [ {
+          "name" : "tenant",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        }, {
+          "name" : "namespace",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        }, {
+          "name" : "topic",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "successful operation",
+            "schema" : {
+              "$ref" : "#/definitions/GetSchemaResponse"
+            }
+          },
+          "307" : {
+            "description" : "Current broker doesn't serve the namespace of this topic"
+          },
+          "401" : {
+            "description" : "Client is not authorized or Don't have admin permission"
+          },
+          "403" : {
+            "description" : "Client is not authenticated"
+          },
+          "404" : {
+            "description" : "Tenant or Namespace or Topic doesn't exist; or Schema is not
found for this topic"
+          },
+          "412" : {
+            "description" : "Failed to find the ownership for the topic"
+          }
+        }
+      },
+      "post" : {
+        "tags" : [ "schemas" ],
+        "summary" : "Update the schema of a topic",
+        "description" : "",
+        "operationId" : "postSchema",
+        "consumes" : [ "application/json" ],
+        "produces" : [ "application/json" ],
+        "parameters" : [ {
+          "name" : "tenant",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        }, {
+          "name" : "namespace",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        }, {
+          "name" : "topic",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        }, {
+          "in" : "body",
+          "name" : "body",
+          "description" : "A JSON value presenting a schema playload. An example of the expected
schema can be found down here.",
+          "required" : false,
+          "schema" : {
+            "$ref" : "#/definitions/PostSchemaPayload"
+          },
+          "x-examples" : {
+            "application/json" : "{\"type\": \"STRING\", \"schema\": \"\", \"properties\":
{ \"key1\" : \"value1\" + } }"
+          }
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "successful operation",
+            "schema" : {
+              "$ref" : "#/definitions/PostSchemaResponse"
+            }
+          },
+          "307" : {
+            "description" : "Current broker doesn't serve the namespace of this topic"
+          },
+          "401" : {
+            "description" : "Client is not authorized or Don't have admin permission"
+          },
+          "403" : {
+            "description" : "Client is not authenticated"
+          },
+          "404" : {
+            "description" : "Tenant or Namespace or Topic doesn't exist"
+          },
+          "412" : {
+            "description" : "Failed to find the ownership for the topic"
+          }
+        }
+      },
+      "delete" : {
+        "tags" : [ "schemas" ],
+        "summary" : "Delete the schema of a topic",
+        "description" : "",
+        "operationId" : "deleteSchema",
+        "produces" : [ "application/json" ],
+        "parameters" : [ {
+          "name" : "tenant",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        }, {
+          "name" : "namespace",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        }, {
+          "name" : "topic",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "successful operation",
+            "schema" : {
+              "$ref" : "#/definitions/DeleteSchemaResponse"
+            }
+          },
+          "307" : {
+            "description" : "Current broker doesn't serve the namespace of this topic"
+          },
+          "401" : {
+            "description" : "Client is not authorized or Don't have admin permission"
+          },
+          "403" : {
+            "description" : "Client is not authenticated"
+          },
+          "404" : {
+            "description" : "Tenant or Namespace or Topic doesn't exist"
+          },
+          "412" : {
+            "description" : "Failed to find the ownership for the topic"
+          }
+        }
+      }
+    },
+    "/schemas/{tenant}/{namespace}/{topic}/schema/{version}" : {
+      "get" : {
+        "tags" : [ "schemas" ],
+        "summary" : "Get the schema of a topic at a given version",
+        "description" : "",
+        "operationId" : "getSchema",
+        "produces" : [ "application/json" ],
+        "parameters" : [ {
+          "name" : "tenant",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        }, {
+          "name" : "namespace",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        }, {
+          "name" : "topic",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        }, {
+          "name" : "version",
+          "in" : "path",
+          "required" : true,
+          "type" : "string"
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "successful operation",
+            "schema" : {
+              "$ref" : "#/definitions/GetSchemaResponse"
+            }
+          },
+          "307" : {
+            "description" : "Current broker doesn't serve the namespace of this topic"
+          },
+          "401" : {
+            "description" : "Client is not authorized or Don't have admin permission"
+          },
+          "403" : {
+            "description" : "Client is not authenticated"
+          },
+          "404" : {
+            "description" : "Tenant or Namespace or Topic doesn't exist; or Schema is not
found for this topic"
+          },
+          "412" : {
+            "description" : "Failed to find the ownership for the topic"
+          }
+        }
+      }
+    },
     "/tenants" : {
       "get" : {
         "tags" : [ "tenants" ],
@@ -6034,10 +6340,10 @@
         "address" : {
           "type" : "string"
         },
-        "clientVersion" : {
+        "connectedSince" : {
           "type" : "string"
         },
-        "connectedSince" : {
+        "clientVersion" : {
           "type" : "string"
         }
       }
@@ -6109,6 +6415,15 @@
         }
       }
     },
+    "DeleteSchemaResponse" : {
+      "type" : "object",
+      "properties" : {
+        "version" : {
+          "type" : "integer",
+          "format" : "int64"
+        }
+      }
+    },
     "DispatchRate" : {
       "type" : "object",
       "properties" : {
@@ -6138,6 +6453,32 @@
         }
       }
     },
+    "GetSchemaResponse" : {
+      "type" : "object",
+      "properties" : {
+        "version" : {
+          "type" : "integer",
+          "format" : "int64"
+        },
+        "type" : {
+          "type" : "string",
+          "enum" : [ "NONE", "STRING", "JSON", "PROTOBUF", "AVRO" ]
+        },
+        "timestamp" : {
+          "type" : "integer",
+          "format" : "int64"
+        },
+        "data" : {
+          "type" : "string"
+        },
+        "properties" : {
+          "type" : "object",
+          "additionalProperties" : {
+            "type" : "string"
+          }
+        }
+      }
+    },
     "InternalConfigurationData" : {
       "type" : "object",
       "properties" : {
@@ -6319,24 +6660,24 @@
           "type" : "number",
           "format" : "double"
         },
-        "lastUpdate" : {
-          "type" : "integer",
-          "format" : "int64"
+        "cpu" : {
+          "$ref" : "#/definitions/ResourceUsage"
         },
-        "bandwidthIn" : {
+        "directMemory" : {
           "$ref" : "#/definitions/ResourceUsage"
         },
-        "bandwidthOut" : {
+        "bandwidthIn" : {
           "$ref" : "#/definitions/ResourceUsage"
         },
         "memory" : {
           "$ref" : "#/definitions/ResourceUsage"
         },
-        "cpu" : {
+        "bandwidthOut" : {
           "$ref" : "#/definitions/ResourceUsage"
         },
-        "directMemory" : {
-          "$ref" : "#/definitions/ResourceUsage"
+        "lastUpdate" : {
+          "type" : "integer",
+          "format" : "int64"
         },
         "msgThroughputIn" : {
           "type" : "number",
@@ -6346,14 +6687,14 @@
           "type" : "number",
           "format" : "double"
         },
-        "underLoaded" : {
-          "type" : "boolean"
-        },
         "overLoaded" : {
           "type" : "boolean"
         },
         "loadReportType" : {
           "type" : "string"
+        },
+        "underLoaded" : {
+          "type" : "boolean"
         }
       }
     },
@@ -6516,10 +6857,10 @@
         "address" : {
           "type" : "string"
         },
-        "clientVersion" : {
+        "connectedSince" : {
           "type" : "string"
         },
-        "connectedSince" : {
+        "clientVersion" : {
           "type" : "string"
         },
         "producerName" : {
@@ -7008,6 +7349,10 @@
         "offload_threshold" : {
           "type" : "integer",
           "format" : "int64"
+        },
+        "offload_deletion_lag_ms" : {
+          "type" : "integer",
+          "format" : "int64"
         }
       }
     },
@@ -7163,6 +7508,31 @@
         }
       }
     },
+    "PostSchemaPayload" : {
+      "type" : "object",
+      "properties" : {
+        "type" : {
+          "type" : "string"
+        },
+        "schema" : {
+          "type" : "string"
+        },
+        "properties" : {
+          "type" : "object",
+          "additionalProperties" : {
+            "type" : "string"
+          }
+        }
+      }
+    },
+    "PostSchemaResponse" : {
+      "type" : "object",
+      "properties" : {
+        "version" : {
+          "$ref" : "#/definitions/SchemaVersion"
+        }
+      }
+    },
     "PublisherStats" : {
       "type" : "object",
       "properties" : {
@@ -7191,10 +7561,10 @@
         "address" : {
           "type" : "string"
         },
-        "clientVersion" : {
+        "connectedSince" : {
           "type" : "string"
         },
-        "connectedSince" : {
+        "clientVersion" : {
           "type" : "string"
         },
         "producerName" : {
@@ -7253,15 +7623,15 @@
     "ResourceDescription" : {
       "type" : "object",
       "properties" : {
+        "usagePct" : {
+          "type" : "integer",
+          "format" : "int32"
+        },
         "resourceUsage" : {
           "type" : "object",
           "additionalProperties" : {
             "$ref" : "#/definitions/ResourceUsage"
           }
-        },
-        "usagePct" : {
-          "type" : "integer",
-          "format" : "int32"
         }
       }
     },
@@ -7296,11 +7666,11 @@
     "ResourceUnit" : {
       "type" : "object",
       "properties" : {
-        "availableResource" : {
-          "$ref" : "#/definitions/ResourceDescription"
-        },
         "resourceId" : {
           "type" : "string"
+        },
+        "availableResource" : {
+          "$ref" : "#/definitions/ResourceDescription"
         }
       }
     },
@@ -7330,6 +7700,9 @@
         }
       }
     },
+    "SchemaVersion" : {
+      "type" : "object"
+    },
     "SubscriptionStats" : {
       "type" : "object",
       "properties" : {
diff --git a/site2/website/versioned_docs/version-2.1.0-incubating/admin-api-schemas.md b/site2/website/versioned_docs/version-2.1.0-incubating/admin-api-schemas.md
new file mode 100644
index 0000000000..8b2e528f33
--- /dev/null
+++ b/site2/website/versioned_docs/version-2.1.0-incubating/admin-api-schemas.md
@@ -0,0 +1,99 @@
+---
+id: version-2.1.0-incubating-admin-api-schemas
+title: Managing Schemas
+sidebar_label: Schemas
+original_id: admin-api-schemas
+---
+
+Schemas, like other entities in Pulsar, can be managed using the [admin API](admin-api-overview.md).

+
+## Schema resources
+
+A Pulsar schema is a fairly simple data structure stored in Pulsar for representing the structure
of messages stored in a Pulsar topic. The schema structure consists of:
+
+- *Name*: A schema's name is the topic that the schema is associated to.
+- *Type*: A schema type represents the type of the schema. The predefined schema types can
be found [here](concepts-schema-registry.md#supported-schema-formats). If it 
+  is a customized schema, it is left as an empty string.
+- *Payload*: It is a binary representation of the schema. How to interpret it is up to the
implementation of the schema.
+- *Properties*: It is a user defined properties as a string/string map. Applications can
use this bag for carrying any application specific logics. Possible properties
+  might be the Git hash associated with the schema, an environment string like `dev` or `prod`,
etc.
+
+All the schemas are versioned with versions. So you can retrieve the schema definition of
a given version if the version is not deleted.
+
+### Upload Schema
+
+#### pulsar-admin
+
+You can upload a new schema using the [`upload`](reference-pulsar-admin.md#get-5) subcommand:
+
+```shell
+$ pulsar-admin schemas upload <topic-name> --filename /path/to/schema-definition-file

+```
+
+The schema definition file should contain following json string on defining how the schema
look like:
+
+```json
+{
+    "type": "STRING",
+    "schema": "",
+    "properties": {
+        "key1" : "value1"
+    }
+}
+```
+
+An example of the schema definition file can be found at {@inject: github:SchemaExample:/conf/schema_example.conf}.
+
+#### REST
+
+{@inject: endpoint|POST|/admin/v2/schemas/:tenant/:namespace/:topic/schema|operation/uploadSchema}
+
+### Get Schema
+
+#### pulsar-admin
+
+You can get the latest version of Schema using the [`get`](reference-pulsar-admin.md#get-5)
subcommand.
+
+```shell
+$ pulsar-admin schemas get <topic-name>
+{
+    "version": 0,
+    "type": "String",
+    "timestamp": 0,
+    "data": "string",
+    "properties": {
+        "property1": "string",
+        "property2": "string"
+    }
+}
+```
+
+You can also retrieve the Schema of a given version by specifying `--version` option.
+
+```shell
+$ pulsar-admin schemas get <topic-name> --version <version>
+```
+
+#### REST API
+
+Retrieve the latest version of the schema:
+
+{@inject: endpoint|GET|/admin/v2/schemas/:tenant/:namespace/:topic/schema|operation/getSchema}
+
+Retrieve the schema of a given version:
+
+{@inject: endpoint|GET|/admin/v2/schemas/:tenant/:namespace/:topic/schema/:version|operation/getSchema}
+
+### Delete Schema
+
+#### pulsar-adnin
+
+You can delete a schema using the [`delete`](reference-pulsar-admin.md#delete-8) subcommand.
+
+```shell
+$ pulsar-admin schemas delete <topic-name>
+```
+
+#### REST API
+
+{@inject: endpoint|DELETE|/admin/v2/schemas/:tenant/:namespace/:topic/schema|operation/deleteSchema}
diff --git a/site2/website/versioned_docs/version-2.1.0-incubating/concepts-schema-registry.md
b/site2/website/versioned_docs/version-2.1.0-incubating/concepts-schema-registry.md
index 6dfdbebee5..cd6531031c 100644
--- a/site2/website/versioned_docs/version-2.1.0-incubating/concepts-schema-registry.md
+++ b/site2/website/versioned_docs/version-2.1.0-incubating/concepts-schema-registry.md
@@ -19,7 +19,7 @@ Both approaches are available in Pulsar, and you're free to adopt one or
the oth
 
 ## Basic architecture
 
-In Pulsar, schemas are uploaded to, fetched from, and update via Pulsar's {@inject: rest:REST:/}
API.
+Schemas are automatically uploaded when you create a typed Producer with a Schema. Additionally,
Schemas can be manually uploaded to, fetched from, and updated via Pulsar's {@inject: rest:REST:tag/schemas}
API.
 
 > #### Other schema registry backends
 > Out of the box, Pulsar uses the [Apache BookKeeper](concepts-architecture-overview#persistent-storage)
log storage system for schema storage. You can, however, use different backends if you wish.
Documentation for custom schema storage logic is coming soon.
@@ -76,3 +76,7 @@ For usage instructions, see the documentation for your preferred client
library:
 * [Java](client-libraries-java.md#schemas)
 
 > Support for other schema formats will be added in future releases of Pulsar.
+
+## Managing Schemas
+
+You can use Pulsar's [admin tools](admin-api-schemas.md) for managing schemas for topics.
diff --git a/site2/website/versioned_sidebars/version-2.1.0-incubating-sidebars.json b/site2/website/versioned_sidebars/version-2.1.0-incubating-sidebars.json
index 78c05075ff..4523d85e6a 100644
--- a/site2/website/versioned_sidebars/version-2.1.0-incubating-sidebars.json
+++ b/site2/website/versioned_sidebars/version-2.1.0-incubating-sidebars.json
@@ -75,7 +75,8 @@
       "version-2.1.0-incubating-admin-api-permissions",
       "version-2.1.0-incubating-admin-api-persistent-topics",
       "version-2.1.0-incubating-admin-api-non-persistent-topics",
-      "version-2.1.0-incubating-admin-api-partitioned-topics"
+      "version-2.1.0-incubating-admin-api-partitioned-topics",
+      "version-2.1.0-incubating-admin-api-schemas"
     ],
     "Adaptors": [
       "version-2.1.0-incubating-adaptors-kafka",


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services

Mime
View raw message