From e54ed22740188820e735fdc002ba0eb69f342b97 Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Mon, 4 Nov 2024 15:31:09 -0800 Subject: [PATCH] add default api versioning --- docs/references/http-websocket-apis/index.md | 21 ++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/references/http-websocket-apis/index.md b/docs/references/http-websocket-apis/index.md index b47b12c241..6a354c100b 100644 --- a/docs/references/http-websocket-apis/index.md +++ b/docs/references/http-websocket-apis/index.md @@ -6,11 +6,11 @@ metadata: --- # HTTP / WebSocket APIs -You can communicate directly with the XRP Ledger by `rippled` servers through the publicly available APIs. +You can communicate with the XRP Ledger through the `rippled` servers' publicly available APIs. Currently, there are two API versions: `1` and `2` {% badge href="https://github.com/XRPLF/rippled/releases/tag/2.0.0" %}New in: rippled 2.0.0{% /badge %}. 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. +Separate API requests can use different API versions even on the same persistent connection. For example, if you connect through 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. @@ -43,6 +43,23 @@ The following types of changes are **non-breaking changes** and may occur withou - Adding a new field to a request or response, not including positional parameters. - Adding a new API method. + +## Default API Versions + +The table below shows which version of the `rippled` API is used if you don't specify it in the request: + +| Request Format | API Version | Additional Notes | +|----------------|-------------|------------------| +| Websocket | 1 | | +| JSON-RPC | 1 | | +| Commandline | 2 | The commandline only uses the latest API version (currently 2). | +| [xrpl.js](https://github.com/XRPLF/xrpl.js) | 2 | Defaults to [API v2][] starting in v4.0.0. | +| [xrpl-py](https://github.com/XRPLF/xrpl-py) | 2 | Defaults to [API v2][] starting in v3.0.0. | + +{% admonition type="info" name="Note" %} +[API v2][] is used by default when you make a request to a Clio server, starting in v???. +{% /admonition %} + {% raw-partial file="/docs/_snippets/common-links.md" /%} {% child-pages /%}