From 273f13fb41aef594e20d9f3d5388fb0283425897 Mon Sep 17 00:00:00 2001
From: Jeff Mitchell <jeffrey.mitchell@gmail.com>
Date: Mon, 21 Sep 2015 11:22:48 -0400
Subject: [PATCH] Add API endpoint documentation to generic

---
 .../source/docs/secrets/generic/index.html.md | 102 ++++++++++++++++--
 1 file changed, 93 insertions(+), 9 deletions(-)

diff --git a/website/source/docs/secrets/generic/index.html.md b/website/source/docs/secrets/generic/index.html.md
index 704d27fd1..9669e2597 100644
--- a/website/source/docs/secrets/generic/index.html.md
+++ b/website/source/docs/secrets/generic/index.html.md
@@ -13,10 +13,11 @@ Name: `generic`
 The generic secret backend is used to store arbitrary secrets within
 the configured physical storage for Vault. If you followed along with
 the getting started guide, you interacted with a generic secret backend
-via the `secret/` prefix that Vault mounts by default.
+via the `secret/` prefix that Vault mounts by default. You can mount as many
+of these backends at different mount points as you like.
 
-Writing to a key in the `secret/` backend will replace the old value,
-the sub-fields are not merged together.
+Writing to a key in the `secret/` backend will replace the old value;
+sub-fields are not merged together.
 
 ## Quick Start
 
@@ -42,17 +43,100 @@ $ vault write secret/foo zip=zap ttl=1h
 Success! Data written to: secret/foo
 ```
 
-This writes the key with the "zip" field set to "zap" and a one hour lease. We can test
-this by doing a read:
+This writes the key with the "zip" field set to "zap" and a one hour TTL.
+We can test this by doing a read:
 
 ```
 $ vault read secret/foo
 Key           	Value
-lease_id      	secret/foo/e4514713-d5d9-fb14-4177-97a7f7f64518
-lease_duration	3600
+ttl_seconds	3600
 ttl		1h
 zip           	zap
 ```
 
-As expected, we get the value previously set back as well as our custom TTL.
-The lease_duration has been set to 3600 seconds (one hour) as specified.
+As expected, we get the value previously set back as well as our custom TTL
+both as specified and translated to seconds. The TTL has been set to 3600
+seconds (one hour) as specified.
+
+## API
+
+### /secret
+#### GET
+
+<dl class="api">
+  <dt>Description</dt>
+  <dd>
+    Retrieves the secret at the specified location.
+  </dd>
+
+  <dt>Method</dt>
+  <dd>GET</dd>
+
+  <dt>URL</dt>
+  <dd>`/secret/<path>`</dd>
+
+  <dt>Parameters</dt>
+  <dd>
+     None
+  </dd>
+
+  <dt>Returns</dt>
+  <dd>
+
+  ```javascript
+  {
+      "auth": null,
+      "data": {
+          "foo": "bar"
+      },
+      "lease_duration": 2592000,
+      "lease_id": "",
+      "renewable": false
+  }
+  ```
+  
+  </dd>
+</dl>
+
+#### POST/PUT
+
+<dl class="api">
+  <dt>Description</dt>
+  <dd>
+    Stores a secret at the specified location.
+  </dd>
+
+  <dt>Method</dt>
+  <dd>POST/PUT</dd>
+
+  <dt>URL</dt>
+  <dd>`/secret/<path>`</dd>
+
+  <dt>Parameters</dt>
+  <dd>
+    <ul>
+      <li>
+        <span class="param">(key)</span>
+        <span class="param-flags">optional</span>
+        A key, paired with an associated value, to be held at the
+        given location. Multiple key/value pairs can be specified,
+        and all will be returned on a read operation.
+      </li>
+      <li>
+        <span class="param">ttl</span>
+        <span class="param-flags">optional</span>
+        The Time To Live for the entry. This value, converted to
+        seconds, is round-tripped on read operations as the
+        `lease_duration` parameter. Vault takes no action when this
+        value expires; it is only meant as a way for a writer of
+        a value to indicate to readers how often they should check
+        for new entries.
+      </li>
+    </ul>
+  </dd>
+
+  <dt>Returns</dt>
+  <dd>
+  A `204` response code.
+  </dd>
+</dl>