Add the first 3 endpoints to mdbook docs (#41)

* add the first 3 endpoints to mdbook docs

* use localhost, not internal fly dns hostname

* consistent slashes

doc/SUMMARY.md

@@ -17,10 +17,10 @@
 - [Templates]()
 
 # Reference
-- [API]()
-    - [POST /v1/exec]()
-    - [POST /v1/query]()
-    - [POST /v1/subscriptions]()
+- [API](api/README.md)
+    - [POST /v1/transactions](api/transactions.md)
+    - [POST /v1/queries](api/queries.md)
+    - [POST /v1/subscriptions](api/subscriptions.md)
 - [Command-line Interface](cli/README.md)
     - [agent]()
     - [backup](cli/backup.md)

doc/api/README.md

@@ -0,0 +1,7 @@
+## API
+
+Each running Corrosion agent hosts a RESTful HTTP API for interacting with the cluster's synchronized database. Endpoints accept SQL statements in a JSON body, for versatility.
+
+- [POST /v1/transactions](transactions.md) for writes
+- [POST /v1/queries](queries.md) for reads
+- [POST /v1/subscriptions](subscriptions.md) to receive streaming updates for a desired query

doc/api/queries.md

@@ -0,0 +1,20 @@
+## POST /v1/queries
+
+Read from the Corrosion database. The `/v1/queries` endpoint accepts a single SQL statement in JSON format.
+
+### Sample request
+```
+curl http://localhost:8080/v1/queries \ 
+ -H "content-type: application/json" \
+ -d "\"SELECT sandwich FROM sandwiches\""
+```
+
+### Sample response
+```json
+{"columns":["sandwich"]}
+{"row":[1,["burger"]]}
+{"row":[2,["ham"]]}
+{"row":[3,["grilled cheese"]]}
+{"row":[4,["brie and cranberry"]]}
+{"eoq":{"time":5e-8}}
+```

doc/api/subscriptions.md

@@ -0,0 +1,28 @@
+# POST /v1/subscriptions
+
+Start receiving updates for a desired SQL query. The `/v1/subscriptions` endpoint accepts a single SQL statement in JSON format.
+The Corrosion agent responds with an HTML stream that notifies of any changes to the response to this query.
+
+### Sample request
+```
+curl http://localhost:8080/v1/subscriptions \
+ -H "content-type: application/json" \
+ -d "\"SELECT sandwich FROM sw\""
+```
+
+### Sample response
+
+```json
+{"columns":["sandwich"]}
+{"row":[1,["shiitake"]]}
+{"row":[2,["ham"]]}
+{"row":[3,["grilled cheese"]]}
+{"row":[4,["brie and cranberry"]]}
+{"eoq":{"time":8e-8}}
+{"change":["update",2,["smoked meat"]]}
+{"change":["update",1,["smoked meat"]]}
+{"change":["update",2,["ham"]]}
+{"change":["update",1,["burger"]]}
+{"change":["update",2,["smoked meat"]]}
+...
+```

doc/api/transactions.md

@@ -0,0 +1,15 @@
+## POST /v1/transactions
+
+Write changes to the Corrosion database for propagation through the cluster. The `/v1/transactions` endpoint accepts a JSON list of SQL statements.
+
+### Sample request
+```
+curl http://localhost:8080/v1/transactions \
+ -H "content-type: application/json" \
+ -d "[\"INSERT OR IGNORE INTO sandwiches (pk, sandwich) VALUES (3, 'brie and cranberry')\"]"
+```
+
+### Sample response
+```json
+{"results":[{"rows_affected":1,"time":0.000027208}],"time":0.000300708}% 
+```