mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-21 04:05:49 +00:00
API versioning info
- Adds the new api_version field and related info to 'Request Formatting'. - Restructures request formatting to use parameter tables. - Removes some redundant sections from 'Get Started with the rippled API' and links relevant references instead (this partially addresses issue 584 but does not fix it) - Fixes a typo in 'Admin Access' section and clarifies it - Adds the new API version universal error and sorts the universal errors alphabetically.
This commit is contained in:
mDuo13
@@ -11,7 +11,7 @@ Some example errors:
|
||||
|
||||
*WebSocket*
|
||||
|
||||
```
|
||||
```json
|
||||
{
|
||||
"id": 3,
|
||||
"status": "error",
|
||||
@@ -29,8 +29,9 @@ Some example errors:
|
||||
|
||||
*JSON-RPC*
|
||||
|
||||
```
|
||||
```json
|
||||
HTTP Status: 200 OK
|
||||
|
||||
{
|
||||
"result": {
|
||||
"error": "ledgerIndexMalformed",
|
||||
@@ -47,7 +48,7 @@ HTTP Status: 200 OK
|
||||
|
||||
*Commandline*
|
||||
|
||||
```
|
||||
```json
|
||||
{
|
||||
"result": {
|
||||
"error": "ledgerIndexMalformed",
|
||||
@@ -73,7 +74,8 @@ HTTP Status: 200 OK
|
||||
| `status` | String | `"error"` if the request caused an error |
|
||||
| `type` | String | Typically `"response"`, which indicates a successful response to a command. |
|
||||
| `error` | String | A unique code for the type of error that occurred |
|
||||
| `request` | Object | A copy of the request that prompted this error, in JSON format. **Caution:** If the request contained any account secrets, they are copied here! |
|
||||
| `request` | Object | A copy of the request that prompted this error, in JSON format. **Caution:** If the request contained any secrets, they are copied here! |
|
||||
| `api_version` | Number | _(May be omitted)_ The `api_version` specified in the request, if any. |
|
||||
|
||||
|
||||
## JSON-RPC Format
|
||||
@@ -99,14 +101,15 @@ 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:
|
||||
|
||||
* `unknownCmd` - The request does not contain a [command](rippled-api.html) that the `rippled` server recognizes.
|
||||
* `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.
|
||||
- `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.
|
||||
* `tooBusy` - The server is under too much load to do this command right now. Generally not returned if you are connected as an admin.
|
||||
* `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).
|
||||
* `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.
|
||||
* `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.
|
||||
* `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.
|
||||
|
||||
@@ -1,14 +1,62 @@
|
||||
# Request Formatting
|
||||
|
||||
## Example Request
|
||||
|
||||
<!-- MULTICODE_BLOCK_START -->
|
||||
|
||||
*WebSocket*
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 2,
|
||||
"command": "account_info",
|
||||
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
|
||||
"strict": true,
|
||||
"ledger_index": "validated",
|
||||
"api_version": 1
|
||||
}
|
||||
```
|
||||
|
||||
*JSON-RPC*
|
||||
|
||||
```json
|
||||
POST http://s1.ripple.com:51234/
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"method": "account_info",
|
||||
"params": [
|
||||
{
|
||||
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
|
||||
"strict": true,
|
||||
"ledger_index": "validated",
|
||||
"api_version": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
*Commandline*
|
||||
|
||||
```sh
|
||||
rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated strict
|
||||
```
|
||||
|
||||
<!-- MULTICODE_BLOCK_END -->
|
||||
|
||||
|
||||
## WebSocket Format
|
||||
|
||||
After you open a WebSocket to the `rippled` server, you can send commands as a [JSON](https://en.wikipedia.org/wiki/JSON) object, with the following attributes:
|
||||
After you open a WebSocket to the `rippled` server, you can send commands as a [JSON](https://en.wikipedia.org/wiki/JSON) object with the following fields:
|
||||
|
||||
* Put command name in top-level `"command"` field
|
||||
* All the relevant parameters for the command are also in the top level
|
||||
* Optionally include an `"id"` field with an arbitrary value. 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.
|
||||
| Field | Type | Description |
|
||||
|:--------------------|:----------|:-------------------------------------------|
|
||||
| `command` | String | The name of the [API method](public-rippled-methods.html). |
|
||||
| `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, use version 1. For details, see [API Versioning](#api-versioning). [New in: rippled 1.5.0][] |
|
||||
| (Method Parameters) | (Various) | Provide any parameters to the method at the top level. |
|
||||
|
||||
The response comes as a JSON object.
|
||||
See [Response Formatting](response-formatting.html) for the response from the server.
|
||||
|
||||
## JSON-RPC Format
|
||||
|
||||
@@ -18,53 +66,63 @@ Always include a `Content-Type` header with the value `application/json`.
|
||||
|
||||
If you plan on making multiple requests, use [Keep-Alives](http://tools.ietf.org/html/rfc7230#section-6.3) so that you do not have to close and re-open the connection in between requests.
|
||||
|
||||
Send request body as a [JSON](https://en.wikipedia.org/wiki/JSON) object with the following attributes:
|
||||
Send request body as a [JSON](https://en.wikipedia.org/wiki/JSON) object with the following fields:
|
||||
|
||||
* Put the command in the top-level `"method"` field
|
||||
* Include a top-level `"params"` field. The contents of this field should be **a one-item array** containing only a nested JSON object with all the parameters for the command.
|
||||
|
||||
The response is also a JSON object.
|
||||
| Field | Type | Description |
|
||||
|:--------------------|:----------|:-------------------------------------------|
|
||||
| `method` | String | The name of the [API method](public-rippled-methods.html). |
|
||||
| `params` | Array | _(Optional)_ A **one-item array** containing a nested JSON object with the parameters to this method. You may omit this field if the method does not require any parameters. |
|
||||
|
||||
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][] |
|
||||
| (Method Parameters) | (Various) | Provide any parameters to the method here. |
|
||||
|
||||
See [Response Formatting](response-formatting.html) for the response from the server.
|
||||
|
||||
## Commandline Format
|
||||
|
||||
The commandline puts the command after any normal (dash-prefaced) commandline options, followed by a limited set of parameters, separated by spaces. For any parameter values that might contain spaces or other unusual characters, use single-quotes to encapsulate them.
|
||||
Put the API method name after any normal (dash-prefaced) commandline options, followed by a limited set of parameters, separated by spaces. For any parameter values that might contain spaces or other unusual characters, use single-quotes to encapsulate them. Not all methods have commandline API syntax. For more information, see [Commandline Usage](https://xrpl.org/commandline-usage.html#client-mode-options).
|
||||
|
||||
### Example Request
|
||||
The commandline calls JSON-RPC, so its responses always match the JSON-RPC [response format](response-formatting.html).
|
||||
|
||||
<!-- MULTICODE_BLOCK_START -->
|
||||
The commandline always uses the latest [API version](#api-versioning).
|
||||
|
||||
*WebSocket*
|
||||
**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!
|
||||
|
||||
```
|
||||
{
|
||||
"id": 2,
|
||||
"command": "account_info",
|
||||
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
|
||||
"strict": true,
|
||||
"ledger_index": "validated"
|
||||
}
|
||||
```
|
||||
## API Versioning
|
||||
|
||||
*JSON-RPC*
|
||||
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][]
|
||||
|
||||
```
|
||||
POST http://s1.ripple.com:51234/
|
||||
{
|
||||
"method": "account_info",
|
||||
"params": [
|
||||
{
|
||||
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
|
||||
"strict": true,
|
||||
"ledger_index": "validated"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
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. <!-- TODO: add a link when `version` method is documented. -->
|
||||
|
||||
*Commandline*
|
||||
### Breaking Changes
|
||||
|
||||
```
|
||||
rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated true
|
||||
```
|
||||
The following types of changes are **breaking changes**:
|
||||
|
||||
<!-- MULTICODE_BLOCK_END -->
|
||||
- Removing or renaming a field of a request or response.
|
||||
- Changing the type of a field of a request or response.
|
||||
- Changing the meaning of a field of a request or a response.
|
||||
- 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.
|
||||
|
||||
### Non-Breaking Changes
|
||||
|
||||
The following types of changes are **non-breaking changes** and may occur without a change of API version number:
|
||||
|
||||
- Adding a new field to a request or response, not including positional parameters.
|
||||
- Adding a new API method.
|
||||
|
||||
@@ -24,192 +24,70 @@ These public servers are not for sustained or business use, and they may become
|
||||
|
||||
## Admin Access
|
||||
|
||||
To use a `rippled` server's [Admin Methods](admin-rippled-methods.html). In this case, you should use whatever IP and port you configured the server to bind. (For example, `127.0.0.1:54321`) Additionally, to access admin functionality, you must connect from a port/IP address marked as admin in the config file.
|
||||
`rippled` API methods are divided into [Public Methods](public-rippled-methods.html) and [Admin Methods](admin-rippled-methods.html) so that organizations can offer public servers for the benefit of the community. To access admin methods, or admin functionality of public methods, you must connect to the API on a **port and IP address marked as admin** in the server's config file.
|
||||
|
||||
The [example config file](https://github.com/ripple/rippled/blob/8429dd67e60ba360da591bfa905b58a35638fda1/cfg/rippled-example.cfg#L1050-L1073) listens for connections on the local loopback network (127.0.0.1), with JSON-RPC (HTTP) on port 5005 and WebSocket (WS) on port 6006, and treats all connected clients as admin.
|
||||
The [example config file](https://github.com/ripple/rippled/blob/f00f263852c472938bf8e993e26c7f96f435935c/cfg/rippled-example.cfg#L1154-L1179) listens for connections on the local loopback network (127.0.0.1), with JSON-RPC (HTTP) on port 5005 and WebSocket (WS) on port 6006, and treats all connected clients as admin.
|
||||
|
||||
|
||||
## WebSocket API
|
||||
|
||||
If you are looking to try out some methods on the XRP Ledger, you can skip writing your own WebSocket code and go straight to using the API at the [Ripple WebSocket API Tool](websocket-api-tool.html). Later on, when you want to connect to your own `rippled` server, you can [build your own client in the browser](monitor-incoming-payments-with-websocket.html) or [in Node.js](https://www.npmjs.com/package/ws).
|
||||
|
||||
### Request Formatting
|
||||
Example WebSocket API request:
|
||||
|
||||
After you open a WebSocket to the `rippled` server, you can send commands as a [JSON](https://en.wikipedia.org/wiki/JSON) object, with the following attributes:
|
||||
```json
|
||||
{
|
||||
"id": "my_first_request",
|
||||
"command": "server_info",
|
||||
"api_version": 1
|
||||
}
|
||||
```
|
||||
|
||||
* Put command name in top-level `"command"` field
|
||||
* All the relevant parameters for the command are also in the top level
|
||||
* Optionally include an `"id"` field with an arbitrary value. 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.
|
||||
|
||||
The response comes as a JSON object.
|
||||
The response to [this command][server_info method] shows you the current status of the server. Or, read more about [Request Formatting](request-formatting.html) and [Response Formatting](response-formatting.html).
|
||||
|
||||
## JSON-RPC
|
||||
|
||||
You can use any HTTP client (like [RESTED for Firefox](https://addons.mozilla.org/en-US/firefox/addon/rested/), [Postman for Chrome](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en) or [Online HTTP client ExtendsClass](https://extendsclass.com/rest-client-online.html)) to make JSON-RPC calls a `rippled` server. Most programming languages have a library for making HTTP requests built in.
|
||||
|
||||
### Request Formatting
|
||||
Example JSON-RPC request:
|
||||
|
||||
To make a JSON-RPC request, send an HTTP **POST** request to the root path (`/`) on the port and IP where the `rippled` server is listening for JSON-RPC connections. You can use HTTP/1.0 or HTTP/1.1. If you use HTTPS, you should use TLS v1.2. For security reasons, `rippled` _does not support_ SSL v3 or earlier.
|
||||
|
||||
Always include a `Content-Type` header with the value `application/json`.
|
||||
|
||||
If you plan on making multiple requests, use [Keep-Alives](http://tools.ietf.org/html/rfc7230#section-6.3) so that you do not have to close and re-open the connection in between requests.
|
||||
|
||||
Send request body as a [JSON](https://en.wikipedia.org/wiki/JSON) object with the following attributes:
|
||||
|
||||
* Put the command in the top-level `"method"` field
|
||||
* Include a top-level `"params"` field. The contents of this field should be **a one-item array** containing only a nested JSON object with all the parameters for the command.
|
||||
|
||||
The response is also a JSON object.
|
||||
|
||||
|
||||
## Commandline
|
||||
|
||||
The commandline interface connects to the same service as the JSON-RPC one, so the public servers and server configuration are the same. As a commandline client, `rippled` connects to the local instance. For example:
|
||||
|
||||
```
|
||||
rippled --conf=/etc/rippled.cfg server_info
|
||||
```
|
||||
|
||||
**Note:** The commandline interface is intended for administrative purposes only and is _not a supported API_.
|
||||
|
||||
|
||||
### Request Formatting
|
||||
|
||||
The commandline puts the command after any normal (dash-prefaced) commandline options, followed by a limited set of parameters, separated by spaces. For any parameter values that might contain spaces or other unusual characters, use single-quotes to encapsulate them.
|
||||
|
||||
|
||||
## Example Request
|
||||
|
||||
<!-- MULTICODE_BLOCK_START -->
|
||||
|
||||
*WebSocket*
|
||||
|
||||
```
|
||||
{
|
||||
"id": 2,
|
||||
"command": "account_info",
|
||||
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
|
||||
"strict": true,
|
||||
"ledger_index": "validated"
|
||||
}
|
||||
```
|
||||
|
||||
*JSON-RPC*
|
||||
|
||||
```
|
||||
```json
|
||||
POST http://s1.ripple.com:51234/
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"method": "account_info",
|
||||
"method": "server_info",
|
||||
"params": [
|
||||
{
|
||||
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
|
||||
"strict": true,
|
||||
"ledger_index": "validated"
|
||||
"api_version": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
*Commandline*
|
||||
The response to this command shows you the current status of the server. For more information, see the [server_info method][].
|
||||
|
||||
## Commandline
|
||||
|
||||
The commandline interface connects to the same service as the JSON-RPC one, so the public servers and server configuration are the same. By default, the commandline connects to a `rippled` server running on the same machine.
|
||||
|
||||
Example commandline request:
|
||||
|
||||
```
|
||||
rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated true
|
||||
rippled --conf=/etc/opt/ripple/rippled.cfg server_info
|
||||
```
|
||||
|
||||
<!-- MULTICODE_BLOCK_END -->
|
||||
For more information on `rippled`'s commandline usage, see [Commandline Usage Reference](https://xrpl.org/commandline-usage.html).
|
||||
|
||||
**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!
|
||||
|
||||
## Response Formatting
|
||||
## Available Methods
|
||||
|
||||
### Example Successful Response
|
||||
For a full list of API methods, see:
|
||||
|
||||
<!-- MULTICODE_BLOCK_START -->
|
||||
- [Public `rippled` Methods](public-rippled-methods.html): Methods available on public servers, including looking up data from the ledger and submitting transactions.
|
||||
- [Admin `rippled` Methods](admin-rippled-methods.html): Methods for [managing](manage-the-rippled-server.html) the `rippled` server.
|
||||
|
||||
*WebSocket*
|
||||
|
||||
```
|
||||
{
|
||||
"id": 2,
|
||||
"status": "success",
|
||||
"type": "response",
|
||||
"result": {
|
||||
"account_data": {
|
||||
"Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
|
||||
"Balance": "27389517749",
|
||||
"Flags": 0,
|
||||
"LedgerEntryType": "AccountRoot",
|
||||
"OwnerCount": 18,
|
||||
"PreviousTxnID": "B6B410172C0B65575D89E464AF5B99937CC568822929ABF87DA75CBD11911932",
|
||||
"PreviousTxnLgrSeq": 6592159,
|
||||
"Sequence": 1400,
|
||||
"index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05"
|
||||
},
|
||||
"ledger_index": 6760970
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
*JSON-RPC*
|
||||
|
||||
```
|
||||
HTTP Status: 200 OK
|
||||
{
|
||||
"result": {
|
||||
"account_data": {
|
||||
"Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
|
||||
"Balance": "27389517749",
|
||||
"Flags": 0,
|
||||
"LedgerEntryType": "AccountRoot",
|
||||
"OwnerCount": 18,
|
||||
"PreviousTxnID": "B6B410172C0B65575D89E464AF5B99937CC568822929ABF87DA75CBD11911932",
|
||||
"PreviousTxnLgrSeq": 6592159,
|
||||
"Sequence": 1400,
|
||||
"index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05"
|
||||
},
|
||||
"ledger_index": 6761012,
|
||||
"status": "success"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
*Commandline*
|
||||
|
||||
```
|
||||
{
|
||||
"result": {
|
||||
"account_data": {
|
||||
"Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
|
||||
"Balance": "27389517749",
|
||||
"Flags": 0,
|
||||
"LedgerEntryType": "AccountRoot",
|
||||
"OwnerCount": 18,
|
||||
"PreviousTxnID": "B6B410172C0B65575D89E464AF5B99937CC568822929ABF87DA75CBD11911932",
|
||||
"PreviousTxnLgrSeq": 6592159,
|
||||
"Sequence": 1400,
|
||||
"index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05"
|
||||
},
|
||||
"ledger_index": 6761012,
|
||||
"status": "success"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<!-- MULTICODE_BLOCK_END -->
|
||||
|
||||
The fields of a successful response include:
|
||||
|
||||
| `Field` | Type | Description |
|
||||
|:----------------|:---------|:------------------------------------------------|
|
||||
| `id` | (Varies) | (WebSocket only) ID provided in the request that prompted this response |
|
||||
| `status` | String | (WebSocket only) The value `success` indicates the request was successfully received and understood by the server. |
|
||||
| `result.status` | String | (JSON-RPC and Commandline) The value `success` indicates the request was successfully received and understood by the server. |
|
||||
| `type` | String | (WebSocket only) The value `response` indicates a successful response to a command. [Asynchronous notifications](subscribe.html) use a different value such as `ledgerClosed` or `transaction`. |
|
||||
| `result` | Object | The result of the query; contents vary depending on the command. |
|
||||
|
||||
### Commandline
|
||||
|
||||
The response format for commandline methods is the same as JSON-RPC responses, because they use the same interface.
|
||||
|
||||
## See Also
|
||||
|
||||
|
||||
Reference in New Issue
Block a user