From 8f2bb251578a6419265dd6f3ff03d8fe3336be2a Mon Sep 17 00:00:00 2001
From: Ryan Uber <ru@ryanuber.com>
Date: Fri, 30 Oct 2015 14:38:51 -0700
Subject: [PATCH] website: clean up HTTP docs, add blocking queries

---
 website/source/docs/http/alloc.html.md  |   6 +-
 website/source/docs/http/allocs.html.md |   6 +-
 website/source/docs/http/eval.html.md   |  18 ++-
 website/source/docs/http/evals.html.md  |   6 +-
 website/source/docs/http/index.html.md  |   1 +
 website/source/docs/http/job.html.md    | 161 ++++++++++++------------
 website/source/docs/http/jobs.html.md   |   6 +-
 website/source/docs/http/node.html.md   |  20 +--
 website/source/docs/http/nodes.html.md  |   7 +-
 9 files changed, 132 insertions(+), 99 deletions(-)

diff --git a/website/source/docs/http/alloc.html.md b/website/source/docs/http/alloc.html.md
index 3c224fd5401..822858a8c42 100644
--- a/website/source/docs/http/alloc.html.md
+++ b/website/source/docs/http/alloc.html.md
@@ -31,6 +31,11 @@ be specified using the `?region=` query parameter.
     None
   </dd>
 
