From 0c70a4636acc77ffcfdcccc5e6e57305bd7183a2 Mon Sep 17 00:00:00 2001
From: Ethan Buchman <ethan@coinculture.info>
Date: Thu, 23 Jun 2016 20:33:04 -0400
Subject: [PATCH] add better docs to readme

---
 README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 54 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index f6e725c2..a6882310 100644
--- a/README.md
+++ b/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