mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-28 23:55:49 +00:00
Reporting Mode: API changes
This commit is contained in:
mDuo13
@@ -68,17 +68,30 @@ Some types of hash appear in API requests and responses. Others are only calcula
|
||||
Many API methods require you to specify an instance of the ledger, with the data retrieved being considered up-to-date as of that particular version of the shared ledger. The commands that accept a ledger version all work the same way. There are three ways you can specify which ledger you want to use:
|
||||
|
||||
1. Specify a ledger by its [Ledger Index][] in the `ledger_index` parameter. Each closed ledger has a ledger index that is 1 higher than the previous ledger. (The very first ledger had ledger index 1.)
|
||||
|
||||
"ledger_index": 61546724
|
||||
|
||||
2. Specify a ledger by its [Hash][] value in the `ledger_hash` parameter.
|
||||
|
||||
"ledger_hash": "8BB204CE37CFA7A021A16B5F6143400831C4D1779E6FE538D9AC561ABBF4A929"
|
||||
|
||||
3. Specify a ledger by one of the following shortcuts, in the `ledger_index` parameter:
|
||||
* `validated` for the most recent ledger that has been validated by the whole network
|
||||
|
||||
* `validated` for the most recent ledger that has been [validated by consensus](consensus.html#validation)
|
||||
|
||||
"ledger_index": "validated"
|
||||
|
||||
* `closed` for the most recent ledger that has been closed for modifications and proposed for validation
|
||||
|
||||
* `current` for the server's current working version of the ledger.
|
||||
|
||||
There is also a deprecated `ledger` parameter which accepts any of the above three formats. *Do not* use this parameter; it may be removed without further notice.
|
||||
|
||||
If you do not specify a ledger, the `current` (in-progress) ledger is chosen by default. If you provide more than one field specifying ledgers, the deprecated `ledger` field is used first if it exists, falling back to `ledger_hash`. The `ledger_index` field is ignored unless neither of the other two are present.
|
||||
If you do not specify a ledger, the server decides which ledger to use to serve the request. By default, the server chooses the `current` (in-progress) ledger. In [Reporting Mode](rippled-server-modes.html#reporting-mode), the server uses the most recent validated ledger instead. Do not provide more than one field specifying ledgers, the server may choose any of them to . The `ledger_index` field is ignored unless neither of the other two are present.
|
||||
|
||||
**Note:** Do not rely on this default behavior for specifying a ledger; it is subject to change. Always specify a ledger version in the request if you can.
|
||||
**Note:** Do not rely on the default behavior for specifying a ledger; it is subject to change. Always specify a ledger version in the request if you can.
|
||||
|
||||
If you make a request to a Reporting Mode server for a ledger that has not been validated, the server forwards the request to a network mode server, because Reporting Mode does not record ledger data until it has been validated.
|
||||
|
||||
|
||||
## Specifying Currency Amounts
|
||||
|
||||
@@ -101,15 +101,16 @@ For other errors that returned with HTTP status code 200 OK, the responses are f
|
||||
|
||||
All methods can potentially return any of the following values for the `error` code:
|
||||
|
||||
* `amendmentBlocked` - The server is [amendment blocked](amendments.html#amendment-blocked) and needs to be updated to the latest version to stay synced with the XRP Ledger network.
|
||||
- `amendmentBlocked` - The server is [amendment blocked](amendments.html#amendment-blocked) and needs to be updated to the latest version to stay synced with the XRP Ledger network.
|
||||
- `failedToForward` - ([Reporting Mode][] servers only) The server tried to forward this request to a Network Mode server, but the connection failed.
|
||||
- `invalid_API_version` - The server does not support the [API version number](request-formatting.html#api-versioning) from the request.
|
||||
* `jsonInvalid` - (WebSocket only) The request is not a proper JSON object.
|
||||
* JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
|
||||
* `missingCommand` - (WebSocket only) The request did not specify a `command` field.
|
||||
* JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
|
||||
* `noClosed` - The server does not have a closed ledger, typically because it has not finished starting up.
|
||||
* `noCurrent` - The server does not know what the current ledger is, due to high load, network problems, validator failures, incorrect configuration, or some other problem.
|
||||
* `noNetwork` - The server is having trouble connecting to the rest of the XRP Ledger peer-to-peer network (and is not running in stand-alone mode).
|
||||
* `tooBusy` - The server is under too much load to do this command right now. Generally not returned if you are connected as an admin.
|
||||
* `unknownCmd` - The request does not contain a [command](rippled-api.html) that the `rippled` server recognizes.
|
||||
* `wsTextRequired` - (WebSocket only) The request's [opcode](https://tools.ietf.org/html/rfc6455#section-5.2) is not text. <!-- SPELLING_IGNORE: opcode -->
|
||||
- `jsonInvalid` - (WebSocket only) The request is not a proper JSON object.
|
||||
- JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
|
||||
- `missingCommand` - (WebSocket only) The request did not specify a `command` field.
|
||||
- JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
|
||||
- `noClosed` - The server does not have a closed ledger, typically because it has not finished starting up.
|
||||
- `noCurrent` - The server does not know what the current ledger is, due to high load, network problems, validator failures, incorrect configuration, or some other problem.
|
||||
- `noNetwork` - The server is having trouble connecting to the rest of the XRP Ledger peer-to-peer network (and is not running in stand-alone mode).
|
||||
- `tooBusy` - The server is under too much load to do this command right now. Generally not returned if you are connected as an admin.
|
||||
- `unknownCmd` - The request does not contain a [command](rippled-api.html) that the `rippled` server recognizes.
|
||||
- `wsTextRequired` - (WebSocket only) The request's [opcode](https://tools.ietf.org/html/rfc6455#section-5.2) is not text. <!-- SPELLING_IGNORE: opcode -->
|
||||
|
||||
@@ -13,6 +13,7 @@ The fields of a successful response include:
|
||||
| `result` | Object | The result of the query; contents vary depending on the command. |
|
||||
| `warning` | String | _(May be omitted)_ If this field is provided, the value is the string `load`. This means the client is approaching the [rate limiting](rate-limiting.html) threshold where the server will disconnect this client. |
|
||||
| `warnings` | Array | _(May be omitted)_ If this field is provided, it contains one or more **Warnings Objects** with important warnings. For details, see [API Warnings](#api-warnings). [New in: rippled 1.5.0][] |
|
||||
| `forwarded` | Boolean | _(May be omitted)_ If `true`, this request has been forwarded from a [Reporting Mode][] server to a Network Mode server because the request requires data that is not available in Reporting Mode. The default is `false`. |
|
||||
|
||||
|
||||
## Example Successful Response
|
||||
@@ -151,6 +152,27 @@ This warning indicates that the server is [amendment blocked](amendments.html#am
|
||||
|
||||
The server administrator must [upgrade `rippled`](install-rippled.html) to a version that supports the activated amendments.
|
||||
|
||||
### 1003. This is a reporting server
|
||||
[New in: rippled 1.7.0][]
|
||||
|
||||
Example warning:
|
||||
|
||||
```json
|
||||
"warnings" : [
|
||||
{
|
||||
"id" : 1003,
|
||||
"message" : "This is a reporting server. The default behavior of a reporting server is to only return validated data. If you are looking for not yet validated data, include \"ledger_index : current\" in your request, which will cause this server to forward the request to a p2p node. If the forward is successful the response will include \"forwarded\" : \"true\""
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
This warning indicates that the server answering the request is running [Reporting Mode][]. Certain API methods are not available or behave differently because Reporting Mode does not connect to the peer-to-peer network and does not track ledger data that has not yet been validated.
|
||||
|
||||
It is generally safe to ignore this warning.
|
||||
|
||||
**Caution:** If you request ledger data without explicitly [specifying a ledger version][Specifying Ledgers], Reporting Mode uses the latest validated ledger by default instead of the current in-progress ledger.
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
|
||||
Reference in New Issue
Block a user