+  <dt>Blocking Queries</dt>
+  <dd>
+    [Supported](/docs/http/index.html#blocking-queries)
+  </dd>
+
   <dt>Returns</dt>
   <dd>
 
@@ -179,4 +184,3 @@ be specified using the `?region=` query parameter.
 
   </dd>
 </dl>
-
diff --git a/website/source/docs/http/allocs.html.md b/website/source/docs/http/allocs.html.md
index 44ad8aa7ef2..b59a4f2043b 100644
--- a/website/source/docs/http/allocs.html.md
+++ b/website/source/docs/http/allocs.html.md
@@ -31,6 +31,11 @@ be specified using the `?region=` query parameter.
     None
   </dd>
 
+  <dt>Blocking Queries</dt>
+  <dd>
+    [Supported](/docs/http/index.html#blocking-queries)
+  </dd>
+
   <dt>Returns</dt>
   <dd>
 
@@ -56,4 +61,3 @@ be specified using the `?region=` query parameter.
 
   </dd>
 </dl>
-
diff --git a/website/source/docs/http/eval.html.md b/website/source/docs/http/eval.html.md
index cba43900c07..87e048209de 100644
--- a/website/source/docs/http/eval.html.md
+++ b/website/source/docs/http/eval.html.md
@@ -3,7 +3,7 @@ layout: "http"
 page_title: "HTTP API: /v1/evaluation"
 sidebar_current: "docs-http-eval-"
 description: |-
-  The '/1/evaluation' endpoint is used to query a specific evaluation.
+  The '/v1/evaluation' endpoint is used to query a specific evaluation.
 ---
 
 # /v1/evaluation
@@ -17,7 +17,7 @@ be specified using the `?region=` query parameter.
 <dl>
   <dt>Description</dt>
   <dd>
-    Lists all the evaluations.
+    Query a specific evaluation.
   </dd>
 
   <dt>Method</dt>
@@ -31,6 +31,11 @@ be specified using the `?region=` query parameter.
     None
   </dd>
 
+  <dt>Blocking Queries</dt>
+  <dd>
+    [Supported](/docs/http/index.html#blocking-queries)
+  </dd>
+
   <dt>Returns</dt>
   <dd>
 
@@ -57,9 +62,6 @@ be specified using the `?region=` query parameter.
   </dd>
 </dl>
 
-# /v1/evaluation/\<ID\>/allocations
-## GET
-
 <dl>
   <dt>Description</dt>
   <dd>
@@ -77,6 +79,11 @@ be specified using the `?region=` query parameter.
     None
   </dd>
 
+  <dt>Blocking Queries</dt>
+  <dd>
+    [Supported](/docs/http/index.html#blocking-queries)
+  </dd>
+
   <dt>Returns</dt>
   <dd>
 
@@ -102,4 +109,3 @@ be specified using the `?region=` query parameter.
 
   </dd>
 </dl>
-
diff --git a/website/source/docs/http/evals.html.md b/website/source/docs/http/evals.html.md
index 3bc22da8ff0..23d98cc9516 100644
--- a/website/source/docs/http/evals.html.md
+++ b/website/source/docs/http/evals.html.md
@@ -31,6 +31,11 @@ be specified using the `?region=` query parameter.
     None
   </dd>
 
+  <dt>Blocking Queries</dt>
+  <dd>
+    [Supported](/docs/http/index.html#blocking-queries)
+  </dd>
+
   <dt>Returns</dt>
   <dd>
 
@@ -59,4 +64,3 @@ be specified using the `?region=` query parameter.
 
   </dd>
 </dl>
-
diff --git a/website/source/docs/http/index.html.md b/website/source/docs/http/index.html.md
index 671d19fa50e..7ed3f0dbdb6 100644
--- a/website/source/docs/http/index.html.md
+++ b/website/source/docs/http/index.html.md
@@ -31,6 +31,7 @@ The API is modeled closely on the underlying data model. Use the links to the le
 documentation about specific endpoints. There are also "Agent" APIs which interact with
 a specific agent and not the broader cluster used for administration.
 
+<a name="blocking-queries"></a>
 ## Blocking Queries
 
 Certain endpoints support a feature called a "blocking query." A blocking query
diff --git a/website/source/docs/http/job.html.md b/website/source/docs/http/job.html.md
index 211963e6a12..cbf0f5097a0 100644
--- a/website/source/docs/http/job.html.md
+++ b/website/source/docs/http/job.html.md
@@ -6,7 +6,7 @@ description: |-
   The '/1/job' endpoint is used for CRUD on a single job.
 ---
 
-# /v1/job/\<ID\>
+# /v1/job
 
 The `job` endpoint is used for CRUD on a single job. By default, the agent's local
 region is used; another region can be specified using the `?region=` query parameter.
@@ -30,6 +30,11 @@ region is used; another region can be specified using the `?region=` query param
     None
   </dd>
 
+  <dt>Blocking Queries</dt>
+  <dd>
+    [Supported](/docs/http/index.html#blocking-queries)
+  </dd>
+
   <dt>Returns</dt>
   <dd>
 
@@ -136,129 +141,146 @@ region is used; another region can be specified using the `?region=` query param
   </dd>
 </dl>
 
-## PUT / POST
-
 <dl>
   <dt>Description</dt>
   <dd>
-    Registers a new job or updates an existing job
+    Query the allocations belonging to a single job.
   </dd>
 
   <dt>Method</dt>
-  <dd>PUT or POST</dd>
+  <dd>GET</dd>
 
   <dt>URL</dt>
-  <dd>`/v1/job/<ID>`</dd>
+  <dd>`/v1/job/<id>/allocations`</dd>
 
   <dt>Parameters</dt>
   <dd>
-    <ul>
-      <li>
-        <span class="param">Job</span>
-        <span class="param-flags">required</span>
-        The JSON definition of the job. The general structure is given
-        by the [job specification](/docs/jobspec/index.html), and matches
-        the return response of GET.
-      </li>
-    </ul>
+    None
+  </dd>
+
+  <dt>Blocking Queries</dt>
+  <dd>
+    [Supported](/docs/http/index.html#blocking-queries)
   </dd>
 
   <dt>Returns</dt>
   <dd>
 
     ```javascript
+    [
     {
-    "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
-    "EvalCreateIndex": 35,
-    "JobModifyIndex": 34,
-    }
+        "ID": "3575ba9d-7a12-0c96-7b28-add168c67984",
+        "EvalID": "151accaa-1ac6-90fe-d427-313e70ccbb88",
+        "Name": "binstore-storagelocker.binsl[0]",
+        "NodeID": "a703c3ca-5ff8-11e5-9213-970ee8879d1b",
+        "JobID": "binstore-storagelocker",
+        "TaskGroup": "binsl",
+        "DesiredStatus": "run",
+        "DesiredDescription": "",
+        "ClientStatus": "running",
+        "ClientDescription": "",
+        "CreateIndex": 16,
+        "ModifyIndex": 16
+    },
+    ...
+    ]
     ```
 
   </dd>
 </dl>
 
-## DELETE
-
 <dl>
   <dt>Description</dt>
   <dd>
-    Deregisters a job, and stops all allocations part of it.
+    Query the evaluations belonging to a single job.
   </dd>
 
   <dt>Method</dt>
-  <dd>DELETE</dd>
+  <dd>GET</dd>
 
   <dt>URL</dt>
-  <dd>`/v1/job/<ID>`</dd>
+  <dd>`/v1/job/<id>/evaluations`</dd>
 
   <dt>Parameters</dt>
   <dd>
     None
   </dd>
 
+  <dt>Blocking Queries</dt>
+  <dd>
+    [Supported](/docs/http/index.html#blocking-queries)
+  </dd>
+
   <dt>Returns</dt>
   <dd>
 
     ```javascript
+    [
     {
-    "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
-    "EvalCreateIndex": 35,
-    "JobModifyIndex": 34,
-    }
+        "ID": "151accaa-1ac6-90fe-d427-313e70ccbb88",
+        "Priority": 50,
+        "Type": "service",
+        "TriggeredBy": "job-register",
+        "JobID": "binstore-storagelocker",
+        "JobModifyIndex": 14,
+        "NodeID": "",
+        "NodeModifyIndex": 0,
+        "Status": "complete",
+        "StatusDescription": "",
+        "Wait": 0,
+        "NextEval": "",
+        "PreviousEval": "",
+        "CreateIndex": 15,
+        "ModifyIndex": 17
+    },
+    ...
+    ]
     ```
 
   </dd>
 </dl>
 
-# /v1/job/\<ID\>/allocations
-## GET
+## PUT / POST
 
 <dl>
   <dt>Description</dt>
   <dd>
-    Query the allocations belonging to a single job.
+    Registers a new job or updates an existing job
   </dd>
 
   <dt>Method</dt>
-  <dd>GET</dd>
+  <dd>PUT or POST</dd>
 
   <dt>URL</dt>
-  <dd>`/v1/job/<id>/allocations`</dd>
+  <dd>`/v1/job/<ID>`</dd>
 
   <dt>Parameters</dt>
   <dd>
-    None
+    <ul>
+      <li>
+        <span class="param">Job</span>
+        <span class="param-flags">required</span>
+        The JSON definition of the job. The general structure is given
+        by the [job specification](/docs/jobspec/index.html), and matches
+        the return response of GET.
+      </li>
+    </ul>
   </dd>
 
   <dt>Returns</dt>
   <dd>
 
     ```javascript
-    [
     {
-        "ID": "3575ba9d-7a12-0c96-7b28-add168c67984",
-        "EvalID": "151accaa-1ac6-90fe-d427-313e70ccbb88",
-        "Name": "binstore-storagelocker.binsl[0]",
-        "NodeID": "a703c3ca-5ff8-11e5-9213-970ee8879d1b",
-        "JobID": "binstore-storagelocker",
-        "TaskGroup": "binsl",
-        "DesiredStatus": "run",
-        "DesiredDescription": "",
-        "ClientStatus": "running",
-        "ClientDescription": "",
-        "CreateIndex": 16,
-        "ModifyIndex": 16
-    },
-    ...
-    ]
+    "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
+    "EvalCreateIndex": 35,
+    "JobModifyIndex": 34,
+    }
     ```
 
   </dd>
 </dl>
 
-# /v1/job/\<ID\>/evaluate
-## PUT / POST
-
 <dl>
   <dt>Description</dt>
   <dd>
@@ -291,20 +313,19 @@ region is used; another region can be specified using the `?region=` query param
   </dd>
 </dl>
 
-# /v1/job/\<ID\>/evaluations
-## GET
+## DELETE
 
 <dl>
   <dt>Description</dt>
   <dd>
-    Query the evaluations belonging to a single job.
+    Deregisters a job, and stops all allocations part of it.
   </dd>
 
   <dt>Method</dt>
-  <dd>GET</dd>
+  <dd>DELETE</dd>
 
   <dt>URL</dt>
-  <dd>`/v1/job/<id>/evaluations`</dd>
+  <dd>`/v1/job/<ID>`</dd>
 
   <dt>Parameters</dt>
   <dd>
@@ -315,28 +336,12 @@ region is used; another region can be specified using the `?region=` query param
   <dd>
 
     ```javascript
-    [
     {
-        "ID": "151accaa-1ac6-90fe-d427-313e70ccbb88",
-        "Priority": 50,
-        "Type": "service",
-        "TriggeredBy": "job-register",
-        "JobID": "binstore-storagelocker",
-        "JobModifyIndex": 14,
-        "NodeID": "",
-        "NodeModifyIndex": 0,
-        "Status": "complete",
-        "StatusDescription": "",
-        "Wait": 0,
-        "NextEval": "",
-        "PreviousEval": "",
-        "CreateIndex": 15,
-        "ModifyIndex": 17
-    },
-    ...
-    ]
+    "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
+    "EvalCreateIndex": 35,
+    "JobModifyIndex": 34,
+    }
     ```
 
   </dd>
 </dl>
-
diff --git a/website/source/docs/http/jobs.html.md b/website/source/docs/http/jobs.html.md
index f724ce0ace9..8f098b1ca85 100644
--- a/website/source/docs/http/jobs.html.md
+++ b/website/source/docs/http/jobs.html.md
@@ -31,6 +31,11 @@ another region can be specified using the `?region=` query parameter.
     None
   </dd>
 
+  <dt>Blocking Queries</dt>
+  <dd>
+    [Supported](/docs/http/index.html#blocking-queries)
+  </dd>
+
   <dt>Returns</dt>
   <dd>
 
@@ -93,4 +98,3 @@ another region can be specified using the `?region=` query parameter.
 
   </dd>
 </dl>
-
diff --git a/website/source/docs/http/node.html.md b/website/source/docs/http/node.html.md
index f16131f97a7..df09426d62a 100644
--- a/website/source/docs/http/node.html.md
+++ b/website/source/docs/http/node.html.md
@@ -31,6 +31,11 @@ be specified using the `?region=` query parameter.
     None
   </dd>
 
+  <dt>Blocking Queries</dt>
+  <dd>
+    [Supported](/docs/http/index.html#blocking-queries)
+  </dd>
+
   <dt>Returns</dt>
   <dd>
 
@@ -82,9 +87,6 @@ be specified using the `?region=` query parameter.
   </dd>
 </dl>
 
-# /v1/node/\<ID\>/allocations
-## GET
-
 <dl>
   <dt>Description</dt>
   <dd>
@@ -102,6 +104,11 @@ be specified using the `?region=` query parameter.
     None
   </dd>
 
+  <dt>Blocking Queries</dt>
+  <dd>
+    [Supported](/docs/http/index.html#blocking-queries)
+  </dd>
+
   <dt>Returns</dt>
   <dd>
 
@@ -128,7 +135,6 @@ be specified using the `?region=` query parameter.
   </dd>
 </dl>
 
-# /v1/node/\<ID\>/evaluate
 ## PUT / POST
 
 <dl>
@@ -163,9 +169,6 @@ be specified using the `?region=` query parameter.
   </dd>
 </dl>
 
-# /v1/node/\<ID\>/drain
-## PUT / POST
-
 <dl>
   <dt>Description</dt>
   <dd>
@@ -175,7 +178,7 @@ be specified using the `?region=` query parameter.
   </dd>
 
   <dt>Method</dt>
-  <dd>PUT or POSt</dd>
+  <dd>PUT or POST</dd>
 
   <dt>URL</dt>
   <dd>`/v1/node/<ID>/drain`</dd>
@@ -205,4 +208,3 @@ be specified using the `?region=` query parameter.
 
   </dd>
 </dl>
-
diff --git a/website/source/docs/http/nodes.html.md b/website/source/docs/http/nodes.html.md
index 36fa96fcdab..b8e2b91a95f 100644
--- a/website/source/docs/http/nodes.html.md
+++ b/website/source/docs/http/nodes.html.md
@@ -31,6 +31,11 @@ be specified using the `?region=` query parameter.
     None
   </dd>
 
+  <dt>Blocking Queries</dt>
+  <dd>
+    [Supported](/docs/http/index.html#blocking-queries)
+  </dd>
+
   <dt>Returns</dt>
   <dd>
 
@@ -53,5 +58,3 @@ be specified using the `?region=` query parameter.
 
   </dd>
 </dl>
-
-