ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-21 12:15:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

API versioning info

Browse Source 
- 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
2020-03-31 14:35:54 -07:00
parent d7cc46657c
commit 195a901e9a
3 changed files with 142 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
content/references/rippled-api/api-conventions/error-formatting.md
View File

@@ -11,7 +11,7 @@ Some example errors:
*WebSocket* *WebSocket*
``` ```json
{ {
"id": 3, "id": 3,
"status": "error", "status": "error",
@@ -29,8 +29,9 @@ Some example errors:
*JSON-RPC* *JSON-RPC*
``` ```json
HTTP Status: 200 OK HTTP Status: 200 OK
{ {
"result": { "result": {
"error": "ledgerIndexMalformed", "error": "ledgerIndexMalformed",
@@ -47,7 +48,7 @@ HTTP Status: 200 OK
*Commandline* *Commandline*
``` ```json
{ {
"result": { "result": {
"error": "ledgerIndexMalformed", "error": "ledgerIndexMalformed",
@@ -73,7 +74,8 @@ HTTP Status: 200 OK
| `status` | String | `"error"` if the request caused an error | | `status` | String | `"error"` if the request caused an error |
| `type` | String | Typically `"response"`, which indicates a successful response to a command. | | `type` | String | Typically `"response"`, which indicates a successful response to a command. |
| `error` | String | A unique code for the type of error that occurred | | `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 ## 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: 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. * `jsonInvalid` - (WebSocket only) The request is not a proper JSON object.
* JSON-RPC returns a 400 Bad Request HTTP error in this case instead. * JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
* `missingCommand` - (WebSocket only) The request did not specify a `command` field. * `missingCommand` - (WebSocket only) The request did not specify a `command` field.
* JSON-RPC returns a 400 Bad Request HTTP error in this case instead. * 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. * `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. * `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.

140
content/references/rippled-api/api-conventions/request-formatting.md
View File

@@ -1,14 +1,62 @@
# Request Formatting # 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 ## 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 | Field | Type | Description |
* 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. | `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 ## 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. 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 ## 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!
``` ## API Versioning
{
"id": 2,
"command": "account_info",
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"strict": true,
"ledger_index": "validated"
}
```
*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][]
``` 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. -->
POST http://s1.ripple.com:51234/
{
"method": "account_info",
"params": [
{
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"strict": true,
"ledger_index": "validated"
}
]
}
```
*Commandline* ### Breaking Changes
``` The following types of changes are **breaking changes**:
rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated true
```
<!-- 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.

184
content/tutorials/get-started/get-started-with-the-rippled-api.md
View File

@@ -24,192 +24,70 @@ These public servers are not for sustained or business use, and they may become
## Admin Access ## 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 ## 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). 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 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).
* 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.
## JSON-RPC ## 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. 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. ```json
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*
```
POST http://s1.ripple.com:51234/ POST http://s1.ripple.com:51234/
Content-Type: application/json
{ {
"method": "account_info", "method": "server_info",
"params": [ "params": [
{ {
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", "api_version": 1
"strict": true,
"ledger_index": "validated"
} }
] ]
} }
``` ```
*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 ## See Also