Documentation ¶
Overview ¶
HTTP RPC server supporting calls via uri params, jsonrpc, and jsonrpc over websockets
Client Requests ¶
Suppose we want to expose the rpc function `HelloWorld(name string, num int)`.
## GET (URI)
As a GET request, it would have URI encoded parameters, and look like:
``` curl 'http://localhost:8008/hello_world?name="my_world"&num=5' ```
Note the `'` around the url, which is just so bash doesn't ignore the quotes in `"my_world"`. This should also work:
``` curl http://localhost:8008/hello_world?name=\"my_world\"&num=5 ```
A GET request to `/` returns a list of available endpoints. For those which take arguments, the arguments will be listed in order, with `_` where the actual value should be.
## POST (JSONRPC)
As a POST request, we use JSONRPC. For instance, the same request would have this as the body:
```
{ "jsonrpc": "2.0", "id": "anything", "method": "hello_world", "params": { "name": "my_world", "num": 5 } }
```
With the above saved in file `data.json`, we can make the request with ¶
``` curl --data @data.json http://localhost:8008 ```
## WebSocket (JSONRPC)
All requests are exposed over websocket in the same form as the POST JSONRPC. Websocket connections are available at their own endpoint, typically `/websocket`, though this is configurable when starting the server.
Server Definition ¶
Define some types and routes:
```
type ResultStatus struct { Value string }
// Define some routes
var Routes = map[string]*rpcserver.RPCFunc{ "status": rpcserver.NewRPCFunc(Status, "arg"), }
// an rpc function
func Status(v string) (*ResultStatus, error) { return &ResultStatus{v}, nil }
```
Now start the server:
``` mux := http.NewServeMux() rpcserver.RegisterRPCFuncs(mux, Routes) wm := rpcserver.NewWebsocketManager(Routes) mux.HandleFunc("/websocket", wm.WebsocketHandler) logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout))
go func() { _, err := rpcserver.StartHTTPServer("0.0.0.0:8008", mux, logger) if err != nil { panic(err) } }()
```
Note that unix sockets are supported as well (eg. `/path/to/socket` instead of `0.0.0.0:8008`)
Now see all available endpoints by sending a GET request to `0.0.0.0:8008`. Each route is available as a GET request, as a JSONRPCv2 POST request, and via JSONRPCv2 over websockets.
Examples ¶
* [Tendermint](https://github.com/tendermint/tendermint/blob/master/rpc/core/routes.go) * [tm-monitor](https://github.com/tendermint/tools/blob/master/tm-monitor/rpc.go)
Index ¶
Constants ¶
const Fix = "0"
const Maj = "0"
const Min = "7"
const Version = Maj + "." + Min + "." + Fix
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
This section is empty.