mirrors/tendermint
1
0
Fork 0
mirror of https://github.com/tendermint/tendermint.git synced 2026-05-22 15:11:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

rpc: move docs from doc.go to swagger.yaml (#5044)

Browse Source 
also,

- add an example for WS
- mention that a subscription could be terminated in /subscribe

Closes #5014
This commit is contained in:
Anton Kaliaev
2020-06-25 09:53:18 +04:00
committed by GitHub
parent 8830176567
commit 7a1ee66763
2 changed files with 54 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
rpc/core/doc.go
View File

@@ -1,75 +1,8 @@
/*
# Introduction
Package core defines the Tendermint RPC endpoints.
Tendermint supports the following RPC protocols:
* URI over HTTP
* JSONRPC over HTTP
* JSONRPC over websockets
Tendermint RPC is built using our own RPC library which contains its own set of documentation and tests.
See it here: https://github.com/tendermint/tendermint/tree/master/rpc/lib
## Configuration
RPC can be configured by tuning parameters under `[rpc]` table in the `$TMHOME/config/config.toml` file
or by using the `--rpc.X` command-line flags.
Default rpc listen address is `tcp://0.0.0.0:26657`.
To set another address, set the `laddr` config parameter to desired value.
CORS (Cross-Origin Resource Sharing) can be enabled by setting
`cors_allowed_origins`, `cors_allowed_methods`, `cors_allowed_headers` config parameters.
## Arguments
Arguments which expect strings or byte arrays may be passed as quoted strings,
like `"abc"` or as `0x`-prefixed strings, like `0x616263`.
## URI/HTTP
```bash
curl 'localhost:26657/broadcast_tx_sync?tx="abc"'
```
> Response:
```json
{
"error": "",
"result": {
"hash": "2B8EC32BA2579B3B8606E42C06DE2F7AFA2556EF",
"log": "",
"data": "",
"code": "0"
},
"id": "",
"jsonrpc": "2.0"
}
```
## JSONRPC/HTTP
JSONRPC requests can be POST'd to the root RPC endpoint via HTTP (e.g. `http://localhost:26657/`).
```json
{
"method": "broadcast_tx_sync",
"jsonrpc": "2.0",
"params": [ "abc" ],
"id": "dontcare"
}
```
## JSONRPC/websockets
JSONRPC requests can be made via websocket.
The websocket endpoint is at `/websocket`, e.g. `localhost:26657/websocket`.
Asynchronous RPC functions like event `subscribe` and `unsubscribe` are only available via websockets.
## More Examples
See the various bash tests using curl in `test/`, and examples using the `Go` API in `rpc/client/`.
Tendermint ships with its own JSONRPC library -
https://github.com/tendermint/tendermint/tree/master/rpc/jsonrpc.
## Get the list
@@ -111,7 +44,5 @@ Endpoints that require arguments:
/unsafe_write_heap_profile?filename=_
/unsubscribe?event=_
```
# Endpoints
*/
package core

53
rpc/swagger/swagger.yaml
View File

@@ -1,7 +1,53 @@
openapi: 3.0.0
info:
title: RPC client for Tendermint
description: A REST interface for state queries, transaction generation and broadcasting.
title: Tendermint RPC
description: |
Tendermint supports the following RPC protocols:
* URI over HTTP
* JSONRPC over HTTP
* JSONRPC over websockets
## Configuration
RPC can be configured by tuning parameters under `[rpc]` table in the
`$TMHOME/config/config.toml` file or by using the `--rpc.X` command-line
flags.
Default rpc listen address is `tcp://0.0.0.0:26657`.
To set another address, set the `laddr` config parameter to desired value.
CORS (Cross-Origin Resource Sharing) can be enabled by setting
`cors_allowed_origins`, `cors_allowed_methods`, `cors_allowed_headers`
config parameters.
## Arguments
Arguments which expect strings or byte arrays may be passed as quoted
strings, like `"abc"` or as `0x`-prefixed strings, like `0x616263`.
## URI/HTTP
A REST like interface.
curl localhost:26657/block?height=5
## JSONRPC/HTTP
JSONRPC requests can be POST'd to the root RPC endpoint via HTTP.
curl --header "Content-Type: application/json" --request POST --data '{"method": "block", "params": ["5"], "id": 1}' localhost:26657
## JSONRPC/websockets
JSONRPC requests can be also made via websocket.
The websocket endpoint is at `/websocket`, e.g. `localhost:26657/websocket`.
Asynchronous RPC functions like event `subscribe` and `unsubscribe` are
only available via websockets.
Example using https://github.com/hashrocket/ws:
ws ws://localhost:26657/websocket
> { "jsonrpc": "2.0", "method": "subscribe", "params": ["tm.event='NewBlock'"], "id": 1 }
version: "Master"
license:
name: Apache 2.0
@@ -309,6 +355,9 @@ paths:
}
}()
```
NOTE: if you're not reading events fast enough, Tendermint might
terminate the subscription.
parameters:
- in: query
name: query