github.com/adoriasoft/tendermint@v0.34.0-dev1.0.20200722151356-96d84601a75a/rpc/jsonrpc/doc.go (about)

     1  // HTTP RPC server supporting calls via uri params, jsonrpc over HTTP, and jsonrpc over
     2  // websockets
     3  //
     4  // Client Requests
     5  //
     6  // Suppose we want to expose the rpc function `HelloWorld(name string, num int)`.
     7  //
     8  // GET (URI)
     9  //
    10  // As a GET request, it would have URI encoded parameters, and look like:
    11  //
    12  //   curl 'http://localhost:8008/hello_world?name="my_world"&num=5'
    13  //
    14  // Note the `'` around the url, which is just so bash doesn't ignore the quotes in `"my_world"`.
    15  // This should also work:
    16  //
    17  //   curl http://localhost:8008/hello_world?name=\"my_world\"&num=5
    18  //
    19  // A GET request to `/` returns a list of available endpoints.
    20  // For those which take arguments, the arguments will be listed in order, with `_` where the actual value should be.
    21  //
    22  // POST (JSONRPC)
    23  //
    24  // As a POST request, we use JSONRPC. For instance, the same request would have this as the body:
    25  //
    26  //   {
    27  //     "jsonrpc": "2.0",
    28  //     "id": "anything",
    29  //     "method": "hello_world",
    30  //     "params": {
    31  //       "name": "my_world",
    32  //       "num": 5
    33  //     }
    34  //   }
    35  //
    36  // With the above saved in file `data.json`, we can make the request with
    37  //
    38  //   curl --data @data.json http://localhost:8008
    39  //
    40  //
    41  // WebSocket (JSONRPC)
    42  //
    43  // All requests are exposed over websocket in the same form as the POST JSONRPC.
    44  // Websocket connections are available at their own endpoint, typically `/websocket`,
    45  // though this is configurable when starting the server.
    46  //
    47  // Server Definition
    48  //
    49  // Define some types and routes:
    50  //
    51  //    type ResultStatus struct {
    52  //    	    Value string
    53  //    }
    54  //
    55  // Define some routes
    56  //
    57  //   var Routes = map[string]*rpcserver.RPCFunc{
    58  //	    "status": rpcserver.NewRPCFunc(Status, "arg"),
    59  //   }
    60  //
    61  // An rpc function:
    62  //
    63  //   func Status(v string) (*ResultStatus, error) {
    64  //	    return &ResultStatus{v}, nil
    65  //   }
    66  //
    67  // Now start the server:
    68  //
    69  //   mux := http.NewServeMux()
    70  //   rpcserver.RegisterRPCFuncs(mux, Routes)
    71  //   wm := rpcserver.NewWebsocketManager(Routes)
    72  //   mux.HandleFunc("/websocket", wm.WebsocketHandler)
    73  //   logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout))
    74  //   listener, err := rpc.Listen("0.0.0.0:8080", rpcserver.Config{})
    75  //   if err != nil { panic(err) }
    76  //   go rpcserver.Serve(listener, mux, logger)
    77  //
    78  // Note that unix sockets are supported as well (eg. `/path/to/socket` instead of `0.0.0.0:8008`)
    79  // Now see all available endpoints by sending a GET request to `0.0.0.0:8008`.
    80  // Each route is available as a GET request, as a JSONRPCv2 POST request, and via JSONRPCv2 over websockets.
    81  //
    82  // Examples
    83  //
    84  // - [Tendermint](https://github.com/tendermint/tendermint/blob/master/rpc/core/routes.go)
    85  package jsonrpc