diff --git a/README.md b/README.md index df640f4e..574ccf52 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ docker pull odpf/stencil:latest To pull a specific version: ``` -docker pull odpf/stencil:v0.2.2 +docker pull odpf/stencil:v0.3.0 ``` ## Usage diff --git a/clients/clojure/README.md b/clients/clojure/README.md index 86870be4..19435d8d 100644 --- a/clients/clojure/README.md +++ b/clients/clojure/README.md @@ -1,17 +1,19 @@ # Stencil Clojure Client -A Clojure library designed to easily encode and decode protobuf messages by using Clojure maps. +A Clojure library designed to easily encode and decode protobuf messages by using Clojure maps. ## Installation Add the below dependency to your `project.clj` file: + ```clj - [io.odpf/stencil-clj "0.2.2"] + [io.odpf/stencil-clj "0.3.0"] ``` ## Usage Consider following proto message + ```proto syntax = "proto3"; @@ -39,6 +41,7 @@ message Person { int32 age = 5; } ``` + 1. Create stencil client. You can refer to [java client](../java) documentation for all available options. ```clojure @@ -52,6 +55,7 @@ message Person { ``` 2. To serialize data from clojure map + ```clojure (:require [stencil.core :refer [serialize]]) @@ -64,6 +68,7 @@ message Person { ``` 3. Deserialize data from bytes to clojure map + ```clojure (:require [stencil.core :refer [deserialize]]) @@ -78,40 +83,44 @@ message Person { ## Protocol buffers - Clojure interop -| Protobuf | Clojure | Notes | -| ----------- | --------------------------- | ---------------- | -| field names | keywords in kebab case | `name` -> `:name`, `field_name` -> `:field-name` | -| scalar fields | Values follow [protobuf-java scalar value mappings](https://developers.google.com/protocol-buffers/docs/proto3#scalar) | | -| enums | Values converted as keywords of enum's original value | `UNKNOWN` -> `:UNKNOWN` | -| messages | clojure map | ```message Hello {string name = 1;}``` -> {:name "odpf"} | -| repeated fields | clojure vector | | -| one-of fields | treated as regular fields | if two fields are set that are part of one-of, last seen value is considered while serializing data | -| map | map values follow it's [wire representation](https://developers.google.com/protocol-buffers/docs/proto3#backwards_compatibility) | for `map` type, example value will be `[{:key "key" :value "value"}]` | +| Protobuf | Clojure | Notes | +| --------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| field names | keywords in kebab case | `name` -> `:name`, `field_name` -> `:field-name` | +| scalar fields | Values follow [protobuf-java scalar value mappings](https://developers.google.com/protocol-buffers/docs/proto3#scalar) | | +| enums | Values converted as keywords of enum's original value | `UNKNOWN` -> `:UNKNOWN` | +| messages | clojure map | `message Hello {string name = 1;}` -> {:name "odpf"} | +| repeated fields | clojure vector | | +| one-of fields | treated as regular fields | if two fields are set that are part of one-of, last seen value is considered while serializing data | +| map | map values follow it's [wire representation](https://developers.google.com/protocol-buffers/docs/proto3#backwards_compatibility) | for `map` type, example value will be `[{:key "key" :value "value"}]` | **Note on errors:** Serialize will throw error in following cases + 1. unknown field is passed that's not present in schema `{:cause :unknown-field :info {:field-name }}` 2. if non-collection type is passed to repeated field `{:cause :not-a-collection :info {:value }}` 3. If unknown enum value passed that's not present in schema `{:cause :unknown-enum-value :info {:field-name }}` ## API + - `create-client (client-config)` Returns a new Stencil Clojure client instance by passing client-config. ### Client config structure : - | Key | Type | Description | - | -----------------------|-----------|---------------------------------------------------------------------------------------------| - | `url` | _String_ | Stencil url to fetch latest descriptor sets | - | `refresh-cache` | _Boolean_ | Whether the cache should be refreshed or not | - | `refresh-ttl` | _Integer_ | Cache TTL in minutes | - | `request-timeout` | _Integer_ | Request timeout in milliseconds | - | `request-backoff-time` | _Integer_ | Request back off time in minutes | - | `retry-count` | _Integer_ | Number of retries to be made to fetch descriptor sets | - | `headers` | _Map_ | Map with key as header key and value as header value, which will be passed to stencil server| - | `refresh-strategy` | _keyword_ | Possible values :version-based-refresh, :long-polling-refresh. Default :long-polling-refresh| + + | Key | Type | Description | + | ---------------------- | --------- | -------------------------------------------------------------------------------------------- | + | `url` | _String_ | Stencil url to fetch latest descriptor sets | + | `refresh-cache` | _Boolean_ | Whether the cache should be refreshed or not | + | `refresh-ttl` | _Integer_ | Cache TTL in minutes | + | `request-timeout` | _Integer_ | Request timeout in milliseconds | + | `request-backoff-time` | _Integer_ | Request back off time in minutes | + | `retry-count` | _Integer_ | Number of retries to be made to fetch descriptor sets | + | `headers` | _Map_ | Map with key as header key and value as header value, which will be passed to stencil server | + | `refresh-strategy` | _keyword_ | Possible values :version-based-refresh, :long-polling-refresh. Default :long-polling-refresh | Example: + ```clojure (let [sample-client-config {:url "https://example-url" :refresh-cache true @@ -130,17 +139,20 @@ Serialize will throw error in following cases Returns protobuf descriptor object for the given protobuf class name. ### Argument list : - | Key | Type | Description | - | ------------------------------------------------|-------------------|-----------------------------------------------------------------------------| - | `client` | _Object_ | Instantiated Clojure client object | - | `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required | + + | Key | Type | Description | + | ------------------ | -------- | ----------------------------------------------------------------- | + | `client` | _Object_ | Instantiated Clojure client object | + | `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required | ### Response structure - | Value | Type | Description | - |-------------------------------------------------|-------------------|-----------------------------------------------------------------------------| - | **proto-desc** | _Object_ | Protobuf descriptor for given proto class name | + + | Value | Type | Description | + | -------------- | -------- | ---------------------------------------------- | + | **proto-desc** | _Object_ | Protobuf descriptor for given proto class name | Example: + ```clojure (let [client (create-client sample-client-config) proto-package "io.odpf.stencil_clj_test" @@ -154,18 +166,21 @@ Serialize will throw error in following cases Returns Clojure map for the given protobuf encoded byte array and protobuf class name. ### Argument list : - | Key | Type | Description | - | ------------------------------------------------|---------------------|-----------------------------------------------------------------------------| - | `client` | _Object_ | Instantiated Clojure client object | - | `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required | - | `data` | _Byte-Array_ | Data (byte-array) to be deserialized using proto-descriptor object | + + | Key | Type | Description | + | ------------------ | ------------ | ------------------------------------------------------------------ | + | `client` | _Object_ | Instantiated Clojure client object | + | `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required | + | `data` | _Byte-Array_ | Data (byte-array) to be deserialized using proto-descriptor object | ### Response structure - | Value | Type | Description | - |-------------------------------------------------|---------------------|-----------------------------------------------------------------------------| - | **deserialized-message** | _PersistentArrayMap_| Deserialized message (Clojure Map) | + + | Value | Type | Description | + | ------------------------ | -------------------- | ---------------------------------- | + | **deserialized-message** | _PersistentArrayMap_ | Deserialized message (Clojure Map) | Example: + ```clojure (let [client (create-client sample-client-config) proto-package "io.odpf.stencil_clj_test" @@ -181,18 +196,21 @@ Serialize will throw error in following cases Returns protobuf encoded byte array for the given Clojure and protobuf class name. ### Argument list : - | Key | Type | Description | - | ------------------------------------------------|----------------------|-----------------------------------------------------------------------------| - | `client` | _Object_ | Instantiated Clojure client object | - | `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required | - | `map` | _PersistentArrayMap_ | Data (in the form of map) to be serialized using proto descriptor object | + + | Key | Type | Description | + | ------------------ | -------------------- | ------------------------------------------------------------------------ | + | `client` | _Object_ | Instantiated Clojure client object | + | `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required | + | `map` | _PersistentArrayMap_ | Data (in the form of map) to be serialized using proto descriptor object | ### Response structure - | Value | Type | Description | - |-------------------------------------------------|---------------------|------------------------------------------------------------------------------| - | **serialized-message** | _Byte-Array_ | Serialized message (byte-array) | + + | Value | Type | Description | + | ---------------------- | ------------ | ------------------------------- | + | **serialized-message** | _Byte-Array_ | Serialized message (byte-array) | Example: + ```clojure (let [client (create-client sample-client-config) proto-package "io.odpf.stencil_clj_test" @@ -201,13 +219,14 @@ Serialize will throw error in following cases proto-desc (get-descriptor client fully-qualified-proto-name)] (serialize client fully-qualified-proto-name {:field-one 1.25})) ``` + ## Development -- Ensure [leiningen](https://leiningen.org/) is installed. -- Run tests: ```lein clean && lein javac && lein test``` +- Ensure [leiningen](https://leiningen.org/) is installed. -- Run formatting: ```lein cljfmt fix``` +- Run tests: `lein clean && lein javac && lein test` +- Run formatting: `lein cljfmt fix` ## License diff --git a/clients/clojure/project.clj b/clients/clojure/project.clj index df797d4a..d82ca3cd 100644 --- a/clients/clojure/project.clj +++ b/clients/clojure/project.clj @@ -1,4 +1,4 @@ -(defproject io.odpf/stencil-clj "0.2.2" +(defproject io.odpf/stencil-clj "0.3.0" :description "Stencil client for clojure" :url "https://github.com/odpf/stencil" :license {:name "Apache 2.0" diff --git a/clients/java/README.md b/clients/java/README.md index 7c02cf07..91c9daf0 100644 --- a/clients/java/README.md +++ b/clients/java/README.md @@ -16,7 +16,7 @@ Protobuf allows you to define a protobuf file using DescriptorSet. A FileDescrip #### Gradle ```groovy - implementation group: 'io.odpf', name: 'stencil', version: '0.2.2' + implementation group: 'io.odpf', name: 'stencil', version: '0.3.0' ``` #### Maven diff --git a/clients/java/build.gradle b/clients/java/build.gradle index baa2fdd5..480fda59 100644 --- a/clients/java/build.gradle +++ b/clients/java/build.gradle @@ -10,7 +10,7 @@ plugins { } group 'io.odpf' -version '0.2.2' +version '0.3.0' repositories { mavenLocal() diff --git a/clients/js/package.json b/clients/js/package.json index df28677a..35175704 100644 --- a/clients/js/package.json +++ b/clients/js/package.json @@ -1,6 +1,6 @@ { "name": "@odpf/stencil", - "version": "0.2.2", + "version": "0.3.0", "description": "Stencil js client package provides a store to lookup protobuf descriptors and options to keep the protobuf descriptors upto date.", "main": "main.js", "scripts": { diff --git a/docs/docs/clients/clojure.md b/docs/docs/clients/clojure.md index e42ad59e..4ee8efd5 100644 --- a/docs/docs/clients/clojure.md +++ b/docs/docs/clients/clojure.md @@ -5,13 +5,15 @@ A Clojure library designed to easily encode and decode protobuf messages by usin ## Installation Add the below dependency to your `project.clj` file: + ```clj - [io.odpf/stencil-clj "0.2.2"] +[io.odpf/stencil-clj "0.3.0"] ``` ## Usage Consider following proto message + ```proto syntax = "proto3"; @@ -39,6 +41,7 @@ message Person { int32 age = 5; } ``` + 1. Create stencil client. You can refer to [java client](java) documentation for all available options. ```clojure @@ -52,6 +55,7 @@ message Person { ``` 2. To serialize data from clojure map + ```clojure (:require [stencil.core :refer [serialize]]) @@ -64,6 +68,7 @@ message Person { ``` 3. Deserialize data from bytes to clojure map + ```clojure (:require [stencil.core :refer [deserialize]]) @@ -78,40 +83,44 @@ message Person { ## Protocol buffers - Clojure interop -| Protobuf | Clojure | Notes | -| ----------- | --------------------------- | ---------------- | -| field names | keywords in kebab case | `name` -> `:name`, `field_name` -> `:field-name` | -| scalar fields | Values follow [protobuf-java scalar value mappings](https://developers.google.com/protocol-buffers/docs/proto3#scalar) | | -| enums | Values converted as keywords of enum's original value | `UNKNOWN` -> `:UNKNOWN` | -| messages | clojure map | ```message Hello {string name = 1;}``` -> {:name "odpf"} | -| repeated fields | clojure vector | | -| one-of fields | treated as regular fields | if two fields are set that are part of one-of, last seen value is considered while serializing data | -| map | map values follow it's [wire representation](https://developers.google.com/protocol-buffers/docs/proto3#backwards_compatibility) | for `map` type, example value will be `[{:key "key" :value "value"}]` | +| Protobuf | Clojure | Notes | +| --------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| field names | keywords in kebab case | `name` -> `:name`, `field_name` -> `:field-name` | +| scalar fields | Values follow [protobuf-java scalar value mappings](https://developers.google.com/protocol-buffers/docs/proto3#scalar) | | +| enums | Values converted as keywords of enum's original value | `UNKNOWN` -> `:UNKNOWN` | +| messages | clojure map | `message Hello {string name = 1;}` -> {:name "odpf"} | +| repeated fields | clojure vector | | +| one-of fields | treated as regular fields | if two fields are set that are part of one-of, last seen value is considered while serializing data | +| map | map values follow it's [wire representation](https://developers.google.com/protocol-buffers/docs/proto3#backwards_compatibility) | for `map` type, example value will be `[{:key "key" :value "value"}]` | **Note on errors:** Serialize will throw error in following cases + 1. unknown field is passed that's not present in schema `{:cause :unknown-field :info {:field-name }}` 2. if non-collection type is passed to repeated field `{:cause :not-a-collection :info {:value }}` 3. If unknown enum value passed that's not present in schema `{:cause :unknown-enum-value :info {:field-name }}` ## API + - `create-client (client-config)` Returns a new Stencil Clojure client instance by passing client-config. ### Client config structure : - | Key | Type | Description | - | -----------------------|-----------|---------------------------------------------------------------------------------------------| - | `url` | _String_ | Stencil url to fetch latest descriptor sets | - | `refresh-cache` | _Boolean_ | Whether the cache should be refreshed or not | - | `refresh-ttl` | _Integer_ | Cache TTL in minutes | - | `request-timeout` | _Integer_ | Request timeout in milliseconds | - | `request-backoff-time` | _Integer_ | Request back off time in minutes | - | `retry-count` | _Integer_ | Number of retries to be made to fetch descriptor sets | - | `headers` | _Map_ | Map with key as header key and value as header value, which will be passed to stencil server| - | `refresh-strategy` | _keyword_ | Possible values :version-based-refresh, :long-polling-refresh. Default :long-polling-refresh| + + | Key | Type | Description | + | ---------------------- | --------- | -------------------------------------------------------------------------------------------- | + | `url` | _String_ | Stencil url to fetch latest descriptor sets | + | `refresh-cache` | _Boolean_ | Whether the cache should be refreshed or not | + | `refresh-ttl` | _Integer_ | Cache TTL in minutes | + | `request-timeout` | _Integer_ | Request timeout in milliseconds | + | `request-backoff-time` | _Integer_ | Request back off time in minutes | + | `retry-count` | _Integer_ | Number of retries to be made to fetch descriptor sets | + | `headers` | _Map_ | Map with key as header key and value as header value, which will be passed to stencil server | + | `refresh-strategy` | _keyword_ | Possible values :version-based-refresh, :long-polling-refresh. Default :long-polling-refresh | Example: + ```clojure (let [sample-client-config {:url "https://example-url" :refresh-cache true @@ -130,17 +139,20 @@ Serialize will throw error in following cases Returns protobuf descriptor object for the given protobuf class name. ### Argument list : - | Key | Type | Description | - | ------------------------------------------------|-------------------|-----------------------------------------------------------------------------| - | `client` | _Object_ | Instantiated Clojure client object | - | `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required | + + | Key | Type | Description | + | ------------------ | -------- | ----------------------------------------------------------------- | + | `client` | _Object_ | Instantiated Clojure client object | + | `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required | ### Response structure - | Value | Type | Description | - |-------------------------------------------------|-------------------|-----------------------------------------------------------------------------| - | **proto-desc** | _Object_ | Protobuf descriptor for given proto class name | + + | Value | Type | Description | + | -------------- | -------- | ---------------------------------------------- | + | **proto-desc** | _Object_ | Protobuf descriptor for given proto class name | Example: + ```clojure (let [client (create-client sample-client-config) proto-package "io.odpf.stencil_clj_test" @@ -154,18 +166,21 @@ Serialize will throw error in following cases Returns Clojure map for the given protobuf encoded byte array and protobuf class name. ### Argument list : - | Key | Type | Description | - | ------------------------------------------------|---------------------|-----------------------------------------------------------------------------| - | `client` | _Object_ | Instantiated Clojure client object | - | `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required | - | `data` | _Byte-Array_ | Data (byte-array) to be deserialized using proto-descriptor object | + + | Key | Type | Description | + | ------------------ | ------------ | ------------------------------------------------------------------ | + | `client` | _Object_ | Instantiated Clojure client object | + | `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required | + | `data` | _Byte-Array_ | Data (byte-array) to be deserialized using proto-descriptor object | ### Response structure - | Value | Type | Description | - |-------------------------------------------------|---------------------|-----------------------------------------------------------------------------| - | **deserialized-message** | _PersistentArrayMap_| Deserialized message (Clojure Map) | + + | Value | Type | Description | + | ------------------------ | -------------------- | ---------------------------------- | + | **deserialized-message** | _PersistentArrayMap_ | Deserialized message (Clojure Map) | Example: + ```clojure (let [client (create-client sample-client-config) proto-package "io.odpf.stencil_clj_test" @@ -181,18 +196,21 @@ Serialize will throw error in following cases Returns protobuf encoded byte array for the given Clojure and protobuf class name. ### Argument list : - | Key | Type | Description | - | ------------------------------------------------|----------------------|-----------------------------------------------------------------------------| - | `client` | _Object_ | Instantiated Clojure client object | - | `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required | - | `map` | _PersistentArrayMap_ | Data (in the form of map) to be serialized using proto descriptor object | + + | Key | Type | Description | + | ------------------ | -------------------- | ------------------------------------------------------------------------ | + | `client` | _Object_ | Instantiated Clojure client object | + | `proto-class-name` | _String_ | Name of the proto class whose proto descriptor object is required | + | `map` | _PersistentArrayMap_ | Data (in the form of map) to be serialized using proto descriptor object | ### Response structure - | Value | Type | Description | - |-------------------------------------------------|---------------------|------------------------------------------------------------------------------| - | **serialized-message** | _Byte-Array_ | Serialized message (byte-array) | + + | Value | Type | Description | + | ---------------------- | ------------ | ------------------------------- | + | **serialized-message** | _Byte-Array_ | Serialized message (byte-array) | Example: + ```clojure (let [client (create-client sample-client-config) proto-package "io.odpf.stencil_clj_test" @@ -201,9 +219,11 @@ Serialize will throw error in following cases proto-desc (get-descriptor client fully-qualified-proto-name)] (serialize client fully-qualified-proto-name {:field-one 1.25})) ``` + ## Development + - Ensure [leiningen](https://leiningen.org/) is installed. -- Run tests: ```lein clean && lein javac && lein test``` +- Run tests: `lein clean && lein javac && lein test` -- Run formatting: ```lein cljfmt fix``` +- Run formatting: `lein cljfmt fix` diff --git a/docs/docs/clients/java.md b/docs/docs/clients/java.md index 4bf3d1d1..fcbba41b 100644 --- a/docs/docs/clients/java.md +++ b/docs/docs/clients/java.md @@ -16,7 +16,7 @@ Protobuf allows you to define a protobuf file using DescriptorSet. A FileDescrip #### Gradle ```groovy - implementation group: 'io.odpf', name: 'stencil', version: '0.2.2' + implementation group: 'io.odpf', name: 'stencil', version: '0.3.0' ``` #### Maven @@ -25,7 +25,7 @@ Protobuf allows you to define a protobuf file using DescriptorSet. A FileDescrip io.odpf stencil - 0.2.2 + 0.3.0 ``` diff --git a/docs/docs/installation.md b/docs/docs/installation.md index cbead33d..5a9cbef7 100644 --- a/docs/docs/installation.md +++ b/docs/docs/installation.md @@ -56,7 +56,7 @@ docker pull odpf/stencil:latest To pull a specific version: ``` -docker pull odpf/stencil:v0.2.2 +docker pull odpf/stencil:v0.3.0 ``` ### Building from source diff --git a/docs/docs/reference/api.md b/docs/docs/reference/api.md index 2cf3df40..44c10e4f 100644 --- a/docs/docs/reference/api.md +++ b/docs/docs/reference/api.md @@ -1,41 +1,45 @@ # API -## Version: 0.2.2 + +## Version: 0.3.0 ### /v1beta1/namespaces #### GET + ##### Summary List names of namespaces ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful response. | [v1beta1ListNamespacesResponse](#v1beta1listnamespacesresponse) | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ----------------------------- | --------------------------------------------------------------- | +| 200 | A successful response. | [v1beta1ListNamespacesResponse](#v1beta1listnamespacesresponse) | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | #### POST + ##### Summary Create namespace entry ##### Parameters -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| body | body | | Yes | [v1beta1CreateNamespaceRequest](#v1beta1createnamespacerequest) | +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | --------------------------------------------------------------- | +| body | body | | Yes | [v1beta1CreateNamespaceRequest](#v1beta1createnamespacerequest) | ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful response. | [v1beta1CreateNamespaceResponse](#v1beta1createnamespaceresponse) | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ----------------------------- | ----------------------------------------------------------------- | +| 200 | A successful response. | [v1beta1CreateNamespaceResponse](#v1beta1createnamespaceresponse) | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | ### /v1beta1/namespaces/{id} #### GET + ##### Summary Get namespace by id @@ -43,17 +47,18 @@ Get namespace by id ##### Parameters | Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| id | path | | Yes | string | +| ---- | ---------- | ----------- | -------- | ------ | +| id | path | | Yes | string | ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful response. | [v1beta1GetNamespaceResponse](#v1beta1getnamespaceresponse) | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ----------------------------- | ----------------------------------------------------------- | +| 200 | A successful response. | [v1beta1GetNamespaceResponse](#v1beta1getnamespaceresponse) | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | #### DELETE + ##### Summary Delete namespace by id @@ -65,17 +70,18 @@ Ensure all schemas under this namespace is deleted, otherwise it will throw erro ##### Parameters | Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| id | path | | Yes | string | +| ---- | ---------- | ----------- | -------- | ------ | +| id | path | | Yes | string | ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful response. | [v1beta1DeleteNamespaceResponse](#v1beta1deletenamespaceresponse) | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ----------------------------- | ----------------------------------------------------------------- | +| 200 | A successful response. | [v1beta1DeleteNamespaceResponse](#v1beta1deletenamespaceresponse) | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | #### PUT + ##### Summary Update namespace entity by id @@ -83,20 +89,21 @@ Update namespace entity by id ##### Parameters | Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| id | path | | Yes | string | -| body | body | | Yes | object | +| ---- | ---------- | ----------- | -------- | ------ | +| id | path | | Yes | string | +| body | body | | Yes | object | ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful response. | [v1beta1UpdateNamespaceResponse](#v1beta1updatenamespaceresponse) | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ----------------------------- | ----------------------------------------------------------------- | +| 200 | A successful response. | [v1beta1UpdateNamespaceResponse](#v1beta1updatenamespaceresponse) | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | ### /v1beta1/namespaces/{id}/schemas #### GET + ##### Summary List schemas under the namespace @@ -104,19 +111,20 @@ List schemas under the namespace ##### Parameters | Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| id | path | | Yes | string | +| ---- | ---------- | ----------- | -------- | ------ | +| id | path | | Yes | string | ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful response. | [v1beta1ListSchemasResponse](#v1beta1listschemasresponse) | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ----------------------------- | --------------------------------------------------------- | +| 200 | A successful response. | [v1beta1ListSchemasResponse](#v1beta1listschemasresponse) | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | ### /v1beta1/namespaces/{namespaceId}/schemas/{schemaId} #### GET + ##### Summary Get latest schema @@ -127,80 +135,84 @@ Returns latest schema in it's own data type. For protobuf response type would be ##### Parameters -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| namespaceId | path | | Yes | string | -| schemaId | path | | Yes | string | +| Name | Located in | Description | Required | Schema | +| ----------- | ---------- | ----------- | -------- | ------ | +| namespaceId | path | | Yes | string | +| schemaId | path | | Yes | string | ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful schema response. Based on schema format, response will return different content types. For avro and json schemas response type is `application/json`. For protobuf response type is `application/octet-stream`. | | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | +| 200 | A successful schema response. Based on schema format, response will return different content types. For avro and json schemas response type is `application/json`. For protobuf response type is `application/octet-stream`. | | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | #### POST + ##### Summary Create schema under the namespace ##### Parameters -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| namespaceId | path | | Yes | string | -| schemaId | path | | Yes | string | -| body | body | Request payload should be equivalent to `curl` `--data-binary` option | Yes | binary | +| Name | Located in | Description | Required | Schema | +| ----------- | ---------- | --------------------------------------------------------------------- | -------- | ------ | +| namespaceId | path | | Yes | string | +| schemaId | path | | Yes | string | +| body | body | Request payload should be equivalent to `curl` `--data-binary` option | Yes | binary | ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful response. | [v1beta1CreateSchemaResponse](#v1beta1createschemaresponse) | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ----------------------------- | ----------------------------------------------------------- | +| 200 | A successful response. | [v1beta1CreateSchemaResponse](#v1beta1createschemaresponse) | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | #### DELETE + ##### Summary Delete specified schema ##### Parameters -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| namespaceId | path | | Yes | string | -| schemaId | path | | Yes | string | +| Name | Located in | Description | Required | Schema | +| ----------- | ---------- | ----------- | -------- | ------ | +| namespaceId | path | | Yes | string | +| schemaId | path | | Yes | string | ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful response. | [v1beta1DeleteSchemaResponse](#v1beta1deleteschemaresponse) | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ----------------------------- | ----------------------------------------------------------- | +| 200 | A successful response. | [v1beta1DeleteSchemaResponse](#v1beta1deleteschemaresponse) | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | #### PATCH + ##### Summary Update only schema metadata ##### Parameters -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| namespaceId | path | | Yes | string | -| schemaId | path | | Yes | string | -| body | body | | Yes | object | +| Name | Located in | Description | Required | Schema | +| ----------- | ---------- | ----------- | -------- | ------ | +| namespaceId | path | | Yes | string | +| schemaId | path | | Yes | string | +| body | body | | Yes | object | ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful response. | [v1beta1UpdateSchemaMetadataResponse](#v1beta1updateschemametadataresponse) | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ----------------------------- | --------------------------------------------------------------------------- | +| 200 | A successful response. | [v1beta1UpdateSchemaMetadataResponse](#v1beta1updateschemametadataresponse) | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | ### /v1beta1/namespaces/{namespaceId}/schemas/{schemaId}/check #### POST + ##### Summary Check schema compatibility @@ -211,273 +223,277 @@ Checks comptibility with existing latest schema ##### Parameters -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| namespaceId | path | | Yes | string | -| schemaId | path | | Yes | string | -| body | body | | Yes | binary | -| X-Compatibility | header | | No | string | +| Name | Located in | Description | Required | Schema | +| --------------- | ---------- | ----------- | -------- | ------ | +| namespaceId | path | | Yes | string | +| schemaId | path | | Yes | string | +| body | body | | Yes | binary | +| X-Compatibility | header | | No | string | ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful response. | [v1beta1CreateSchemaResponse](#v1beta1createschemaresponse) | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ----------------------------- | ----------------------------------------------------------- | +| 200 | A successful response. | [v1beta1CreateSchemaResponse](#v1beta1createschemaresponse) | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | ### /v1beta1/namespaces/{namespaceId}/schemas/{schemaId}/meta #### GET + ##### Summary Create schema under the namespace. Returns version number, unique ID and location ##### Parameters -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| namespaceId | path | | Yes | string | -| schemaId | path | | Yes | string | +| Name | Located in | Description | Required | Schema | +| ----------- | ---------- | ----------- | -------- | ------ | +| namespaceId | path | | Yes | string | +| schemaId | path | | Yes | string | ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful response. | [v1beta1GetSchemaMetadataResponse](#v1beta1getschemametadataresponse) | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ----------------------------- | --------------------------------------------------------------------- | +| 200 | A successful response. | [v1beta1GetSchemaMetadataResponse](#v1beta1getschemametadataresponse) | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | ### /v1beta1/namespaces/{namespaceId}/schemas/{schemaId}/versions #### GET + ##### Summary List all version numbers for schema ##### Parameters -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| namespaceId | path | | Yes | string | -| schemaId | path | | Yes | string | +| Name | Located in | Description | Required | Schema | +| ----------- | ---------- | ----------- | -------- | ------ | +| namespaceId | path | | Yes | string | +| schemaId | path | | Yes | string | ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful response. | [v1beta1ListVersionsResponse](#v1beta1listversionsresponse) | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ----------------------------- | ----------------------------------------------------------- | +| 200 | A successful response. | [v1beta1ListVersionsResponse](#v1beta1listversionsresponse) | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | ### /v1beta1/namespaces/{namespaceId}/schemas/{schemaId}/versions/{versionId} #### DELETE + ##### Summary Delete specified version of the schema ##### Parameters -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| namespaceId | path | | Yes | string | -| schemaId | path | | Yes | string | -| versionId | path | | Yes | integer | +| Name | Located in | Description | Required | Schema | +| ----------- | ---------- | ----------- | -------- | ------- | +| namespaceId | path | | Yes | string | +| schemaId | path | | Yes | string | +| versionId | path | | Yes | integer | ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful response. | [v1beta1DeleteVersionResponse](#v1beta1deleteversionresponse) | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ----------------------------- | ------------------------------------------------------------- | +| 200 | A successful response. | [v1beta1DeleteVersionResponse](#v1beta1deleteversionresponse) | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | ### /v1beta1/search #### GET + ##### Summary Global Search API ##### Parameters -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| namespaceId | query | | No | string | -| schemaId | query | | No | string | -| query | query | | Yes | string | -| history | query | | No | boolean | -| versionId | query | | No | integer | +| Name | Located in | Description | Required | Schema | +| ----------- | ---------- | ----------- | -------- | ------- | +| namespaceId | query | | No | string | +| schemaId | query | | No | string | +| query | query | | Yes | string | +| history | query | | No | boolean | +| versionId | query | | No | integer | ##### Responses -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | A successful response. | [v1beta1SearchResponse](#v1beta1searchresponse) | -| default | An unexpected error response. | [rpcStatus](#rpcstatus) | +| Code | Description | Schema | +| ------- | ----------------------------- | ----------------------------------------------- | +| 200 | A successful response. | [v1beta1SearchResponse](#v1beta1searchresponse) | +| default | An unexpected error response. | [rpcStatus](#rpcstatus) | ### Models #### SchemaCompatibility -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| SchemaCompatibility | string | | | +| Name | Type | Description | Required | +| ------------------- | ------ | ----------- | -------- | +| SchemaCompatibility | string | | | #### SchemaFormat -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| SchemaFormat | string | | | +| Name | Type | Description | Required | +| ------------ | ------ | ----------- | -------- | +| SchemaFormat | string | | | #### protobufAny -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| typeUrl | string | | No | -| value | byte | | No | +| Name | Type | Description | Required | +| ------- | ------ | ----------- | -------- | +| typeUrl | string | | No | +| value | byte | | No | #### rpcStatus -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| code | integer | | No | -| message | string | | No | -| details | [ [protobufAny](#protobufany) ] | | No | +| Name | Type | Description | Required | +| ------- | ------------------------------- | ----------- | -------- | +| code | integer | | No | +| message | string | | No | +| details | [ [protobufAny](#protobufany) ] | | No | #### v1beta1CheckCompatibilityResponse -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| v1beta1CheckCompatibilityResponse | object | | | +| Name | Type | Description | Required | +| --------------------------------- | ------ | ----------- | -------- | +| v1beta1CheckCompatibilityResponse | object | | | #### v1beta1CreateNamespaceRequest -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| id | string | | Yes | -| format | [SchemaFormat](#schemaformat) | | No | -| compatibility | [SchemaCompatibility](#schemacompatibility) | | No | -| description | string | | No | +| Name | Type | Description | Required | +| ------------- | ------------------------------------------- | ----------- | -------- | +| id | string | | Yes | +| format | [SchemaFormat](#schemaformat) | | No | +| compatibility | [SchemaCompatibility](#schemacompatibility) | | No | +| description | string | | No | #### v1beta1CreateNamespaceResponse -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| namespace | [v1beta1Namespace](#v1beta1namespace) | | No | +| Name | Type | Description | Required | +| --------- | ------------------------------------- | ----------- | -------- | +| namespace | [v1beta1Namespace](#v1beta1namespace) | | No | #### v1beta1CreateSchemaResponse -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| version | integer | | No | -| id | string | | No | -| location | string | | No | +| Name | Type | Description | Required | +| -------- | ------- | ----------- | -------- | +| version | integer | | No | +| id | string | | No | +| location | string | | No | #### v1beta1DeleteNamespaceResponse -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| message | string | | No | +| Name | Type | Description | Required | +| ------- | ------ | ----------- | -------- | +| message | string | | No | #### v1beta1DeleteSchemaResponse -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| message | string | | No | +| Name | Type | Description | Required | +| ------- | ------ | ----------- | -------- | +| message | string | | No | #### v1beta1DeleteVersionResponse -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| message | string | | No | +| Name | Type | Description | Required | +| ------- | ------ | ----------- | -------- | +| message | string | | No | #### v1beta1GetLatestSchemaResponse | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | -| data | byte | | No | +| data | byte | | No | #### v1beta1GetNamespaceResponse -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| namespace | [v1beta1Namespace](#v1beta1namespace) | | No | +| Name | Type | Description | Required | +| --------- | ------------------------------------- | ----------- | -------- | +| namespace | [v1beta1Namespace](#v1beta1namespace) | | No | #### v1beta1GetSchemaMetadataResponse -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| format | [SchemaFormat](#schemaformat) | | No | -| compatibility | [SchemaCompatibility](#schemacompatibility) | | No | -| authority | string | | No | +| Name | Type | Description | Required | +| ------------- | ------------------------------------------- | ----------- | -------- | +| format | [SchemaFormat](#schemaformat) | | No | +| compatibility | [SchemaCompatibility](#schemacompatibility) | | No | +| authority | string | | No | #### v1beta1GetSchemaResponse | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | -| data | byte | | No | +| data | byte | | No | #### v1beta1ListNamespacesResponse -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| namespaces | [ string ] | | No | +| Name | Type | Description | Required | +| ---------- | ---------- | ----------- | -------- | +| namespaces | [ string ] | | No | #### v1beta1ListSchemasResponse -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| schemas | [ string ] | | No | +| Name | Type | Description | Required | +| ------- | ---------- | ----------- | -------- | +| schemas | [ string ] | | No | #### v1beta1ListVersionsResponse -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| versions | [ integer ] | | No | +| Name | Type | Description | Required | +| -------- | ----------- | ----------- | -------- | +| versions | [ integer ] | | No | #### v1beta1Namespace -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| id | string | | No | -| format | [SchemaFormat](#schemaformat) | | No | -| Compatibility | [SchemaCompatibility](#schemacompatibility) | | No | -| description | string | | No | -| createdAt | dateTime | | No | -| updatedAt | dateTime | | No | +| Name | Type | Description | Required | +| ------------- | ------------------------------------------- | ----------- | -------- | +| id | string | | No | +| format | [SchemaFormat](#schemaformat) | | No | +| Compatibility | [SchemaCompatibility](#schemacompatibility) | | No | +| description | string | | No | +| createdAt | dateTime | | No | +| updatedAt | dateTime | | No | #### v1beta1SearchHits -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| namespaceId | string | | No | -| schemaId | string | | No | -| versionId | integer | | No | -| fields | [ string ] | | No | -| types | [ string ] | | No | -| path | string | | No | +| Name | Type | Description | Required | +| ----------- | ---------- | ----------- | -------- | +| namespaceId | string | | No | +| schemaId | string | | No | +| versionId | integer | | No | +| fields | [ string ] | | No | +| types | [ string ] | | No | +| path | string | | No | #### v1beta1SearchMeta -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| total | long | | No | +| Name | Type | Description | Required | +| ----- | ---- | ----------- | -------- | +| total | long | | No | #### v1beta1SearchResponse -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| hits | [ [v1beta1SearchHits](#v1beta1searchhits) ] | | No | -| meta | [v1beta1SearchMeta](#v1beta1searchmeta) | | No | +| Name | Type | Description | Required | +| ---- | ------------------------------------------- | ----------- | -------- | +| hits | [ [v1beta1SearchHits](#v1beta1searchhits) ] | | No | +| meta | [v1beta1SearchMeta](#v1beta1searchmeta) | | No | #### v1beta1UpdateNamespaceResponse -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| namespace | [v1beta1Namespace](#v1beta1namespace) | | No | +| Name | Type | Description | Required | +| --------- | ------------------------------------- | ----------- | -------- | +| namespace | [v1beta1Namespace](#v1beta1namespace) | | No | #### v1beta1UpdateSchemaMetadataResponse -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| format | [SchemaFormat](#schemaformat) | | No | -| compatibility | [SchemaCompatibility](#schemacompatibility) | | No | -| authority | string | | No | +| Name | Type | Description | Required | +| ------------- | ------------------------------------------- | ----------- | -------- | +| format | [SchemaFormat](#schemaformat) | | No | +| compatibility | [SchemaCompatibility](#schemacompatibility) | | No | +| authority | string | | No |