diff --git a/@l10n/ja/docs/_snippets/common-links.md b/@l10n/ja/docs/_snippets/common-links.md index 390a3b1a48..b937ba1b82 100644 --- a/@l10n/ja/docs/_snippets/common-links.md +++ b/@l10n/ja/docs/_snippets/common-links.md @@ -14,8 +14,8 @@ [AMMVoteトランザクション]: /@l10n/ja/docs/references/protocol/transactions/types/ammvote.md [AMMWithdraw]: /@l10n/ja/docs/references/protocol/transactions/types/ammwithdraw.md [AMMWithdrawトランザクション]: /@l10n/ja/docs/references/protocol/transactions/types/ammwithdraw.md -[API v1]: /@l10n/ja/docs/references/http-websocket-apis/api-conventions/request-formatting.md#api-versioning -[API v2]: /@l10n/ja/docs/references/http-websocket-apis/api-conventions/request-formatting.md#api-versioning +[API v1]: /@l10n/ja/docs/references/http-websocket-apis/index.md +[API v2]: /@l10n/ja/docs/references/http-websocket-apis/index.md [AccountDelete]: /@l10n/ja/docs/references/protocol/transactions/types/accountdelete.md [AccountDeleteトランザクション]: /@l10n/ja/docs/references/protocol/transactions/types/accountdelete.md [AccountRootエントリ]: /@l10n/ja/docs/references/protocol/ledger-data/ledger-entry-types/accountroot.md diff --git a/@l10n/ja/docs/references/http-websocket-apis/public-api-methods/account-methods/account_tx.md b/@l10n/ja/docs/references/http-websocket-apis/public-api-methods/account-methods/account_tx.md index e5b299ddfe..c942163b92 100644 --- a/@l10n/ja/docs/references/http-websocket-apis/public-api-methods/account-methods/account_tx.md +++ b/@l10n/ja/docs/references/http-websocket-apis/public-api-methods/account-methods/account_tx.md @@ -81,7 +81,7 @@ rippled -- account_tx rLNaPoKeeBjZe2qs6x52yVPZpZ8td4dc6w -1 -1 2 0 binary descen | `marker` | [マーカー][] | 以前にページネーションされたレスポンスの値。そのレスポンスを停止した箇所からデータの取得を再開します。サーバが使用できるレジャーの範囲に変更があっても、この値は変わりません。 | - リクエスト内で次の各フィールドのうち1つ以上を使用する必要があります: `ledger_index`、`ledger_hash`、`ledger_index_min`、または`ledger_index_max`。 -- [API v2]： `ledger_index`と`ledger_hash`のどちらかを指定した場合、`ledger_index_min`と`ledger_index_max`を含めると`invalidParams`エラーが返ります。 +- [API v2][]： `ledger_index`と`ledger_hash`のどちらかを指定した場合、`ledger_index_min`と`ledger_index_max`を含めると`invalidParams`エラーが返ります。 ### 照会されたデータの繰り返し diff --git a/docs/_snippets/common-links.md b/docs/_snippets/common-links.md index 2e2df23691..bd3a0f1384 100644 --- a/docs/_snippets/common-links.md +++ b/docs/_snippets/common-links.md @@ -21,8 +21,8 @@ [AMMWithdraw transaction]: /docs/references/protocol/transactions/types/ammwithdraw.md [AMMWithdraw transactions]: /docs/references/protocol/transactions/types/ammwithdraw.md [AMMWithdraw]: /docs/references/protocol/transactions/types/ammwithdraw.md -[API v1]: /docs/references/http-websocket-apis/api-conventions/request-formatting.md#api-versioning -[API v2]: /docs/references/http-websocket-apis/api-conventions/request-formatting.md#api-versioning +[API v1]: /docs/references/http-websocket-apis/index.md#api-versioning +[API v2]: /docs/references/http-websocket-apis/index.md#api-versioning [AccountDelete transaction]: /docs/references/protocol/transactions/types/accountdelete.md [AccountDelete transactions]: /docs/references/protocol/transactions/types/accountdelete.md [AccountDelete]: /docs/references/protocol/transactions/types/accountdelete.md diff --git a/docs/img/_sources/api-functionality-venn-diagram.uxf b/docs/img/_sources/api-functionality-venn-diagram.uxf new file mode 100644 index 0000000000..8f6161da38 --- /dev/null +++ b/docs/img/_sources/api-functionality-venn-diagram.uxf @@ -0,0 +1,168 @@ + + + 10 + + UMLUseCase + + 230 + 90 + 400 + 360 + + + + + + UMLUseCase + + 30 + 90 + 400 + 360 + + + + + + Text + + 140 + 50 + 110 + 30 + + *rippled Server* + + + + Text + + 400 + 50 + 110 + 30 + + *Clio Server* + + + + Text + + 310 + 70 + 50 + 30 + + *Both* + + + + Text + + 290 + 250 + 100 + 50 + + style=wordwrap +• Serve most API methods + + + + Text + + 430 + 150 + 140 + 50 + + style=wordwrap +• Scales efficiently to many requests + + + + Text + + 30 + 0 + 490 + 40 + + fontsize=20 +*API functionality provided by servers* + + + + Text + + 90 + 160 + 150 + 50 + + style=wordwrap +• Provides Admin API methods + + + + Text + + 70 + 220 + 150 + 80 + + style=wordwrap +• Provides pending / unvalidated data including transaction queue + + + + + Text + + 80 + 300 + 160 + 70 + + style=wordwrap +• Has a live view of consensus and peer-to-peer network + + + + Text + + 440 + 200 + 180 + 70 + + style=wordwrap +• Provides NFT methods: nft_history, nft_info, nfts_by_issuer + + + + Text + + 450 + 270 + 180 + 50 + + style=wordwrap +• Provides mpt_holders method + + + + Text + + 430 + 320 + 140 + 80 + + style=wordwrap +• Serves rippled-exclusive API requests by forwarding + + + diff --git a/docs/img/api-functionality-venn-diagram.svg b/docs/img/api-functionality-venn-diagram.svg new file mode 100644 index 0000000000..30bf864f42 --- /dev/null +++ b/docs/img/api-functionality-venn-diagram.svg @@ -0,0 +1,138 @@ + + +• Servesrippled-exclusiveAPI requests byforwarding• Provides mpt_holdersmethod• Provides NFT methods:nft_history, nft_info,nfts_by_issuer• Has a live view ofconsensus andpeer-to-peer network• Provides pending /unvalidated dataincludingtransaction queue• Provides AdminAPI methodsAPI functionality provided by servers• Scales efficientlyto many requests• Serve mostAPI methodsBothClio Serverrippled Server diff --git a/docs/references/http-websocket-apis/api-conventions/request-formatting.md b/docs/references/http-websocket-apis/api-conventions/request-formatting.md index cad643d8c5..e9d2ff0cf2 100644 --- a/docs/references/http-websocket-apis/api-conventions/request-formatting.md +++ b/docs/references/http-websocket-apis/api-conventions/request-formatting.md @@ -1,6 +1,4 @@ --- -html: request-formatting.html -parent: api-conventions.html seo: description: Standard request format, with examples, for the WebSocket, JSON-RPC, and Commandline interfaces. --- @@ -13,12 +11,11 @@ seo: {% tab label="WebSocket" %} ```json { - "id": 2, + "id": "example_ws_request_1", "command": "account_info", "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", - "strict": true, "ledger_index": "validated", - "api_version": 1 + "api_version": 2 } ``` {% /tab %} @@ -33,9 +30,8 @@ Content-Type: application/json "params": [ { "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", - "strict": true, "ledger_index": "validated", - "api_version": 1 + "api_version": 2 } ] } @@ -44,7 +40,7 @@ Content-Type: application/json {% tab label="Commandline" %} ```sh -rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated strict +rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated ``` {% /tab %} @@ -59,7 +55,7 @@ After you open a WebSocket to the `rippled` server, you can send commands as a [ |:--------------------|:----------|:-------------------------------------------| | `command` | String | The name of the [API method](../public-api-methods/index.md). | | `id` | (Various) | _(Optional)_ A unique value to identify this request. The response to this request uses the same `id` field. This way, even if responses arrive out of order, you know which request prompted which response. | -| `api_version` | Number | _(Optional)_ The API version to use. If omitted, uses version 1. For details, see [API Versioning](#api-versioning). | +| `api_version` | Number | _(Optional)_ The API version to use. For details, see [API Versioning](../index.md#api-versioning). | | (Method Parameters) | (Various) | Provide any parameters to the method at the top level. | See [Response Formatting](response-formatting.md) for the response from the server. @@ -84,7 +80,7 @@ The object inside the `params` array can contain the following fields: | Field | Type | Description | |:--------------------|:----------|:-------------------------------------------| -| `api_version` | Number | _(Optional)_ The API version to use. If omitted, uses version `1`. For details, see [API Versioning](#api-versioning). | +| `api_version` | Number | _(Optional)_ The API version to use. For details, see [API Versioning](#api-versioning). | | (Method Parameters) | (Various) | Provide any parameters to the method here. | See [Response Formatting](response-formatting.md) for the response from the server. @@ -95,7 +91,7 @@ Put the API method name after any normal (dash-prefaced) commandline options, fo The commandline calls JSON-RPC, so its responses always match the JSON-RPC [response format](response-formatting.md). -The commandline always uses the latest [API version](#api-versioning). +The commandline always uses the latest [API version](./index.md#api-versioning). {% admonition type="warning" name="Caution" %}The commandline interface is intended for administrative purposes only and is _not a supported API_. New versions of `rippled` may introduce breaking changes to the commandline API without warning!{% /admonition %} diff --git a/docs/references/http-websocket-apis/index.md b/docs/references/http-websocket-apis/index.md index a7c73465a2..f96c04040d 100644 --- a/docs/references/http-websocket-apis/index.md +++ b/docs/references/http-websocket-apis/index.md @@ -6,37 +6,38 @@ metadata: --- # HTTP / WebSocket APIs -You can communicate with the XRP Ledger through the `rippled` servers' publicly available APIs. +You can communicate directly with the XRP Ledger through HTTP-based APIs provided by the core `rippled` server as well as the Clio server. Both types of server provide JSON-RPC and WebSocket APIs with mostly the same functionality. JSON-RPC uses a strict request-response paradigm similar to a REST API, but WebSocket uses a single persistent connection where the server can push messages to the client asynchronously. For more information, see [Get Started Using HTTP / WebSocket APIs](../../tutorials/http-websocket-apis/build-apps/get-started.md). + +[{% inline-svg file="/docs/img/api-functionality-venn-diagram.svg" /%}](/docs/img/api-functionality-venn-diagram.svg "Diagram: Most API methods are provided by both rippled and Clio servers. The rippled server provides admin methods, provides pending/unvalidated data including transaction queue, and has a live view of consensus and peer-to-peer network. The Clio server scales efficiently, provides additional methods nft_history, nft_info, nfts_by_issuer, and mpt_holders, and serves rippled-exclusive API requests by forwarding.") + +## API Versioning Currently, there are two API versions: `1` and `2` {% badge href="https://github.com/XRPLF/rippled/releases/tag/2.0.0" %}New in: rippled 2.0.0{% /badge %}. The server reports the range of supported API versions in the [`version` API method](public-api-methods/server-info-methods/version.md); you can specify which version to use in your API requests. -Separate API requests can use different API versions even on the same persistent connection. For example, if you connect through WebSocket to a server that supports API versions 1 and 2, you can make an `account_tx` request using API version 2 and then make another `account_tx` request using API version 1 from the same connection. - -- For a full list of the differences between API versions, see [API-CHANGELOG on GitHub](https://github.com/xrplf/rippled/blob/develop/API-CHANGELOG.md). +- For a full list of the differences between API versions, see [API-CHANGELOG on GitHub](https://github.com/XRPLF/rippled/blob/develop/API-CHANGELOG.md). - To stay up-to-date with API changes, join the [ripple server mailing list](https://groups.google.com/g/ripple-server). +### Specifying a Version -## Default API Versions +Use the `api_version` field of the request to specify which API version to use. See [Request Formatting](./api-conventions/request-formatting.md) for example requests. -The table below shows which version of the `rippled` API is used if you don't specify it in the request: +Separate API requests can use different API versions even on the same persistent connection. For example, if you connect through WebSocket to a server that supports API versions 1 and 2, you can make an `account_tx` request using API version 2 and then make another `account_tx` request using API version 1 from the same connection. -| Request Method | API Version | Additional Notes | -|----------------|-------------|------------------| -| Websocket | 1 | | -| JSON-RPC | 1 | | -| Commandline | 2 | The commandline only uses the latest API version. | -| [xrpl.js](https://github.com/XRPLF/xrpl.js) | 2 | Defaults to [API v2][] starting in v4.0.0. | -| [xrpl-py](https://github.com/XRPLF/xrpl-py) | 2 | Defaults to [API v2][] starting in v3.0.0. | +### Default API Versions -{% admonition type="info" name="Note" %} -Clio behaves the same as `rippled`. -{% /admonition %} +If you do not specify an API version when making a request directly to the server, the server uses API v1. However, some [client libraries](../client-libraries.md) automatically use a different API version if you do not specify one. The following table shows which API version each library uses when you don't specify which API version to use: + +| Client Library | API Version | Additional Notes | +|-----------------------------------------------|-------------|------------------| +| None - direct WebSocket / JSON-RPC connection | 1 | | +| None - `rippled` Commandline | 2 | The commandline only uses the latest API version. | +| [xrpl.js](https://github.com/XRPLF/xrpl.js) | 2 | Versions 3.x and older use API v1 by default. | +| [xrpl-py](https://github.com/XRPLF/xrpl-py) | 2 | Versions 2.x and older use API v1 by default. | -Future versions of `rippled` that introduce breaking changes will introduce a new API version 3. ### Breaking Changes -The following types of changes are **breaking changes**: +New API versions can introduce breaking changes. The following types of changes are **breaking changes**: - Removing or renaming a field of a request or response. - Changing the type of a field of a request or response. @@ -44,16 +45,10 @@ The following types of changes are **breaking changes**: - Changing the order of positional parameters, or adding a new field before other positional parameters. - Removing or renaming an API method. - Changing the behavior of an API function visible to existing clients. -- The following types of breaking changes only apply to the gRPC API: - - Changing a `proto` field number. - - Removing or renaming an enum or enum value. - - Adding or removing fields from a `oneof`. - - Splitting or merging a `oneof`. - - Changing whether a message field is `optional`, `repeated`, or `required`. - - Changing the stream value of a request or response. - - Deleting or renaming a package or service. -Any time a full release introduces a breaking change, it introduces a new API version number. Pre-release, beta, and development versions may introduce breaking changes to the same API version number. +Any time a full release introduces a breaking change, it introduces a new API version number. + +API versions are subject to change until they are included in a stable release of the server. New API versions are expected to experience multiple breaking changes across development, beta, and pre-release software. ### Non-Breaking Changes @@ -61,7 +56,11 @@ The following types of changes are **non-breaking changes** and may occur withou - Adding a new field to a request or response, not including positional parameters. - Adding a new API method. +- Fixing a bug so that the API matches prior documentation and behavior. -{% raw-partial file="/docs/_snippets/common-links.md" /%} +## API Method References {% child-pages /%} + + +{% raw-partial file="/docs/_snippets/common-links.md" /%}