Massive README improvements

README.md

@@ -13,15 +13,17 @@ Starting Graphene
     make
     ./programs/witness_node/witness_node
 
-This will launch the witness node. If you would like to launch the command-line wallet, you must first specify a port for communication with the witness node. To do this, add text to `witness_node_data_dir/config.json` as follows, then restart the node:
+This will launch the witness node. If you would like to launch the command-line wallet, you must first specify a port for communication with the witness node. To do this, add text to `witness_node_data_dir/config.ini` as follows, then restart the node:
 
-    "websocket_endpoint": "127.0.0.1:8090"
+    rpc-endpoint = 127.0.0.1:8090
 
 Then, in a separate terminal window, start the command-line wallet `cli_wallet`:
 
     ./programs/cli_wallet/cli_wallet
 
-If you send private keys over this connection, `websocket_endpoint` should be bound to localhost for security.
+If you send private keys over this connection, `rpc-endpoint` should be bound to localhost for security.
+
+A list of CLI wallet commands is available [here](https://bitshares.github.io/doxygen/classgraphene_1_1wallet_1_1wallet__api.html).
 
 Code coverage testing
 ---------------------
@@ -31,7 +33,8 @@ TODO:  Write something here
 Unit testing
 ------------
 
-TODO:  Write something here
+We use the Boost unit test framework for unit testing.  Most unit
+tests reside in the `chain_test` build target.
 
 Core mechanics
 --------------
@@ -94,15 +97,65 @@ Debugging FC exceptions with GDB
 
 - `catch throw`
 
+Using the API
+-------------
+
+We provide several different API's.  Each API has its own ID.
+When running `witness_node`, initially two API's are available:
+API 0 provides read-only access to the database, while API 1 is
+used to login and gain access to additional, restricted API's.
+
+Here is an example using `wscat` package from `npm` for websockets:
+
+    $ npm install -g wscat
+    $ wscat -c ws://127.0.0.1:8090
+    > {"id":1, "method":"call", "params":[0,"get_accounts",[["1.3.0"]]]}
+    < {"id":1,"result":[{"id":"1.3.0","annotations":[],"registrar":"1.3.0","referrer":"1.3.0","referrer_percent":0,"name":"genesis","owner":{"weight_threshold":1,"auths":[["1.2.0",1]]},"active":{"weight_threshold":1,"auths":[["1.2.0",1]]},"memo_key":"1.2.0","voting_account":"1.3.0","num_witness":0,"num_committee":0,"votes":[],"statistics":"2.7.0","whitelisting_accounts":[],"blacklisting_accounts":[]}]}
+    $
+
+We can do the same thing using an HTTP client such as `curl` for API's which do not require login or other session state:
+
+    $ curl --data '{"jsonrpc": "2.0", "method": "call", "params": [0, "get_accounts", [["1.3.0"]]], "id": 1}' http://127.0.0.1:8090/rpc
+    {"id":1,"result":[{"id":"1.3.0","annotations":[],"registrar":"1.3.0","referrer":"1.3.0","referrer_percent":0,"name":"genesis","owner":{"weight_threshold":1,"auths":[["1.2.0",1]]},"active":{"weight_threshold":1,"auths":[["1.2.0",1]]},"memo_key":"1.2.0","voting_account":"1.3.0","num_witness":0,"num_committee":0,"votes":[],"statistics":"2.7.0","whitelisting_accounts":[],"blacklisting_accounts":[]}]}    
+
+API 0 is accessible using regular JSON-RPC:
+
+    $ curl --data '{"jsonrpc": "2.0", "method": "get_accounts", "params": [["1.3.0"]], "id": 1}' http://127.0.0.1:8090/rpc
+
+You can use the login API to obtain `network`, `database` and `history` API's.  Here is an example of how to call `add_node` from the `network` API:
+
+    {"id":1, "method":"call", "params":[1,"login",["bytemaster", "supersecret"]]}
+    {"id":2, "method":"call", "params":[1,"network",[]]}
+    {"id":3, "method":"call", "params":[2,"add_node",["127.0.0.1:9090"]]}
+
+Note, the call to `network` is necessary to obtain the correct API identifier for the network API.  It is not guaranteed that the network API identifier will always be `2`.
+
+Since the `network` API requires login, it is only accessible over the websocket RPC.  Our `doxygen` documentation contains the most up-to-date information
+about API's for the [witness node](https://bitshares.github.io/doxygen/namespacegraphene_1_1app.html) and the
+[wallet](https://bitshares.github.io/doxygen/classgraphene_1_1wallet_1_1wallet__api.html).
+If you want information which is not available from an API, it might be available
+from the [database](https://bitshares.github.io/doxygen/classgraphene_1_1chain_1_1database.html);
+it is fairly simple to write API methods to expose database methods.
+
 Questions
----------------
+---------
 
 - Is there a way to generate help with parameter names and method descriptions?
 
     Yes. Documentation of the code base, including APIs, can be generated using Doxygen. Simply run `doxygen` in this directory.
+    We are thinking of integrating Doxygen's XML output format to provide a better `help` command to the CLI wallet.
 
 - Is there a way to allow external program to drive `cli_wallet` via websocket, JSONRPC, or HTTP?
 
     Yes. External programs may connect to the CLI wallet and make its calls over a websockets API. To do this, run the wallet in
     server mode, i.e. `cli_wallet -s "127.0.0.1:9999"` and then have the external program connect to it over the specified port
     (in this example, port 9999).
+
+- Is there a way to access methods which require login over HTTP?
+
+    No.  Login is inherently a stateful process (logging in changes what the server will do for certain requests, that's kind
+    of the point of having it).  If you need to track state across HTTP RPC calls, you must maintain a session across multiple
+    connections.  This is a famous source of security vulnerabilities for HTTP applications.  Additionally, HTTP is not really
+    designed for "server push" notifications, and we would have to figure out a way to queue notifications for a polling client.
+
+    Websockets solves all these problems.  If you need to access Graphene's stateful methods, you need to use Websockets.