From b29592ed134bc61fb563dabae8b1f54e4b8d31ea Mon Sep 17 00:00:00 2001 From: yamkovoy Date: Fri, 19 Jan 2024 03:21:37 +0300 Subject: [PATCH 1/5] Updated and polished Torii Endpoints; fixed and/or removed dead links in related topics Signed-off-by: yamkovoy --- src/guide/advanced/metrics.md | 48 +- .../advanced/running-iroha-on-bare-metal.md | 4 +- src/guide/configure/configuration-types.md | 8 +- src/guide/configure/peer-configuration.md | 18 +- src/guide/configure/sample-configuration.md | 10 +- src/reference/torii-endpoints.md | 463 +++++++++++++----- 6 files changed, 378 insertions(+), 173 deletions(-) diff --git a/src/guide/advanced/metrics.md b/src/guide/advanced/metrics.md index 7a47420e8..14dcfd09c 100644 --- a/src/guide/advanced/metrics.md +++ b/src/guide/advanced/metrics.md @@ -1,29 +1,42 @@ # Metrics -To conveniently and thoroughly monitor the performance of the network, we -recommend using [`prometheus`](https://prometheus.io/). Prometheus is a -program that can monitor your Iroha peer over a separate socket and provide -different kinds of performance metrics. +To conveniently and thoroughly monitor the performance of your instance of the Iroha network, we recommend using [`Prometheus`](https://prometheus.io/). Prometheus is a program that can monitor your Iroha peer over a separate socket and provide different kinds of performance metrics. -This data can help you find performance bottlenecks and optimise your Iroha -configuration. +This data can help you find performance bottlenecks and optimise your Iroha configuration. + +#### `/metrics` Endpoint + +See [Reference > Torii Endpoints: Metrics](../../reference/torii-endpoints.md#metrics). ## How to use metrics -To use metrics, you need to configure the `/metrics` endpoint in the -[Iroha configuration](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/config.md). -By default, the endpoint is exposed at `127.0.0.1:8180/metrics`. If the -port is not available, Iroha will still start and work normally, but -metrics won't be accessible. +To collect metrics via the `/metrics` endpoint, the following must first be configured: + +- In the [`configs/peer/config.json`](https://github.com/hyperledger/iroha/blob/iroha2-dev/configs/peer/config.json) configuration file: + - `"TORII"`: `"TELEMETRY_URL"` variable; + - `"TELEMETRY"` object in its entirety.\ + > For details, see [Peer Configuration](../configure/peer-configuration.md). + +- In the [`configs/client/config.json`](https://github.com/hyperledger/iroha/blob/iroha2-dev/configs/client/config.json) configuration file: + - `"TORII_TELEMETRY_URL"` variable.\ + Set to `http://127.0.0.1:8180/`, by default. If the port is not available, Iroha will still function properly, but the metrics won't be provided. + > For details, see [Client Configuration](../configure/client-configuration.md) + +::: note -After that, use the IP address to access the data from the running Iroha -instance. For example: +For examples, see [Sample Configuration Files](../configure/sample-configuration.md). + +::: + +After the above is configured, you can use the IP address set in the `"TORII_TELEMETRY_URL"` variable to access the metrics data from within a running Iroha instance. + +**Example**: ```bash -$ curl http://127.0.0.1:8080/metrics +$ curl http://127.0.0.1:8180/metrics ``` -This will give you a result like this: +This returns a result similar to the following: ```bash # HELP blocks_height Total number of blocks in chain @@ -42,8 +55,3 @@ total_number_of_transactions 216499 # TYPE number_of_signatures_in_last_block gauge number_of_signatures_in_last_block 5 ``` - -## `/metrics` endpoint - -Refer to the -[API specification](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/api_spec.md#metrics). diff --git a/src/guide/advanced/running-iroha-on-bare-metal.md b/src/guide/advanced/running-iroha-on-bare-metal.md index 409f9d874..c6816a418 100644 --- a/src/guide/advanced/running-iroha-on-bare-metal.md +++ b/src/guide/advanced/running-iroha-on-bare-metal.md @@ -23,8 +23,8 @@ You can always check [peer configuration options](/guide/configure/peer-configuration.md) for more details. -The complete list of options is available in the -[Iroha Configuration Reference](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/config.md). + ::: diff --git a/src/guide/configure/configuration-types.md b/src/guide/configure/configuration-types.md index c10a61ddd..e5380e7fa 100644 --- a/src/guide/configure/configuration-types.md +++ b/src/guide/configure/configuration-types.md @@ -6,10 +6,10 @@ double `Option>`. In this section we explain the difference between `Option<..>` and `Option>` used for configuration types. You can find more about -available configuration options in -[peer configuration](peer-configuration.md). The full list of available -options is in -[Iroha Configuration Reference](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/config.md). +available configuration options in the [Peer Configuration](peer-configuration.md) topic. + + ## `Option<..>` diff --git a/src/guide/configure/peer-configuration.md b/src/guide/configure/peer-configuration.md index 565589746..cb5c730d3 100644 --- a/src/guide/configure/peer-configuration.md +++ b/src/guide/configure/peer-configuration.md @@ -29,8 +29,8 @@ following: - [Public and private keys for the genesis account](#genesis) (`ACCOUNT_PUBLIC_KEY` and `ACCOUNT_PRIVATE_KEY`) -For the full list of configuration options, refer to -[Iroha Configuration Reference](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/config.md). + ::: info @@ -88,10 +88,8 @@ trusted peers: `TORII` is the module in charge of handling incoming and outgoing connections. -Here we only cover the required configurations: `API_URL`, `P2P_ADDR`, and -`TELEMETRY_URL`. Check -[`TORII` configuration reference](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/config.md#torii) -for all available options. + ### `API_URL` @@ -153,8 +151,8 @@ configurations, such as: - `GENESIS_SUBMISSION_DELAY_MS`: the delay before the genesis block submission after the minimum number of peers were discovered. -You can find more details in -[`GENESIS` Iroha Configuration Reference](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/config.md#genesis). + ## Logger @@ -202,5 +200,5 @@ _warehouse_). The `BLOCK_STORE_PATH` specifies where the blocks are stored. You can change it to a custom location if for some reason the default location (`./storage`) is not available or desirable. -For more details, check -[`KURA` configuration reference](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/config.md#kura). + diff --git a/src/guide/configure/sample-configuration.md b/src/guide/configure/sample-configuration.md index 75e6c8b99..e8033adea 100644 --- a/src/guide/configure/sample-configuration.md +++ b/src/guide/configure/sample-configuration.md @@ -2,9 +2,12 @@ Here you can find sample configuration files for Iroha 2: -- Peer Configuration (`configs/peer/config.json`). Refer to [peer configuration](peer-configuration.md) for details. -- Genesis Block (`configs/peer/genesis.json`). Refer to [genesis block](genesis.md) for details. -- Client Configuration (`configs/client_cli/config.json`). Refer to [client configuration](client-configuration.md) for details. +- Peer Configuration [`configs/peer/config.json`](https://github.com/hyperledger/iroha/blob/iroha2-dev/configs/peer/config.json).\ + For details, see [Peer Configuration](peer-configuration.md). +- Genesis Block [`configs/peer/genesis.json`](https://github.com/hyperledger/iroha/blob/iroha2-dev/configs/peer/genesis.json).\ + For details, see [Genesis Block](genesis.md). +- Client Configuration [`configs/client/config.json`](https://github.com/hyperledger/iroha/blob/iroha2-dev/configs/client/config.json).\ + For details, see [Client Configuration](client-configuration.md). ::: code-group @@ -15,4 +18,3 @@ Here you can find sample configuration files for Iroha 2: <<< @/snippets/client-cli-config.json ::: - diff --git a/src/reference/torii-endpoints.md b/src/reference/torii-endpoints.md index 8d9cd7e94..8b7a7dd66 100644 --- a/src/reference/torii-endpoints.md +++ b/src/reference/torii-endpoints.md @@ -1,48 +1,131 @@ # Torii Endpoints - +::: tip Note + +Messages for certain `TORII` operations are encoded with Parity SCALE Codec commonly used with the [Parity Substrate](https://www.parity.io/technologies/substrate/) blockchain framework, and other blockchains utilizing it. + +For more information on Parity SCALE Codec, see the [Substrate Documentation: Type encoding (SCALE)](https://docs.substrate.io/reference/scale-codec/) article and its [official GitHub repository](https://github.com/paritytech/parity-scale-codec). + + + +::: + +`TORII` is the Iroha 2 module in charge of handling incoming and outgoing connections. It is used to receive, accept and route incoming instructions, and HTTP queries, as well as run-time configuration updates. + +To establish two-way communication with the `TORII` endpoints, the following addresses must be specified in the Iroha 2 configuration files: + +1. In the `configs/client_cli/config.json` client configuration file: + - `TORII_API_URL` — connects to the `TORII` module responsible for handling incoming and outgoing connections.\ + This address is the same as the `API_URL` address in the `configs/peer/config.json` peer configuration file. + - `TORII_TELEMETRY_URL` — connects to the [Prometheus](https://prometheus.io/) endpoint address that is used as a [metrics](../guide/advanced/metrics.md) tool to monitor the network performance. + + ::: info + + To learn more, see [Client Configuration > Iroha Public Addresses](../guide/configure/client-configuration.md#iroha-public-addresses). + + ::: + +2. In the `configs/peer/config.json` peer configuration file: + - `API_URL` — connects to the `TORII` module responsible for handling incoming and outgoing connections.\ + This address is the same as the `TORII_API_URL` address in the `configs/client_cli/config.json` client configuration file. + - `TELEMETRY_URL` — connects to the [Prometheus](https://prometheus.io/) endpoint address that is used as a [metrics](../guide/advanced/metrics.md) tool to monitor the network performance. + + ::: info + + To learn more, see [Peer Configuration > Iroha Public Addresses](../guide/configure/peer-configuration.html#iroha-public-addresses). + + ::: ## API Version -- **Protocol:** HTTP -- **Method:** `GET` -- **Endpoint:** `/api_version` +- **Protocol**: `HTTP` +- **Method**: `GET` +- **Encoding**: `JSON` +- **Endpoint**: `/api_version` + +#### Requests -**Responses:** +A `GET` request to the endpoint. -`200 OK`: The current version of API used by Iroha returned as a JSON string. Grabbed from the genesis block's version, -so at least a minimal subnet of 4 peers should be running and the genesis be submitted at the time of request. +#### Responses + +| Code | Response | Description | +| :--: | --------------------- | ----------------------------------------------------------------------------- | +| 200 | OK | Returns the current version of the API used by Iroha 2. | +| 401 | Unauthorized | The client lacks valid credentials for the request. | +| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | + +**Example**: ```json -"1" +200 OK: "1" ``` +::: info + +The API version is retrieved from and is the same as the version of the [genesis block](../guide/configure/genesis.md), which means that at least a minimal subnet of four peers must be running, and the genesis block must already be submitted at the time of the request. + +::: + ## Blocks Stream -- **Protocol:** HTTP -- **Protocol Upgrade:**`WebSocket -- **Endpoint:** `/block/stream` +- **Protocols**: `HTTP` upgraded to `WebSocket` +- **Encoding**: `SCALE` +- **Endpoint**: `/block/stream` + +#### Handshake + +Since the `/block/stream` endpoint handles continuous two-way data exchange, a `WebSocket` handshake between the client and server must first be performed to initiate communication with this endpoint. -The client should send a [`BlockSubscriptionRequest`](/reference/data-model-schema#blocksubscriptionrequest) to initiate -communication after the WebSocket handshake. Then the server sends a -[`BlockMessage`](/reference/data-model-schema#blockmessage). Messages are SCALE-encoded[^1]. +The first HTTP request to this endpoint requires a standard set of `WebSocket` headers. -Via this endpoint, the client first provides the starting block number (i.e. height) in the subscription request. After -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. +**Example**: + +```http +Host: example.com:8000 +Upgrade: websocket +Connection: Upgrade +Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw== +Sec-WebSocket-Version: 13 +Sec-WebSocket-Extensions: permessage-deflate, client_max_window_bits +``` + +#### Data Exchange + +After a successful handshake, the client must send a [`BlockSubscriptionRequest`](/reference/data-model-schema#blocksubscriptionrequest) request with the starting block number provided (i.e., the `height` value). Then, upon sending the confirmation and [`BlockMessage`](/reference/data-model-schema#blockmessage) messages, the server starts streaming all of the blocks, beginning with the block specified with `height` up to the most recent one, and then continues to stream new blocks as they are added to the blockchain. + +#### Responses + +| Code | Response | Description | +| :--: | --------------------- | ----------------------------------------------------------------------------- | +| 101 | Switching Protocols | The protocol is successfully switched from `HTTP` to `WebSocket`. | +| 400 | Bad Request | The server will not process the request due to an issue on the client side. | +| 401 | Unauthorized | The client lacks valid credentials for the request. | +| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | ## Configuration / Retrieve -- **Protocol:** HTTP -- **Method:** `GET` -- **Endpoint:** `/configuration` -- **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. +- **Protocol**: `HTTP` +- **Method**: `GET` +- **Encoding**: `JSON` +- **Endpoint**: `/configuration` + +#### Requests -**Example response:** +A `GET` request to the endpoint. + +#### Responses + +| Code | Response | Description | +| :--: | --------------------- | ----------------------------------------------------------------------------- | +| 200 | OK | Returns a subset of configuration parameters serialized into JSON format. | +| 401 | Unauthorized | The client lacks valid credentials for the request. | +| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | + +**Example**: ```json +200 OK: { "logger": { "level": "TRACE" @@ -50,20 +133,35 @@ current block and continues to stream blocks as they are added to the blockchain } ``` +::: info + +The subset of configuration parameters returned by this operation is equal to the one accepted by the [Configuration / Update](#configuration-update) operation, i.e., it only contains the `logger.level` parameter as of now. + +::: + ## Configuration / Update -- **Protocol:** HTTP -- **Method:** `POST` -- **Endpoint:** `/configuration` -- **Expects:** a JSON-serialized subset of configuration parameters. -- **Response:** `202 ACCEPTED` +- **Protocol**: `HTTP` +- **Method**: `POST` +- **Encoding**: `JSON` +- **Endpoint**: `/configuration` + +#### Requests -This endpoint only supports dynamic updating of the `logger.level` parameter for now. +This endpoint expects a subset of configuration parameters serialized into JSON format. Currently, it only supports 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)). +::: info -**Example request:** +The list of all accepted values is currently unavailable and will be a part of the configuration reference that is still WIP. + +Until then, to get assistance with the acceptable values and their definitions, consult [Receive Support](../guide/support.md) for ways to contact us. + +The progress on the configuration reference can be tracked in the following GitHub issue:\ +[iroha-2-docs > Issue #392: Tracking issue for Configuration Reference as per RFC](https://github.com/hyperledger/iroha-2-docs/issues/392). + +::: + +**Example**: ```json { @@ -73,59 +171,111 @@ For possible values please refer to the configuration reference (TODO: } ``` +#### Responses + +| Code | Response | Description | +| :--: | --------------------- | ------------------------------------------------------------------------------- | +| 202 | Accepted | The request to update the configuration is accepted and is due to be processed. | +| 401 | Unauthorized | The client lacks valid credentials for the request. | +| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | + ::: tip Guarantees -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. +A successful configuration update does not guarantee that the configuration is indeed updated. While a follow-up [Configuration / Retrieve](#configuration-retrieve) request will return updated values, the actual update is performed asynchronously. ::: ## Events -- **Protocol:** HTTP -- **Protocol Upgrade:** WebSocket -- **Endpoint:** `/events` - -After a handshake, the client should send an -[`EventSubscriptionRequest`](/reference/data-model-schema#eventsubscriptionrequest). Then the server sends an -[`EventMessage`](/reference/data-model-schema#eventmessage). Messages are SCALE-encoded[^1]. +- **Protocol**: `HTTP` upgraded to `WebSocket` +- **Encoding**: `SCALE` +- **Endpoint**: `/events` ### Transaction Events -Transaction event statuses can be either `Validating`, `Committed` or `Rejected`. +The status of a transaction event can be one of the following: -Transaction statuses proceed from `Validating` to either `Committed` or `Rejected`. However, due to the distributed -nature of the network, some peers might receive events out of order (e.g. `Committed` before `Validating`). +- `Validating` — The transaction has been successfully submitted and is currently being validated by peers. +- `Committed` — The transaction has been successfully validated and is committed to the blockchain. +- `Rejected` — The transaction has been rejected by at least one peer and is __not__ committed to the blockchain. -Some peers in the network may be offline for the validation round. If the client connects to them while they are -offline, the peers might not respond with the `Validating` status. But when the offline peers come back online they will -synchronize the blocks. They are then guaranteed to respond with the `Committed` (or `Rejected`) status depending on the -information found in the block. +All transactions are designated with the `Validating` status upon creation, which later proceeds to either `Committed` or `Rejected`. However, due to the distributed nature of the network, some peers might receive events out of order (e.g., `Committed` before `Validating`). + +Some peers in the network may be offline for the validation round. If a client connects to them while they are offline, the peers might not respond with the `Validating` status. But when the offline peers come back online they will automatically synchronize the blocks. These peers are then guaranteed to respond with either `Committed` or `Rejected` status, depending on the information found in the block. + +#### Handshake + +Since the `/events` endpoint handles continuous two-way data exchange, a `WebSocket` handshake between the client and server must first be performed to initiate communication with this endpoint. + +The first HTTP request to this endpoint requires a standard set of `WebSocket` headers. + +**Example**: + +```http +Host: example.com:8000 +Upgrade: websocket +Connection: Upgrade +Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw== +Sec-WebSocket-Version: 13 +Sec-WebSocket-Extensions: permessage-deflate, client_max_window_bits +``` + +#### Data Exchange + +After a successful handshake, the client must send an [`EventSubscriptionRequest`](/reference/data-model-schema#eventsubscriptionrequest) request, after which the server sends an [`EventMessage`](/reference/data-model-schema#eventmessage) response. + +#### Responses + +| Code | Response | Description | +| :--: | --------------------- | ----------------------------------------------------------------------------- | +| 101 | Switching Protocols | The protocol is successfully switched from `HTTP` to `WebSocket`. | +| 400 | Bad Request | The server will not process the request due to an issue on the client side. | +| 401 | Unauthorized | The client lacks valid credentials for the request. | +| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | ## Health -- **Protocol:** HTTP -- **Method:** `GET` -- **Endpoint:** `/health` +- **Protocol**: `HTTP` +- **Method**: `GET` +- **Encoding**: `JSON` +- **Endpoint**: `/health` + +#### Requests + +A `GET` request to the endpoint. + +#### Responses + +| Code | Response | Description | +| :--: | --------------------- | ----------------------------------------------------------------------------- | +| 200 | Health Status | Returns the current status of the peer submitting the request. | +| 401 | Unauthorized | The client lacks valid credentials for the request. | +| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | -Responses with `200 OK` and a current status of peer as a JSON string: +**Example**: ```json -"Healthy" +200 Health Status: "Healthy" ``` ## Metrics -- **Protocol:** HTTP -- **Method:** `GET` -- **Endpoint:** `/metrics` +- **Protocol**: `HTTP` +- **Method**: `GET` +- **Encoding**: `JSON` +- **Endpoint**: `/metrics` -**Responses:** +#### Responses -`200 OK` reports 8 of 10 metrics: +| Code | Response | Description | +| :--: | --------------------- | ----------------------------------------------------------------------------- | +| 200 | Metrics | Returns a report on 8 out of 10 Prometheus metrics. | +| 401 | Unauthorized | The client lacks valid credentials for the request. | +| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | -::: details Sample Prometheus metrics +**Example**: + +::: details Example `200 Metrics` response ```bash # HELP accounts User accounts registered at this time @@ -172,37 +322,46 @@ view_changes 0 ::: -Learn [how to use metrics](/guide/advanced/metrics). +::: info + +To learn more about metrics, see [Metrics](../guide/advanced/metrics.md). + +::: ## Query -- **Protocol:** HTTP -- **Method:** `POST` -- **Endpoint:** `/query` -- **Expects:** - - **Body:** SCALE-encoded[^1] [`VersionedSignedQuery`](/reference/data-model-schema#versionedsignedquery) - - **Query parameters:** - - **`start`:** An optional parameter in queries where results can be indexed. Use to return results from a specified - point. Results are ordered by id, which uses Rust's - [PartialOrd](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html#derivable) and - [Ord](https://doc.rust-lang.org/std/cmp/trait.Ord.html) traits. - - **`limit`:** An optional parameter in queries where results can be indexed. Use to return a specific number of - 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 it to specify the exact number of results returned by a - query. - -**Responses:** - -| 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) | -| Signature Error | 401 | [`QueryExecutionFail::Signature(String)`](/reference/data-model-schema#queryexecutionfail) | -| Permission Error | 403 | [`QueryExecutionFail::Permission(String)`](/reference/data-model-schema#queryexecutionfail) | -| Find Error | 404 | [`QueryExecutionFail::Find(FindError)`](/reference/data-model-schema#queryexecutionfail) | +- **Protocol**: `HTTP` +- **Method**: `POST` +- **Encoding**: `SCALE` +- **Endpoint**: `/query` + +#### Requests + +This endpoint expects the following data: + + - **Body**: [`VersionedSignedQuery`](/reference/data-model-schema#versionedsignedquery) + - **Parameters** (optional): + - `start` — Specifies the `id` of a starting entry. A successful response will contain all entries newer than and including the `id` specified.\ + - `limit` — Specifies the exact number of retrieved `id` entries.\ + - `sort_by_metadata_key` — Specifies the metadata key of the `id` entries that will be returned.\ + - `fetch_size` — Specifies the maximum number of results that a response can contain. + +#### Responses + +| Code | Response | Body | +| :--: | ---------------- | ------------------------------------------------------------------------------------------------ | +| 200 | Success | [`VersionedBatchedResponse`](/reference/data-model-schema#versionedbatchedresponse-value) | +| 400 | Conversion Error | [`QueryExecutionFail::Conversion(String)`](/reference/data-model-schema#queryexecutionfail) | +| 400 | Evaluate Error | [`QueryExecutionFail::Evaluate(String)`](/reference/data-model-schema#queryexecutionfail) | +| 401 | Signature Error | [`QueryExecutionFail::Signature(String)`](/reference/data-model-schema#queryexecutionfail) | +| 403 | Permission Error | [`QueryExecutionFail::Permission(String)`](/reference/data-model-schema#queryexecutionfail) | +| 404 | Find Error | [`QueryExecutionFail::Find(FindError)`](/reference/data-model-schema#queryexecutionfail) | + +::: info + +The `200 Success` response returns results that are ordered by `id`, which use Rust's [PartialOrd](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html#derivable) and [Ord](https://doc.rust-lang.org/std/cmp/trait.Ord.html) traits. + +::: ### Account Not Found 404 @@ -226,15 +385,35 @@ Whether each prerequisite object was found and [`FindError`](/reference/data-mod ## Status -- **Protocol:** HTTP -- **Method:** `GET` -- **Endpoint:** `/status` -- **Expects:** an optional `Accept: application/x-parity-scale` request header to encode response with SCALE[^1]. - Otherwise, will fall back to `application/json`. -- **Responses**: with `Content-Type` set either to `application/json` or `application/x-parity-scale`, and an - accordingly encoded response body. +- **Protocol**: `HTTP` +- **Method**: `GET` +- **Encoding**: `JSON` or `SCALE` +- **Endpoint**: `/status` + +#### Requests + +A `GET` request to the endpoint. + +This endpoint also accepts the following: -Response body is of the following `Status` structure: + - **Header**: Specifies the encoding of the retrieved data.\ + Can be set to one of the following: + - `Accept: application/x-parity-scale` — the retrieved data is encoded with SCALE. + - `Accept: application/json` — the retrieved data is encoded with JSON. + +If no header is specified in the request, the `Accept: application/json` header is used by default. + +#### Responses + +| Code | Response | Description | +| :--: | --------------------- | ----------------------------------------------------------------------------- | +| 200 | Iroha Status | Returns the Iroha network status report. | +| 401 | Unauthorized | The client lacks valid credentials for the request. | +| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | + +The `200 Iroha Status` response is generated in accordance with the encoding specified in the header of the request. + +The response body has the following structure: ```rust struct Status { @@ -260,25 +439,9 @@ 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 -number type according to the specification effectively is `f64`, the precision might be lost on deserialization, for -example, in -[JavaScript's `JSON.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse). -For more details, see related [issue](https://github.com/hyperledger/iroha/issues/3964). - -::: - -::: tip Compact Form in SCALE - -Fields with type `u64` serialized in the [Compact form](https://docs.substrate.io/reference/scale-codec/#fn-1). - -::: - -::: details Sample responses +::: details Examples -These samples represent the same data: +The following examples represent the same data: ::: code-group @@ -303,13 +466,48 @@ These samples represent the same data: ::: +::: 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 number type according to the specification effectively is `f64`, the precision might be lost on deserialization, for example, in [JavaScript's `JSON.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse). + +For more details, see the related [GitHub issue](https://github.com/hyperledger/iroha/issues/3964). + +::: + +::: tip Compact Form in SCALE + +Fields with `u64` type are serialized in the [Compact form](https://docs.substrate.io/reference/scale-codec/#fn-1). + +::: + ### Sub-routing -To obtain the value of a specific field, one can append the name of the field to the path, e.g. `/status/peers`. This -returns the corresponding JSON value. +It is also possible to retrieve the data of a specific `struct` group or variable within it by adding their path to the endpoint address. The sub-routed values are only returned in the JSON format. + +**Examples**: ::: code-group +```json [/status] +struct Status { + "peers": 4, + "blocks": 5, + "txs_accepted": 31, + "txs_rejected": 3, + "uptime": { + "secs": 5, + "nanos": 937000000 + }, + "view_changes": 2, + "queue_size": 18 +} + +struct Uptime { + secs: 5, + nanos: 937000000 +} +``` + ```json [/status/peers] 4 ``` @@ -329,23 +527,22 @@ returns the corresponding JSON value. ## Transaction -- **Protocol:** HTTP -- **Method:** `POST` -- **Endpoint:** `/transaction` -- **Expects:** - - **Body:** SCALE-encoded[^1] [`VersionedSignedTransaction`](/reference/data-model-schema#versionedsignedtransaction) +- **Protocol**: `HTTP` +- **Method**: `POST` +- **Encoding**: `SCALE` +- **Endpoint**: `/transaction` + +#### Requests -**Responses:** +This endpoint expects the following data: -| Status | Description | -| ------ | ---------------------------------------------------------------------- | -| 200 | Transaction Accepted (But not guaranteed to have passed consensus yet) | -| 400 | Transaction Rejected (Malformed) | -| 401 | Transaction Rejected (Improperly signed) | + - **Body**: [`VersionedSignedTransaction`](/reference/data-model-schema#versionedsignedtransaction) -[^1]: - For more information on Parity SCALE Codec check - [Substrate Dev Hub](https://docs.substrate.io/reference/scale-codec/) and codec's - [GitHub repository](https://github.com/paritytech/parity-scale-codec). +#### Responses - +| Code | Response | Description | +| :--: | ---------------------------------------- | ---------------------------------------------------------------------------------- | +| 200 | Transaction Accepted | Transaction has been accepted, but is not yet guaranteed to have passed consensus. | +| 400 | Transaction Rejected (Malformed) | Transaction is rejected due to being malformed. | +| 401 | Transaction Rejected (Improperly signed) | Transaction is rejected due to being improperly signed. | +| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | From 22dc36475242ee2da8b7225ececf6c4945c77282 Mon Sep 17 00:00:00 2001 From: yamkovoy <100563712+yamkovoy@users.noreply.github.com> Date: Fri, 19 Jan 2024 15:40:02 +0300 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: 0x009922 <43530070+0x009922@users.noreply.github.com> Signed-off-by: yamkovoy <100563712+yamkovoy@users.noreply.github.com> --- src/reference/torii-endpoints.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/src/reference/torii-endpoints.md b/src/reference/torii-endpoints.md index 8b7a7dd66..1c77a8377 100644 --- a/src/reference/torii-endpoints.md +++ b/src/reference/torii-endpoints.md @@ -10,7 +10,7 @@ For more information on Parity SCALE Codec, see the [Substrate Documentation: Ty ::: -`TORII` is the Iroha 2 module in charge of handling incoming and outgoing connections. It is used to receive, accept and route incoming instructions, and HTTP queries, as well as run-time configuration updates. +Torii (jap. 鳥居 - gates; Shinto shrine archway) is the Iroha module in charge of handling HTTP and WebSocket requests. It is the main application programmable interface to interact with Iroha. Such interactions include sending transactions, making queries, listening for blocks stream, and so on. To establish two-way communication with the `TORII` endpoints, the following addresses must be specified in the Iroha 2 configuration files: @@ -125,7 +125,6 @@ A `GET` request to the endpoint. **Example**: ```json -200 OK: { "logger": { "level": "TRACE" @@ -407,11 +406,7 @@ If no header is specified in the request, the `Accept: application/json` header | Code | Response | Description | | :--: | --------------------- | ----------------------------------------------------------------------------- | -| 200 | Iroha Status | Returns the Iroha network status report. | -| 401 | Unauthorized | The client lacks valid credentials for the request. | -| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | - -The `200 Iroha Status` response is generated in accordance with the encoding specified in the header of the request. +| 200 | Iroha Status | Returns the Iroha network status report. The response is generated in accordance with the encoding specified in the header of the request and is specified in `Content-Type` response header. | The response body has the following structure: From 1c68a40449cc3f232121a238ae035d3676763eec Mon Sep 17 00:00:00 2001 From: yamkovoy Date: Fri, 19 Jan 2024 18:20:56 +0300 Subject: [PATCH 3/5] Updated after review Signed-off-by: yamkovoy --- src/guide/advanced/metrics.md | 2 + src/reference/torii-endpoints.md | 169 ++++++++++++++++++++----------- 2 files changed, 114 insertions(+), 57 deletions(-) diff --git a/src/guide/advanced/metrics.md b/src/guide/advanced/metrics.md index 14dcfd09c..16b8e07a1 100644 --- a/src/guide/advanced/metrics.md +++ b/src/guide/advanced/metrics.md @@ -10,6 +10,8 @@ See [Reference > Torii Endpoints: Metrics](../../reference/torii-endpoints.md#me ## How to use metrics + + To collect metrics via the `/metrics` endpoint, the following must first be configured: - In the [`configs/peer/config.json`](https://github.com/hyperledger/iroha/blob/iroha2-dev/configs/peer/config.json) configuration file: diff --git a/src/reference/torii-endpoints.md b/src/reference/torii-endpoints.md index 1c77a8377..00462e5f3 100644 --- a/src/reference/torii-endpoints.md +++ b/src/reference/torii-endpoints.md @@ -1,16 +1,18 @@ # Torii Endpoints -::: tip Note +::: tip About Parity SCALE Codec -Messages for certain `TORII` operations are encoded with Parity SCALE Codec commonly used with the [Parity Substrate](https://www.parity.io/technologies/substrate/) blockchain framework, and other blockchains utilizing it. +Messages for certain `TORII` operations are encoded with the Parity SCALE Codec (`SCALE`) commonly used with the [Parity Substrate](https://www.parity.io/technologies/substrate/) blockchain framework, and other blockchains utilizing it. -For more information on Parity SCALE Codec, see the [Substrate Documentation: Type encoding (SCALE)](https://docs.substrate.io/reference/scale-codec/) article and its [official GitHub repository](https://github.com/paritytech/parity-scale-codec). +For more information on `SCALE`, see the [Substrate Documentation: Type encoding (SCALE)](https://docs.substrate.io/reference/scale-codec/) article and its [official GitHub repository](https://github.com/paritytech/parity-scale-codec). ::: -Torii (jap. 鳥居 - gates; Shinto shrine archway) is the Iroha module in charge of handling HTTP and WebSocket requests. It is the main application programmable interface to interact with Iroha. Such interactions include sending transactions, making queries, listening for blocks stream, and so on. +Torii (Japanese: 鳥居 — Shinto shrine gateway) is the Iroha 2 module in charge of handling `HTTP` and `WebSocket` requests. It is the main API for interacting with Iroha 2. Such interactions include sending transactions, making queries, listening for blocks stream, etc. + + + ## API Version +::: info + +This operation requires the Iroha 2 network to be established with the `telemetry` feature enabled. + + + +::: + - **Protocol**: `HTTP` - **Method**: `GET` - **Encoding**: `JSON` @@ -49,16 +61,14 @@ A `GET` request to the endpoint. #### Responses -| Code | Response | Description | -| :--: | --------------------- | ----------------------------------------------------------------------------- | -| 200 | OK | Returns the current version of the API used by Iroha 2. | -| 401 | Unauthorized | The client lacks valid credentials for the request. | -| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | +| Code | Response | Description | +| :--: | -------- | ------------------------------------------------------------------------ | +| 200 | OK | Returns the current version of the API used by Iroha 2 as a JSON string. | **Example**: ```json -200 OK: "1" +"1" ``` ::: info @@ -94,15 +104,6 @@ Sec-WebSocket-Extensions: permessage-deflate, client_max_window_bits After a successful handshake, the client must send a [`BlockSubscriptionRequest`](/reference/data-model-schema#blocksubscriptionrequest) request with the starting block number provided (i.e., the `height` value). Then, upon sending the confirmation and [`BlockMessage`](/reference/data-model-schema#blockmessage) messages, the server starts streaming all of the blocks, beginning with the block specified with `height` up to the most recent one, and then continues to stream new blocks as they are added to the blockchain. -#### Responses - -| Code | Response | Description | -| :--: | --------------------- | ----------------------------------------------------------------------------- | -| 101 | Switching Protocols | The protocol is successfully switched from `HTTP` to `WebSocket`. | -| 400 | Bad Request | The server will not process the request due to an issue on the client side. | -| 401 | Unauthorized | The client lacks valid credentials for the request. | -| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | - ## Configuration / Retrieve - **Protocol**: `HTTP` @@ -116,11 +117,9 @@ A `GET` request to the endpoint. #### Responses -| Code | Response | Description | -| :--: | --------------------- | ----------------------------------------------------------------------------- | -| 200 | OK | Returns a subset of configuration parameters serialized into JSON format. | -| 401 | Unauthorized | The client lacks valid credentials for the request. | -| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | +| Code | Response | Description | +| :--: | -------- | ------------------------------------------------------------------------- | +| 200 | OK | Returns a subset of configuration parameters serialized into JSON format. | **Example**: @@ -172,11 +171,9 @@ The progress on the configuration reference can be tracked in the following GitH #### Responses -| Code | Response | Description | -| :--: | --------------------- | ------------------------------------------------------------------------------- | -| 202 | Accepted | The request to update the configuration is accepted and is due to be processed. | -| 401 | Unauthorized | The client lacks valid credentials for the request. | -| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | +| Code | Response | Description | +| :--: | -------- | ------------------------------------------------------------------------------- | +| 202 | Accepted | The request to update the configuration is accepted and is due to be processed. | ::: tip Guarantees @@ -186,7 +183,7 @@ A successful configuration update does not guarantee that the configuration is i ## Events -- **Protocol**: `HTTP` upgraded to `WebSocket` +- **Protocols**: `HTTP` upgraded to `WebSocket` - **Encoding**: `SCALE` - **Endpoint**: `/events` @@ -223,15 +220,6 @@ Sec-WebSocket-Extensions: permessage-deflate, client_max_window_bits After a successful handshake, the client must send an [`EventSubscriptionRequest`](/reference/data-model-schema#eventsubscriptionrequest) request, after which the server sends an [`EventMessage`](/reference/data-model-schema#eventmessage) response. -#### Responses - -| Code | Response | Description | -| :--: | --------------------- | ----------------------------------------------------------------------------- | -| 101 | Switching Protocols | The protocol is successfully switched from `HTTP` to `WebSocket`. | -| 400 | Bad Request | The server will not process the request due to an issue on the client side. | -| 401 | Unauthorized | The client lacks valid credentials for the request. | -| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | - ## Health - **Protocol**: `HTTP` @@ -245,20 +233,26 @@ A `GET` request to the endpoint. #### Responses -| Code | Response | Description | -| :--: | --------------------- | ----------------------------------------------------------------------------- | -| 200 | Health Status | Returns the current status of the peer submitting the request. | -| 401 | Unauthorized | The client lacks valid credentials for the request. | -| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | +| Code | Response | Description | +| :--: | ------------- | -------------------------------------------------------------- | +| 200 | Health Status | Returns the current status of the peer submitting the request. | **Example**: ```json -200 Health Status: "Healthy" +"Healthy" ``` ## Metrics +::: info + +This operation requires the Iroha 2 network to be established with the `telemetry` feature enabled. + + + +::: + - **Protocol**: `HTTP` - **Method**: `GET` - **Encoding**: `JSON` @@ -266,11 +260,9 @@ A `GET` request to the endpoint. #### Responses -| Code | Response | Description | -| :--: | --------------------- | ----------------------------------------------------------------------------- | -| 200 | Metrics | Returns a report on 8 out of 10 Prometheus metrics. | -| 401 | Unauthorized | The client lacks valid credentials for the request. | -| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | +| Code | Response | Description | +| :--: | -------- | --------------------------------------------------- | +| 200 | Metrics | Returns a report on 8 out of 10 Prometheus metrics. | **Example**: @@ -327,6 +319,37 @@ To learn more about metrics, see [Metrics](../guide/advanced/metrics.md). ::: +## Pending Transactions + +- **Protocol**: `HTTP` +- **Method**: `GET` +- **Encoding**: `SCALE` +- **Endpoint**: `/pending_transactions` + +#### Requests + +A `GET` request to the endpoint. + +#### Responses + +| Code | Response | Description | +| :--: | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 | OK | Returns a list of pending transactions as [`SignedTransaction`](data-model-schema.md#signedtransaction) objects encoded with `SCALE`; must be decoded by the client. | + +**Example**: + +```[SCALE] +[ + 34, + 86, + 97, + 108, + 117, + 101, + 34 +] +``` + ## Query - **Protocol**: `HTTP` @@ -382,8 +405,41 @@ Whether each prerequisite object was found and [`FindError`](/reference/data-mod | Y | - | N | - | [`FindError::AssetDefinition(AssetDefinitionId)`](/reference/data-model-schema#finderror) | | Y | Y | Y | N | [`FindError::Asset(AssetId)`](/reference/data-model-schema#finderror) | +## Schema + +::: info + +This operation requires the Iroha 2 network to be established with the `schema` feature enabled. + + + +::: + +- **Protocol**: `HTTP` +- **Method**: `GET` +- **Encoding**: `JSON` +- **Endpoint**: `/schema` + +#### Requests + +A `GET` request to the endpoint. + +#### Responses + +| Code | Response | Description | +| :--: | -------- | ------------------------------------------------------------------------------------------------------------------- | +| 200 | OK | Returns the Rust data structures and types of the entire [Data Model Schema](data-model-schema.md) as JSON objects. | + ## Status +::: info + +This operation requires the Iroha 2 network to be established with the `telemetry` feature enabled. + + + +::: + - **Protocol**: `HTTP` - **Method**: `GET` - **Encoding**: `JSON` or `SCALE` @@ -397,16 +453,16 @@ This endpoint also accepts the following: - **Header**: Specifies the encoding of the retrieved data.\ Can be set to one of the following: - - `Accept: application/x-parity-scale` — the retrieved data is encoded with SCALE. - - `Accept: application/json` — the retrieved data is encoded with JSON. + - `Accept: application/x-parity-scale` — the retrieved data is encoded with `SCALE`. + - `Accept: application/json` — the retrieved data is encoded with `JSON`. If no header is specified in the request, the `Accept: application/json` header is used by default. #### Responses -| Code | Response | Description | -| :--: | --------------------- | ----------------------------------------------------------------------------- | -| 200 | Iroha Status | Returns the Iroha network status report. The response is generated in accordance with the encoding specified in the header of the request and is specified in `Content-Type` response header. | +| Code | Response | Description | +| :--: | --------------------- | ------------------------------------------------------------------------------------------ | +| 200 | Iroha Status | Returns the Iroha network status report encoded as specified in the header of the request. | The response body has the following structure: @@ -484,7 +540,7 @@ It is also possible to retrieve the data of a specific `struct` group or variabl ::: code-group ```json [/status] -struct Status { +{ "peers": 4, "blocks": 5, "txs_accepted": 31, @@ -540,4 +596,3 @@ This endpoint expects the following data: | 200 | Transaction Accepted | Transaction has been accepted, but is not yet guaranteed to have passed consensus. | | 400 | Transaction Rejected (Malformed) | Transaction is rejected due to being malformed. | | 401 | Transaction Rejected (Improperly signed) | Transaction is rejected due to being improperly signed. | -| 500 | Internal Server Error | The server encountered an unexpected issue and could not fulfill the request. | From 69b38d4d934d038cf1afe55abfa88e5d0ab1f657 Mon Sep 17 00:00:00 2001 From: yamkovoy <100563712+yamkovoy@users.noreply.github.com> Date: Wed, 31 Jan 2024 19:30:31 +0300 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: 0x009922 <43530070+0x009922@users.noreply.github.com> Signed-off-by: yamkovoy <100563712+yamkovoy@users.noreply.github.com> --- src/reference/torii-endpoints.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/src/reference/torii-endpoints.md b/src/reference/torii-endpoints.md index 00462e5f3..88da2259e 100644 --- a/src/reference/torii-endpoints.md +++ b/src/reference/torii-endpoints.md @@ -44,7 +44,7 @@ To establish two-way communication with the `TORII` endpoints, the following add ::: info -This operation requires the Iroha 2 network to be established with the `telemetry` feature enabled. +This operation requires the particular Iroha node you are making request to to be compiled with the `telemetry` feature enabled. @@ -102,7 +102,7 @@ Sec-WebSocket-Extensions: permessage-deflate, client_max_window_bits #### Data Exchange -After a successful handshake, the client must send a [`BlockSubscriptionRequest`](/reference/data-model-schema#blocksubscriptionrequest) request with the starting block number provided (i.e., the `height` value). Then, upon sending the confirmation and [`BlockMessage`](/reference/data-model-schema#blockmessage) messages, the server starts streaming all of the blocks, beginning with the block specified with `height` up to the most recent one, and then continues to stream new blocks as they are added to the blockchain. +After establishing a WebSocket connection, the client must send a [`BlockSubscriptionRequest`](/reference/data-model-schema#blocksubscriptionrequest) request with the starting block number provided (i.e., the `height` value). Then, upon sending the confirmation and [`BlockMessage`](/reference/data-model-schema#blockmessage) messages, the server starts streaming all of the blocks, beginning with the block specified with `height` up to the most recent one, and then continues to stream new blocks as they are added to the blockchain. ## Configuration / Retrieve @@ -381,7 +381,7 @@ This endpoint expects the following data: ::: info -The `200 Success` response returns results that are ordered by `id`, which use Rust's [PartialOrd](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html#derivable) and [Ord](https://doc.rust-lang.org/std/cmp/trait.Ord.html) traits. +The `200 Success` response returns results that are ordered by `id`, which use Rust's [PartialOrd](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) and [Ord](https://doc.rust-lang.org/std/cmp/trait.Ord.html) traits. ::: @@ -552,11 +552,6 @@ It is also possible to retrieve the data of a specific `struct` group or variabl "view_changes": 2, "queue_size": 18 } - -struct Uptime { - secs: 5, - nanos: 937000000 -} ``` ```json [/status/peers] From b09c1ac0c36c8c7ee5c3482335e584b3f9e34c20 Mon Sep 17 00:00:00 2001 From: yamkovoy Date: Wed, 31 Jan 2024 20:19:47 +0300 Subject: [PATCH 5/5] Torii: Updated after review, minor fixes Signed-off-by: yamkovoy --- src/guide/advanced/metrics.md | 13 +++----- src/reference/torii-endpoints.md | 52 ++++---------------------------- 2 files changed, 10 insertions(+), 55 deletions(-) diff --git a/src/guide/advanced/metrics.md b/src/guide/advanced/metrics.md index 16b8e07a1..1c47144b5 100644 --- a/src/guide/advanced/metrics.md +++ b/src/guide/advanced/metrics.md @@ -12,17 +12,12 @@ See [Reference > Torii Endpoints: Metrics](../../reference/torii-endpoints.md#me -To collect metrics via the `/metrics` endpoint, the following must first be configured: +Work in Progress. -- In the [`configs/peer/config.json`](https://github.com/hyperledger/iroha/blob/iroha2-dev/configs/peer/config.json) configuration file: - - `"TORII"`: `"TELEMETRY_URL"` variable; - - `"TELEMETRY"` object in its entirety.\ - > For details, see [Peer Configuration](../configure/peer-configuration.md). +This topic will be updated as part of the new configuration reference. -- In the [`configs/client/config.json`](https://github.com/hyperledger/iroha/blob/iroha2-dev/configs/client/config.json) configuration file: - - `"TORII_TELEMETRY_URL"` variable.\ - Set to `http://127.0.0.1:8180/`, by default. If the port is not available, Iroha will still function properly, but the metrics won't be provided. - > For details, see [Client Configuration](../configure/client-configuration.md) +The progress on the configuration reference can be tracked in the following GitHub issue:\ +[iroha-2-docs > Issue #392: Tracking issue for Configuration Reference as per RFC](https://github.com/hyperledger/iroha-2-docs/issues/392). ::: note diff --git a/src/reference/torii-endpoints.md b/src/reference/torii-endpoints.md index 88da2259e..811ae9b33 100644 --- a/src/reference/torii-endpoints.md +++ b/src/reference/torii-endpoints.md @@ -44,7 +44,7 @@ To establish two-way communication with the `TORII` endpoints, the following add ::: info -This operation requires the particular Iroha node you are making request to to be compiled with the `telemetry` feature enabled. +This operation requires the specific Iroha node being requested to be compiled with the `telemetry` feature enabled. @@ -61,9 +61,9 @@ A `GET` request to the endpoint. #### Responses -| Code | Response | Description | -| :--: | -------- | ------------------------------------------------------------------------ | -| 200 | OK | Returns the current version of the API used by Iroha 2 as a JSON string. | +| Code | Response | Description | +| :--: | -------- | ------------------------------------------------------------------------------------------- | +| 200 | OK | Returns the current version of the API used by the requested Iroha 2 node as a JSON string. | **Example**: @@ -87,22 +87,9 @@ The API version is retrieved from and is the same as the version of the [genesis Since the `/block/stream` endpoint handles continuous two-way data exchange, a `WebSocket` handshake between the client and server must first be performed to initiate communication with this endpoint. -The first HTTP request to this endpoint requires a standard set of `WebSocket` headers. - -**Example**: - -```http -Host: example.com:8000 -Upgrade: websocket -Connection: Upgrade -Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw== -Sec-WebSocket-Version: 13 -Sec-WebSocket-Extensions: permessage-deflate, client_max_window_bits -``` - #### Data Exchange -After establishing a WebSocket connection, the client must send a [`BlockSubscriptionRequest`](/reference/data-model-schema#blocksubscriptionrequest) request with the starting block number provided (i.e., the `height` value). Then, upon sending the confirmation and [`BlockMessage`](/reference/data-model-schema#blockmessage) messages, the server starts streaming all of the blocks, beginning with the block specified with `height` up to the most recent one, and then continues to stream new blocks as they are added to the blockchain. +After establishing a `WebSocket` connection, the client must send a [`BlockSubscriptionRequest`](/reference/data-model-schema#blocksubscriptionrequest) request with the starting block number provided (i.e., the `height` value). Then, upon sending the confirmation and [`BlockMessage`](/reference/data-model-schema#blockmessage) messages, the server starts streaming all of the blocks, beginning with the block specified with `height` up to the most recent one, and then continues to stream new blocks as they are added to the blockchain. ## Configuration / Retrieve @@ -203,22 +190,9 @@ Some peers in the network may be offline for the validation round. If a client c Since the `/events` endpoint handles continuous two-way data exchange, a `WebSocket` handshake between the client and server must first be performed to initiate communication with this endpoint. -The first HTTP request to this endpoint requires a standard set of `WebSocket` headers. - -**Example**: - -```http -Host: example.com:8000 -Upgrade: websocket -Connection: Upgrade -Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw== -Sec-WebSocket-Version: 13 -Sec-WebSocket-Extensions: permessage-deflate, client_max_window_bits -``` - #### Data Exchange -After a successful handshake, the client must send an [`EventSubscriptionRequest`](/reference/data-model-schema#eventsubscriptionrequest) request, after which the server sends an [`EventMessage`](/reference/data-model-schema#eventmessage) response. +After establishing a `WebSocket` connection, the client must send an [`EventSubscriptionRequest`](/reference/data-model-schema#eventsubscriptionrequest) request, after which the server sends an [`EventMessage`](/reference/data-model-schema#eventmessage) response. ## Health @@ -336,20 +310,6 @@ A `GET` request to the endpoint. | :--: | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Returns a list of pending transactions as [`SignedTransaction`](data-model-schema.md#signedtransaction) objects encoded with `SCALE`; must be decoded by the client. | -**Example**: - -```[SCALE] -[ - 34, - 86, - 97, - 108, - 117, - 101, - 34 -] -``` - ## Query - **Protocol**: `HTTP`