From 31d34942d38484b958a9e674347cd348a76dfe2e Mon Sep 17 00:00:00 2001 From: Dmitry Balashov <43530070+0x009922@users.noreply.github.com> Date: Thu, 23 Nov 2023 13:42:03 +0700 Subject: [PATCH 1/3] [docs]: update configuration endpoints Signed-off-by: Dmitry Balashov <43530070+0x009922@users.noreply.github.com> --- src/reference/torii-endpoints.md | 125 ++++++++++++------------------- 1 file changed, 47 insertions(+), 78 deletions(-) diff --git a/src/reference/torii-endpoints.md b/src/reference/torii-endpoints.md index a9918004a..0c93281c5 100644 --- a/src/reference/torii-endpoints.md +++ b/src/reference/torii-endpoints.md @@ -31,6 +31,47 @@ Via this endpoint, the client first provides the starting block number (i.e. hei sending the confirmation message, the server starts streaming all the blocks from the given block number up to the current block and continues to stream blocks as they are added to the blockchain. +## Configuration > Retrieve + +- **Protocol:** HTTP +- **Method:** `GET` +- **Endpoint:** `/configuration` +- **Responses:** with JSON-serialized subset of configuration parameters. The subset of returned parameters is equal to + the one accepted by [Configuration > Update endpoint](#configuration-update), i.e. it contains only + `logger.max_log_level` parameter as of now. + +Example response: + +```json +{ + "logger": { + "max_log_level": "TRACE" + } +} +``` + +## Configuration > Update + +- **Protocol:** HTTP +- **Method:** `POST` +- **Endpoint:** `/configuration` +- **Expects:** a JSON-serialized subset of configuration parameters. + +This endpoint currently supports only dynamic updating of the `logger.max_log_level` parameter. + +For possible values please refer to the configuration reference (TODO: +[Tracking issue for configuration reference](https://github.com/hyperledger/iroha-2-docs/issues/392)). + +Example request: + +```json +{ + "logger": { + "max_log_level": "DEBUG" + } +} +``` + ## Events - **Protocol:** HTTP @@ -140,12 +181,13 @@ Learn [how to use metrics](/guide/advanced/metrics). results. - **`sort_by_metadata_key`:** An optional parameter in queries. Use to sort results containing metadata with a given key. - - **`fetch_size`:** An optional parameter in queries. Use to specify the exact number of results returned by a query. + - **`fetch_size`:** An optional parameter in queries. Use to specify the exact number of results returned by a + query. **Responses:** -| Response | Status | Body | -| ---------------- | ------ | ------------------------------------------------------------------------------------------ | +| Response | Status | Body | +| ---------------- | ------ | ------------------------------------------------------------------------------------------------ | | Success | 200 | [`VersionedBatchedResponse`](/reference/data-model-schema#versionedbatchedresponse-value) | | Conversion Error | 400 | [`QueryExecutionFail::Conversion(String)`](/reference/data-model-schema#queryexecutionfail) | | Evaluate Error | 400 | [`QueryExecutionFail::Evaluate(String)`](/reference/data-model-schema#queryexecutionfail) | @@ -158,7 +200,7 @@ Learn [how to use metrics](/guide/advanced/metrics). Whether each prerequisite object was found and [`FindError`](/reference/data-model-schema#finderror): | Domain | Account | [`FindError`](/reference/data-model-schema#finderror) | -| :----: | :-----: | ------------------------------------------------------------------- | +| :----: | :-----: | ------------------------------------------------------------------------- | | N | - | [`FindError::Domain(DomainId)`](/reference/data-model-schema#finderror) | | Y | N | [`FindError::Account(AccountId)`](/reference/data-model-schema#finderror) | @@ -167,7 +209,7 @@ Whether each prerequisite object was found and [`FindError`](/reference/data-mod Whether each prerequisite object was found and [`FindError`](/reference/data-model-schema#finderror): | Domain | Account | Asset Definition | Asset | [`FindError`](/reference/data-model-schema#finderror) | -| :----: | :-----: | :--------------: | :---: | ----------------------------------------------------------------------------------- | +| :----: | :-----: | :--------------: | :---: | ----------------------------------------------------------------------------------------- | | N | - | - | - | [`FindError::Domain(DomainId)`](/reference/data-model-schema#finderror) | | Y | N | - | - | [`FindError::Account(AccountId)`](/reference/data-model-schema#finderror) | | Y | - | N | - | [`FindError::AssetDefinition(AssetDefinitionId)`](/reference/data-model-schema#finderror) | @@ -209,7 +251,6 @@ struct Uptime { } ``` - ::: warning JSON Precision Lost Almost all fields in the `Status` structure are 64-bit integers, and they are encoded in JSON as-is. Since native JSON's @@ -299,75 +340,3 @@ returns the corresponding JSON value. [GitHub repository](https://github.com/paritytech/parity-scale-codec). - - From b2e09643be19bc14ed63558ec838a0b43ad0b419 Mon Sep 17 00:00:00 2001 From: Dmitry Balashov <43530070+0x009922@users.noreply.github.com> Date: Tue, 12 Dec 2023 12:28:26 +0700 Subject: [PATCH 2/3] [docs]: actualise configuration endpoints Signed-off-by: Dmitry Balashov <43530070+0x009922@users.noreply.github.com> --- src/reference/torii-endpoints.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/src/reference/torii-endpoints.md b/src/reference/torii-endpoints.md index 0c93281c5..f735e39b8 100644 --- a/src/reference/torii-endpoints.md +++ b/src/reference/torii-endpoints.md @@ -31,47 +31,56 @@ Via this endpoint, the client first provides the starting block number (i.e. hei sending the confirmation message, the server starts streaming all the blocks from the given block number up to the current block and continues to stream blocks as they are added to the blockchain. -## Configuration > Retrieve +## Configuration / Retrieve - **Protocol:** HTTP - **Method:** `GET` - **Endpoint:** `/configuration` - **Responses:** with JSON-serialized subset of configuration parameters. The subset of returned parameters is equal to the one accepted by [Configuration > Update endpoint](#configuration-update), i.e. it contains only - `logger.max_log_level` parameter as of now. + `logger.level` parameter as of now. -Example response: +**Example response:** ```json { "logger": { - "max_log_level": "TRACE" + "level": "TRACE" } } ``` -## Configuration > Update +## Configuration / Update - **Protocol:** HTTP - **Method:** `POST` - **Endpoint:** `/configuration` - **Expects:** a JSON-serialized subset of configuration parameters. +- **Response:** `202 ACCEPTED` -This endpoint currently supports only dynamic updating of the `logger.max_log_level` parameter. +This endpoint currently supports only dynamic updating of the `logger.level` parameter. For possible values please refer to the configuration reference (TODO: [Tracking issue for configuration reference](https://github.com/hyperledger/iroha-2-docs/issues/392)). -Example request: +**Example request:** ```json { "logger": { - "max_log_level": "DEBUG" + "level": "DEBUG" } } ``` +::: tip Guarantees + +It is not guaranteed that successful update of configuration means that the configuration is indeed updated. While +consecutive [configuration retrievals](#configuration-retrieve) will return updated values, the actual update is +performed asynchronously. + +::: + ## Events - **Protocol:** HTTP From 428650ceb58b368a1774fc1879762f5fdb935b6d Mon Sep 17 00:00:00 2001 From: 0x009922 <43530070+0x009922@users.noreply.github.com> Date: Tue, 12 Dec 2023 09:46:19 +0000 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: William Richter <88400283+WRRicht3r@users.noreply.github.com> Co-authored-by: Ekaterina Mekhnetsova Signed-off-by: 0x009922 <43530070+0x009922@users.noreply.github.com> --- src/reference/torii-endpoints.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/reference/torii-endpoints.md b/src/reference/torii-endpoints.md index f735e39b8..8d9cd7e94 100644 --- a/src/reference/torii-endpoints.md +++ b/src/reference/torii-endpoints.md @@ -36,8 +36,8 @@ current block and continues to stream blocks as they are added to the blockchain - **Protocol:** HTTP - **Method:** `GET` - **Endpoint:** `/configuration` -- **Responses:** with JSON-serialized subset of configuration parameters. The subset of returned parameters is equal to - the one accepted by [Configuration > Update endpoint](#configuration-update), i.e. it contains only +- **Responses:** with a JSON-serialized subset of configuration parameters. The subset of returned parameters is equal to + the one accepted by the [Configuration > Update endpoint](#configuration-update), i.e. it only contains the `logger.level` parameter as of now. **Example response:** @@ -58,7 +58,7 @@ current block and continues to stream blocks as they are added to the blockchain - **Expects:** a JSON-serialized subset of configuration parameters. - **Response:** `202 ACCEPTED` -This endpoint currently supports only dynamic updating of the `logger.level` parameter. +This endpoint only supports dynamic updating of the `logger.level` parameter for now. For possible values please refer to the configuration reference (TODO: [Tracking issue for configuration reference](https://github.com/hyperledger/iroha-2-docs/issues/392)). @@ -75,7 +75,7 @@ For possible values please refer to the configuration reference (TODO: ::: tip Guarantees -It is not guaranteed that successful update of configuration means that the configuration is indeed updated. While +A successful configuration update does not guarantee that the configuration is indeed updated. While consecutive [configuration retrievals](#configuration-retrieve) will return updated values, the actual update is performed asynchronously. @@ -190,7 +190,7 @@ Learn [how to use metrics](/guide/advanced/metrics). results. - **`sort_by_metadata_key`:** An optional parameter in queries. Use to sort results containing metadata with a given key. - - **`fetch_size`:** An optional parameter in queries. Use to specify the exact number of results returned by a + - **`fetch_size`:** An optional parameter in queries. Use it to specify the exact number of results returned by a query. **Responses:**