Website: cleanup for intro/getting-started/kv.html.

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

@@ -3,7 +3,7 @@ layout: "intro"
 page_title: "Key/Value Data"
 sidebar_current: "gettingstarted-kv"
 description: |-
-  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 anything else a developer can think to build.
+  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 enable anything else a developer can think to build.
 ---
 
 # Key/Value Data
@@ -11,18 +11,17 @@ description: |-
 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 anything else a developer can think to build. The
-[HTTP API](/docs/agent/http.html) fully documents the features of the K/V store.
+and enable anything else a developer can think to build.
 
-This page assumes you have at least one Consul agent already running.
+This step 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.
 
-Querying the agent we started in a prior page, we can first verify that
-there are no existing keys in the k/v store:
+Querying the local agent we started in the [Run the Agent step](agent.html),
+we can first verify that there are no existing keys in the k/v store:
 
 ```text
 $ curl -v http://localhost:8500/v1/kv/?recurse
@@ -43,8 +42,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
@@ -60,12 +59,12 @@ $ curl http://localhost:8500/v1/kv/?recurse
 ```
 
 Here we have created 3 keys, each with the value of "test". Note that the
-`Value` field returned is base64 encoded to allow non-UTF8
-characters. For the "web/key2" key, we set a `flag` value of 42. All keys
-support setting a 64-bit integer flag value. This is opaque to Consul but can
-be used by clients for any purpose.
+`Value` field returned is base64 encoded to allow non-UTF8 characters. For the
+key "web/key2", we set a `flag` value of 42. All keys support setting a 64-bit
+integer flag value. This is not used internally by Consul, but it can be used by
+clients to add meaningful metadata to any KV.
 
-After setting the values, we then issued a GET request to retrieve multiple
+After setting the values, we then issued a `GET` request to retrieve multiple
 keys using the `?recurse` parameter.
 
 You can also fetch a single key just as easily:
@@ -75,8 +74,9 @@ $ 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 path, or we can recursively delete all keys under a root using "?recurse":
+Deleting keys is simple as well, accomplished by using the `DELETE` verb. We can
+delete a single key by specifying the full path, or we can recursively delete all
+keys under a root using "?recurse":
 
 ```text
 $ curl -X DELETE http://localhost:8500/v1/kv/web/sub?recurse
@@ -85,11 +85,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 by issuing the same PUT request.
-Additionally, Consul provides a Check-And-Set operation, enabling atomic
-key updates. This is done by providing the `?cas=` parameter with the last
-`ModifyIndex` value from the GET request. For example, suppose we wanted
-to update "web/key1":
+A key can be modified by issuing a `PUT` request to the same URI and
+providing a different message body. Additionally, Consul provides a
+Check-And-Set operation, enabling atomic key updates. This is done by
+providing the `?cas=` parameter with the last `ModifyIndex` value from
+the GET request. For example, suppose we wanted to update "web/key1":
 
 ```text
 $ curl -X PUT -d 'newval' http://localhost:8500/v1/kv/web/key1?cas=97
@@ -98,7 +98,7 @@ $ curl -X PUT -d 'newval' http://localhost:8500/v1/kv/web/key1?cas=97
 false
 ```
 
-In this case, the first CAS update succeeds because the last modify time is 97.
+In this case, the first CAS update succeeds because the `ModifyIndex` is 97.
 However the second operation fails because the `ModifyIndex` is no longer 97.
 
 We can also make use of the `ModifyIndex` to wait for a key's value to change.
@@ -109,11 +109,15 @@ $ curl "http://localhost:8500/v1/kv/web/key2?index=101&wait=5s"
 [{"CreateIndex":98,"ModifyIndex":101,"Key":"web/key2","Flags":42,"Value":"dGVzdA=="}]
 ```
 
-By providing "?index=" we are asking to wait until the key has a `ModifyIndex` greater
+By providing "?index=", we are asking to wait until the key has a `ModifyIndex` greater
 than 101. However the "?wait=5s" parameter restricts the query to at most 5 seconds,
 returning the current, unchanged value. This can be used to efficiently wait for
 key modifications. Additionally, this same technique can be used to wait for a list
 of keys, waiting only until any of the keys has a newer modification time.
 
-These are only a few examples of what the API supports. For full
-documentation, please see the [HTTP API](/docs/agent/http.html).
+## Next Steps
+
+These are only a few examples of what the API supports. For full documentation, please
+see [the /kv/ route of the HTTP API](/docs/agent/http/kv.html).
+
+Next, we will look at the [web UI](ui.html) options supported by Consul.