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
@@ -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