diff --git a/content/_snippets/rippled-api-links.md b/content/_snippets/rippled-api-links.md index d1534e4331b..c7115d52dda 100644 --- a/content/_snippets/rippled-api-links.md +++ b/content/_snippets/rippled-api-links.md @@ -2,6 +2,8 @@ [Address]: basic-data-types.html#addresses [アドレス]: basic-data-types.html#アドレス [admin command]: admin-api-methods.html +[API v1]: request-formatting.html#api-versioning +[API v2]: request-formatting.html#api-versioning [base58]: base58-encodings.html [common fields]: transaction-common-fields.html [共通フィールド]: transaction-common-fields.html diff --git a/content/_snippets/rippled_versions.md b/content/_snippets/rippled_versions.md index 321a2456fa6..106053a9416 100644 --- a/content/_snippets/rippled_versions.md +++ b/content/_snippets/rippled_versions.md @@ -44,6 +44,7 @@ "1.10.0", "1.11.0", "1.12.0", + "2.0.0" ] %} {% for v in rippled_versions %} diff --git a/content/references/http-websocket-apis/api-conventions/request-formatting.md b/content/references/http-websocket-apis/api-conventions/request-formatting.md index cdbbfc13286..efc7a0fef28 100644 --- a/content/references/http-websocket-apis/api-conventions/request-formatting.md +++ b/content/references/http-websocket-apis/api-conventions/request-formatting.md @@ -83,7 +83,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, use version 1. For details, see [API Versioning](#api-versioning). [New in: rippled 1.5.0][] | +| `api_version` | Number | _(Optional)_ The API version to use. If omitted, uses version `1`. For details, see [API Versioning](#api-versioning). | | (Method Parameters) | (Various) | Provide any parameters to the method here. | See [Response Formatting](response-formatting.html) for the response from the server. @@ -98,11 +98,15 @@ The commandline always uses the latest [API version](#api-versioning). **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! + ## API Versioning -The `rippled` server uses a single integer to identify the API version to use. The first API version is `1`; currently, this is the only version of the `rippled` API. (There is no API version 0.) [New in: rippled 1.5.0][] +The `rippled` server uses a single integer to identify the API version to use. Currently, there are two API versions: `1` and `2` [New in: rippled 2.0.0][]. The server reports the range of supported API versions in the `version` API method. + +Separate API requests can use different API versions even on the same persistent connection. For example, if you connect 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. + +Future versions of `rippled` that introduce breaking changes will introduce a new API version 3. -Future versions of `rippled` that introduce breaking changes will introduce a new API version number, such as `2`. The server will support a range of API versions, which it reports in the `version` API method. ### Breaking Changes diff --git a/content/references/http-websocket-apis/public-api-methods/account-methods/account_info.md b/content/references/http-websocket-apis/public-api-methods/account-methods/account_info.md index 8ba5ecab6d1..a1a3f356e1a 100644 --- a/content/references/http-websocket-apis/public-api-methods/account-methods/account_info.md +++ b/content/references/http-websocket-apis/public-api-methods/account-methods/account_info.md @@ -63,7 +63,7 @@ The request contains the following parameters: | `ledger_hash` | String | No | A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) | | `ledger_index` | Number or String | No | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) | | `queue` | Boolean | No | If `true`, return stats about [queued transactions](transaction-queue.html) sent by this account. Can only be used when querying for the data from the current open ledger. Not available from servers in [Reporting Mode][]. | -| `signer_lists` | Boolean | No | If `true`, return any [SignerList objects](signerlist.html) associated with this account. | +| `signer_lists` | Boolean | No | [API v1][]: If `true`, return any [SignerList objects](signerlist.html) associated with this account.
[API v2][]: Identical to v1, but also returns an `invalidParams` error if you provide a non-boolean value. | The following fields are deprecated and should not be provided: `ident`, `ledger`, `strict`. @@ -204,7 +204,7 @@ The response follows the [standard format][], with the result containing the req |:-----------------------|:--------|:------------------------------------------| | `account_data` | Object | The [AccountRoot ledger object](accountroot.html) with this account's information, as stored in the ledger. | | `account_flags` | Object | The account's flag statuses (see below), based on the `Flags` field of the account. [New in: rippled 1.11.0][] | -| `signer_lists` | Array | _(Omitted unless the request specified `signer_lists` and at least one SignerList is associated with the account.)_ Array of [SignerList ledger objects](signerlist.html) associated with this account for [Multi-Signing](multi-signing.html). Since an account can own at most one SignerList, this array must have exactly one member if it is present. **Quirk:** In [API version 1](https://github.com/xrplf/rippled/blob/develop/API-CHANGELOG.md#v1-account_info-response), this field is nested under `account_data`. For this method, [Clio](https://github.com/XRPLF/clio) implements the API version 2 behavior where is field is **not** nested under `account_data`. | +| `signer_lists` | Array | [API v1][]: _(Omitted unless the request specified `signer_lists` and at least one SignerList is associated with the account.)_ Array of [SignerList ledger objects](signerlist.html) associated with this account for [Multi-Signing](multi-signing.html). Since an account can own at most one SignerList, this array must have exactly one member if it is present. The field is nested under `account_data`.
[API v2][]: Identical to API v1, but the field is returned in the root response instead. [Clio](https://github.com/XRPLF/clio) implements the API v2 behavior in all cases. | | `ledger_current_index` | Integer | _(Omitted if `ledger_index` is provided instead)_ The [ledger index][] of the current in-progress ledger, which was used when retrieving this information. | | `ledger_index` | Integer | _(Omitted if `ledger_current_index` is provided instead)_ The [ledger index][] of the ledger version used when retrieving this information. The information does not contain any changes from ledger versions newer than this one. | | `queue_data` | Object | _(Omitted unless `queue` specified as `true` and querying the current open ledger.)_ Information about [queued transactions](transaction-cost.html#queued-transactions) sent by this account. This information describes the state of the local `rippled` server, which may be different from other servers in the [peer-to-peer XRP Ledger network](peer-protocol.html). Some fields may be omitted because the values are calculated "lazily" by the queuing mechanism. | diff --git a/content/references/http-websocket-apis/public-api-methods/account-methods/account_tx.md b/content/references/http-websocket-apis/public-api-methods/account-methods/account_tx.md index 7ff5914baf8..28062c844ab 100644 --- a/content/references/http-websocket-apis/public-api-methods/account-methods/account_tx.md +++ b/content/references/http-websocket-apis/public-api-methods/account-methods/account_tx.md @@ -68,18 +68,17 @@ The request includes the following parameters: |:-------------------|:-------------------------------------------|:-----------| | `account` | String | A unique identifier for the account, most commonly the account's address. | | `tx_type` | String | _(Optional)_ **Clio Only** Return only transactions of a specific type, such as "Clawback", "AccountSet", "AccountDelete", et al. Case-insensitive. Supports any transaction type except `AMM*` (See [Transaction Types](transaction-types.html).) [New in: Clio v2.0](https://github.com/XRPLF/clio/releases/tag/2.0.0 "BADGE_BLUE") | -| `ledger_index_min` | Integer | _(Optional)_ Use to specify the earliest ledger to include transactions from. A value of `-1` instructs the server to use the earliest validated ledger version available. | -| `ledger_index_max` | Integer | _(Optional)_ Use to specify the most recent ledger to include transactions from. A value of `-1` instructs the server to use the most recent validated ledger version available. | +| `ledger_index_min` | Integer | [API v1][]: _(Optional)_ Use to specify the earliest ledger to include transactions from. A value of `-1` instructs the server to use the earliest validated ledger version available.
[API v2][]: Identical to v1, but also returns a `lgrIdxMalformed` error if a value is specified beyond the range of ledgers the server has. | +| `ledger_index_max` | Integer | [API v1][]: _(Optional)_ Use to specify the most recent ledger to include transactions from. A value of `-1` instructs the server to use the most recent validated ledger version available.
[API v2][]: Identical to v1, but also returns a `lgrIdxMalformed` error if a value is specified beyond the range of ledgers the server has. | | `ledger_hash` | String | _(Optional)_ Use to look for transactions from a single ledger only. (See [Specifying Ledgers][].) | | `ledger_index` | String or Unsigned Integer | _(Optional)_ Use to look for transactions from a single ledger only. (See [Specifying Ledgers][].) | -| `binary` | Boolean | _(Optional)_ Defaults to `false`. If set to `true`, returns transactions as hex strings instead of JSON. | -| `forward` | Boolean | _(Optional)_ Defaults to `false`. If set to `true`, returns values indexed with the oldest ledger first. Otherwise, the results are indexed with the newest ledger first. (Each page of results may not be internally ordered, but the pages are overall ordered.) | +| `binary` | Boolean | [API v1][]: _(Optional)_ Defaults to `false`. If set to `true`, returns transactions as hex strings instead of JSON.
[API v2][]: Identical to v1, but also returns an `invalidParams` error if you provide a non-boolean value. | +| `forward` | Boolean | [API v1][]: _(Optional)_ Defaults to `false`. If set to `true`, returns values indexed with the oldest ledger first. Otherwise, the results are indexed with the newest ledger first. (Each page of results may not be internally ordered, but the pages are overall ordered.)
[API v2][]: Identical to v1, but also returns an `invalidParams` error if you provide a non-boolean value. | | `limit` | Integer | _(Optional)_ Default varies. Limit the number of transactions to retrieve. The server is not required to honor this value. | | `marker` | [Marker][] | Value from a previous paginated response. Resume retrieving data where that response left off. This value is stable even if there is a change in the server's range of available ledgers. | -**You must use at least one of the following fields** in your request: `ledger_index`, `ledger_hash`, `ledger_index_min`, or `ledger_index_max`. - -The following legacy fields are no longer supported: `offset`, `count`, `ledger_min`, `ledger_max`. [Removed in: rippled 1.7.0][] +- You must use at least one of the following fields in your request: `ledger_index`, `ledger_hash`, `ledger_index_min`, or `ledger_index_max`. +- [API v2]: If you specify either `ledger_index` or `ledger_hash`, including `ledger_index_min` and `ledger_index_max` returns an `invalidParams` error. ### Iterating over queried data diff --git a/content/references/http-websocket-apis/public-api-methods/account-methods/noripple_check.md b/content/references/http-websocket-apis/public-api-methods/account-methods/noripple_check.md index 4db16ca0143..beba491e7e6 100644 --- a/content/references/http-websocket-apis/public-api-methods/account-methods/noripple_check.md +++ b/content/references/http-websocket-apis/public-api-methods/account-methods/noripple_check.md @@ -58,7 +58,7 @@ The request includes the following parameters: |:---------------|:---------------------------|:-------------------------------| | `account` | String | A unique identifier for the account, most commonly the account's address. | | `role` | String | Whether the address refers to a `gateway` or `user`. Recommendations depend on the role of the account. Issuers must have Default Ripple enabled and must disable No Ripple on all trust lines. Users should have Default Ripple disabled, and should enable No Ripple on all trust lines. | -| `transactions` | Boolean | _(Optional)_ If `true`, include an array of suggested [transactions](transaction-formats.html), as JSON objects, that you can sign and submit to fix the problems. Defaults to false. | +| `transactions` | Boolean | [API v1][]: _(Optional)_ If `true`, include an array of suggested [transactions](transaction-formats.html), as JSON objects, that you can sign and submit to fix the problems. The default is `false`.
[API v2][]: Identical to v1, but also returns an `invalidParams` error if you use a non-boolean value. | | `limit` | Unsigned Integer | _(Optional)_ The maximum number of trust line problems to include in the results. Defaults to 300. | | `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) | | `ledger_index` | String or Unsigned Integer | _(Optional)_ The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) | diff --git a/content/references/http-websocket-apis/public-api-methods/transaction-methods/tx_history.md b/content/references/http-websocket-apis/public-api-methods/transaction-methods/tx_history.md index f23245eecf5..3d7b774d915 100644 --- a/content/references/http-websocket-apis/public-api-methods/transaction-methods/tx_history.md +++ b/content/references/http-websocket-apis/public-api-methods/transaction-methods/tx_history.md @@ -8,7 +8,7 @@ blurb: Retrieve info about all recent transactions. The `tx_history` method retrieves some of the most recent transactions made. -**Caution:** This method is deprecated, and may be removed without further notice. +**Caution:** This method is removed in [API v2][]. ## Request Format An example of the request format: diff --git a/content/references/protocol/transactions/types/payment.md b/content/references/protocol/transactions/types/payment.md index 6155052fadc..4c0bcd61354 100644 --- a/content/references/protocol/transactions/types/payment.md +++ b/content/references/protocol/transactions/types/payment.md @@ -41,13 +41,15 @@ Payments are also the only way to [create accounts](#creating-accounts). | Field | JSON Type | [Internal Type][] | Description | |:-----------------|:---------------------|:------------------|:---------------| -| `Amount` | [Currency Amount][] | Amount | The amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the [`tfPartialPayment` flag](#payment-flags) is set, deliver _up to_ this amount instead. | +| `Amount` | [Currency Amount][] | Amount | [API v1][]: Only available in API v1. The maximum amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the [`tfPartialPayment` flag](#payment-flags) is set, deliver _up to_ this amount instead. | +| `DeliverMax` | [Currency Amount][] | Amount | [API v2][]: Only available in API v2. The maximum amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the [`tfPartialPayment` flag](#payment-flags) is set, deliver _up to_ this amount instead. [New in: rippled 2.0.0][] | +| `DeliverMin` | [Currency Amount][] | Amount | _(Optional)_ Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](partial-payments.html). For non-XRP amounts, the nested field names are lower-case. | | `Destination` | String | AccountID | The unique address of the account receiving the payment. | | `DestinationTag` | Number | UInt32 | _(Optional)_ Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay. | | `InvoiceID` | String | Hash256 | _(Optional)_ Arbitrary 256-bit hash representing a specific reason or identifier for this payment. | | `Paths` | Array of path arrays | PathSet | (Optional, auto-fillable) Array of [payment paths](paths.html) to be used for this transaction. Must be omitted for XRP-to-XRP transactions. | | `SendMax` | [Currency Amount][] | Amount | _(Optional)_ Highest amount of source currency this transaction is allowed to cost, including [transfer fees](transfer-fees.html), exchange rates, and [slippage](http://en.wikipedia.org/wiki/Slippage_%28finance%29). Does not include the [XRP destroyed as a cost for submitting the transaction](transaction-cost.html). For non-XRP amounts, the nested field names MUST be lower-case. Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments. | -| `DeliverMin` | [Currency Amount][] | Amount | _(Optional)_ Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](partial-payments.html). For non-XRP amounts, the nested field names are lower-case. | + ## Types of Payments