add better docs to readme
This commit is contained in:
parent
7ea86f6506
commit
0c70a4636a
58
README.md
58
README.md
|
@ -4,7 +4,57 @@
|
|||
|
||||
HTTP RPC server supporting calls via uri params, jsonrpc, and jsonrpc over websockets
|
||||
|
||||
# How To
|
||||
# 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":["my_world", 5]
|
||||
}
|
||||
```
|
||||
|
||||
Note the `params` does not currently support key-value pairs (#1), so order matters (you can get the order from making a
|
||||
GET request to `/`)
|
||||
|
||||
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:
|
||||
|
||||
|
@ -41,7 +91,7 @@ rpcserver.RegisterRPCFuncs(mux, Routes)
|
|||
wm := rpcserver.NewWebsocketManager(Routes, nil)
|
||||
mux.HandleFunc("/websocket", wm.WebsocketHandler)
|
||||
go func() {
|
||||
_, err := rpcserver.StartHTTPServer("0.0.0.0:46657", mux)
|
||||
_, err := rpcserver.StartHTTPServer("0.0.0.0:8008", mux)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
@ -49,9 +99,9 @@ go func() {
|
|||
|
||||
```
|
||||
|
||||
Note that unix sockets are supported as well (eg. `/path/to/socket` instead of `0.0.0.0:46657`)
|
||||
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:46657`.
|
||||
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
|
||||
|
||||
|
||||
|
|
Loading…
Reference in New Issue