Merge pull request #368 from hashicorp/b-docs

website: clean up HTTP docs, add blocking queries
hashicorp · Nov 4, 2015 · ab87ef4 · ab87ef4
2 parents 4e88552 + 8f2bb25
commit ab87ef4
Show file tree

Hide file tree

Showing 9 changed files with 132 additions and 99 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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>
-
-Original file line number
+Diff line change
@@ Expand Up / @@ -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>
@@ Expand Down Expand Up / @@ -179,4 +184,3 @@ be specified using the `?region=` query parameter. @@
       </dd>
     </dl>