website: k/v getting started

website/source/intro/getting-started/kv.html.markdown

@@ -9,20 +9,18 @@ sidebar_current: "gettingstarted-kv"
 In addition to providing service discovery and integrated health checking,
 Consul provides an easy to use Key/Value store. This can be used to hold
 dynamic configuration, assist in service coordination, build leader election,
-and any thing else a developer can think to build. The [HTTP API](/docs/agent/http.html) fully
+and anything else a developer can think to build. The
-documents the features of the K/V store.
+[HTTP API](/docs/agent/http.html) fully documents the features of the K/V store.
+
+This page assumes you have at least one Consul agent already running.
 
 ## Simple Usage
 
 To demonstrate how simple it is to get started, we will manipulate a few keys
-in the K/V store. We get started by first starting an agent in server mode:
+in the K/V store.
 
-```
+Querying the agent we started in a prior page, we can first verify that
-$ ./bin/consul agent -server -bootstrap -data-dir /tmp/consul
+there are no existing keys in the k/v store:
-...
-```
-
-Now, we can verify that our K/V store contains no keys:
 
 ```
 $ curl -v http://localhost:8500/v1/kv/?recurse
@@ -43,7 +41,8 @@ $ curl -v http://localhost:8500/v1/kv/?recurse
 * Closing connection #0
 ```
 
-Since there are no keys, we get a 404 response back. Now, we can put a few example keys:
+Since there are no keys, we get a 404 response back.
+Now, we can put a few example keys:
 
 ```
 $ curl -X PUT -d 'test' http://localhost:8500/v1/kv/web/key1
@@ -58,21 +57,24 @@ $ curl http://localhost:8500/v1/kv/?recurse
  {"CreateIndex":99,"ModifyIndex":99,"Key":"web/sub/key3","Flags":0,"Value":"dGVzdA=="}]
 ```
 
-Here we have created 3 keys, each with the value of "test". Note that the `Value` field
+Here we have created 3 keys, each with the value of "test". Note that the
-returned is base64 encoded to encode non UTF8 characters. For the "web/key2" key, we set
+`Value` field returned is base64 encoded to encode allow for non-UTF8
-a `flag` value of 42. All keys support setting a 64bit integer flag value. This is opaque
+characters. For the "web/key2" key, we set a `flag` value of 42. All keys
-to Consul but can be used by clients.
+support setting a 64bit integer flag value. This is opaque to Consul but can
+be used by clients for any purpose.
+
+After setting the values, we then issued a GET request to retrieve multiple
+keys using the `?recurse` parameter.
 
-Above we retrieved multiple keys using the "?recurse" query parameter, but fetching
+You can also fetch a single key just as easily:
-a single key is done by providing the path alone:
 
 ```
 $ curl http://localhost:8500/v1/kv/web/key1
 [{"CreateIndex":97,"ModifyIndex":97,"Key":"web/key1","Flags":0,"Value":"dGVzdA=="}]
 ```
 
-Deleting keys is simple as well. We can delete a single key by specifying the full
+Deleting keys is simple as well. We can delete a single key by specifying the
-path, or we can recursively delete all keys under a root using "?recurse":
+full path, or we can recursively delete all keys under a root using "?recurse":
 
 ```
 $ curl -X DELETE http://localhost:8500/v1/kv/web/sub?recurse
@@ -81,9 +83,11 @@ $ curl http://localhost:8500/v1/kv/web?recurse
  {"CreateIndex":98,"ModifyIndex":98,"Key":"web/key2","Flags":42,"Value":"dGVzdA=="}]
 ```
 
-A key can be updated by setting a new value. Additionally, Consul provides a Check-And-Set
+A key can be updated by setting a new value by issuing the same PUT request.
-operation, that enables an atomic key update. This is done by providing the "?cas=" parameter
+Additionally, Consul provides a Check-And-Set operation, enabling atomic
-with the last `ModifyIndex` value. For example, suppose we wanted to update "web/key1":
+key updates. This is done by providing the `?cas=` paramter with the last
+`ModifyIndex` value from the GET request. For example, suppose we wanted
+to update "web/key1":
 
 ```
 $ curl -X PUT -d 'newval' http://localhost:8500/v1/kv/web/key1?cas=97