Merge pull request #401 from philips/add-dir-docs

feat(README): add notes about in-order key creation

README.md

@@ -272,6 +272,52 @@ curl -L http://127.0.0.1:4001/v2/keys/foo?wait=true\&waitIndex=7
 The watch command returns immediately with the same response as previous.
 
 
+### Atomically Creating In-Order Keys
+
+Using the `POST` on a directory you can create keys with key names that are created in-order.
+This can be used in a variety of useful patterns like implementing queues of keys that need to be processed in strict order.
+An example use case is the [locking module][lockmod] which uses it to ensure clients get fair access to a mutex.
+
+Creating an in-order key is easy
+
+```sh
+curl -X POST http://127.0.0.1:4001/v2/keys/queue -d value=Job1
+```
+
+```json
+{
+    "action": "create",
+    "node": {
+        "createdIndex": 6,
+        "key": "/queue/6",
+        "modifiedIndex": 6,
+        "value": "Job1"
+    }
+}
+```
+
+If you create another entry some time later it is guaranteed to have a key name that is greater than the previous key.
+Also note the key names use the global etcd index so the next key can be more than `previous + 1`.
+
+```sh
+curl -X POST http://127.0.0.1:4001/v2/keys/queue -d value=Job2
+```
+
+```json
+{
+    "action": "create",
+    "node": {
+        "createdIndex": 29,
+        "key": "/queue/29",
+        "modifiedIndex": 29,
+        "value": "Job2"
+    }
+}
+```
+
+[lockmod]: #lock
+
+
 ### Using a directory TTL
 
 Like keys, directories in etcd can be set to expire after a specified number of seconds.
@@ -401,6 +447,27 @@ The response should be
 
 We successfully changed the value from "one" to "two" since we gave the correct previous value.
 
+### Creating Directories
+
+In most cases directories for a key are automatically created.
+But, there are cases where you will want to create a directory or remove one.
+
+Creating a directory is just like a key only you cannot provide a value and must add the `dir=true` parameter.
+
+```sh
+curl -L http://127.0.0.1:4001/v2/keys/dir -XPUT -d dir=true
+```
+```json
+{
+    "action": "set",
+    "node": {
+        "createdIndex": 30,
+        "dir": true,
+        "key": "/dir",
+        "modifiedIndex": 30
+    }
+}
+```
 
 ### Listing a directory
 
@@ -488,14 +555,31 @@ curl -L http://127.0.0.1:4001/v2/keys/?recursive=true
 ```
 
 
-### Deleting a directory
+### Deleting a Directory
 
 Now let's try to delete the directory `/foo_dir`.
 
-To delete a directory, we must add `recursive=true`.
+You can remove an empty directory using the `DELETE` verb and the `dir=true` parameter.
 
 ```sh
-curl -L http://127.0.0.1:4001/v2/keys/foo_dir?recursive=true -XDELETE
+curl -L -X DELETE 'http://127.0.0.1:4001/v2/keys/dir?dir=true'
+```
+```json
+{
+    "action": "delete",
+    "node": {
+        "createdIndex": 30,
+        "dir": true,
+        "key": "/dir",
+        "modifiedIndex": 31
+    }
+}
+```
+
+To delete a directory that holds keys, you must add `recursive=true`.
+
+```sh
+curl -L http://127.0.0.1:4001/v2/keys/dir?recursive=true -XDELETE
 ```
 
 ```json
@@ -504,7 +588,7 @@ curl -L http://127.0.0.1:4001/v2/keys/foo_dir?recursive=true -XDELETE
     "node": {
         "createdIndex": 10,
         "dir": true,
-        "key": "/foo_dir",
+        "key": "/dir",
         "modifiedIndex": 11
     }
 }