From 8f2bb251578a6419265dd6f3ff03d8fe3336be2a Mon Sep 17 00:00:00 2001 From: Ryan Uber 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 | 269 ++++++++++++------------ 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, 186 insertions(+), 153 deletions(-) diff --git a/website/source/docs/http/alloc.html.md b/website/source/docs/http/alloc.html.md index 3c224fd54..822858a8c 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 +
Blocking Queries
+
+ [Supported](/docs/http/index.html#blocking-queries) +
+
Returns
@@ -179,4 +184,3 @@ be specified using the `?region=` query parameter.
- diff --git a/website/source/docs/http/allocs.html.md b/website/source/docs/http/allocs.html.md index 44ad8aa7e..b59a4f204 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 +
Blocking Queries
+
+ [Supported](/docs/http/index.html#blocking-queries) +
+
Returns
@@ -56,4 +61,3 @@ be specified using the `?region=` query parameter.
- diff --git a/website/source/docs/http/eval.html.md b/website/source/docs/http/eval.html.md index cba43900c..87e048209 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.
Description
- Lists all the evaluations. + Query a specific evaluation.
Method
@@ -31,6 +31,11 @@ be specified using the `?region=` query parameter. None +
Blocking Queries
+
+ [Supported](/docs/http/index.html#blocking-queries) +
+
Returns
@@ -57,9 +62,6 @@ be specified using the `?region=` query parameter.
-# /v1/evaluation/\/allocations -## GET -
Description
@@ -77,6 +79,11 @@ be specified using the `?region=` query parameter. None
+
Blocking Queries
+
+ [Supported](/docs/http/index.html#blocking-queries) +
+
Returns
@@ -102,4 +109,3 @@ be specified using the `?region=` query parameter.
- diff --git a/website/source/docs/http/evals.html.md b/website/source/docs/http/evals.html.md index 3bc22da8f..23d98cc95 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 +
Blocking Queries
+
+ [Supported](/docs/http/index.html#blocking-queries) +
+
Returns
@@ -59,4 +64,3 @@ be specified using the `?region=` query parameter.
- diff --git a/website/source/docs/http/index.html.md b/website/source/docs/http/index.html.md index 671d19fa5..7ed3f0dbd 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. + ## 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 211963e6a..cbf0f5097 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/\ +# /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 +
Blocking Queries
+
+ [Supported](/docs/http/index.html#blocking-queries) +
+
Returns
@@ -136,6 +141,105 @@ region is used; another region can be specified using the `?region=` query param
+
+
Description
+
+ Query the allocations belonging to a single job. +
+ +
Method
+
GET
+ +
URL
+
`/v1/job//allocations`
+ +
Parameters
+
+ None +
+ +
Blocking Queries
+
+ [Supported](/docs/http/index.html#blocking-queries) +
+ +
Returns
+
+ + ```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 + }, + ... + ] + ``` + +
+
+ +
+
Description
+
+ Query the evaluations belonging to a single job. +
+ +
Method
+
GET
+ +
URL
+
`/v1/job//evaluations`
+ +
Parameters
+
+ None +
+ +
Blocking Queries
+
+ [Supported](/docs/http/index.html#blocking-queries) +
+ +
Returns
+
+ + ```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 + }, + ... + ] + ``` + +
+
+ ## PUT / POST
@@ -177,6 +281,38 @@ region is used; another region can be specified using the `?region=` query param
+
+
Description
+
+ Creates a new evaluation for the given job. This can be used to force + run the scheduling logic if necessary. +
+ +
Method
+
PUT or POST
+ +
URL
+
`/v1/job//evaluate`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", + "EvalCreateIndex": 35, + "JobModifyIndex": 34, + } + ``` + +
+
+ ## DELETE
@@ -209,134 +345,3 @@ region is used; another region can be specified using the `?region=` query param
- -# /v1/job/\/allocations -## GET - -
-
Description
-
- Query the allocations belonging to a single job. -
- -
Method
-
GET
- -
URL
-
`/v1/job//allocations`
- -
Parameters
-
- None -
- -
Returns
-
- - ```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 - }, - ... - ] - ``` - -
-
- -# /v1/job/\/evaluate -## PUT / POST - -
-
Description
-
- Creates a new evaluation for the given job. This can be used to force - run the scheduling logic if necessary. -
- -
Method
-
PUT or POST
- -
URL
-
`/v1/job//evaluate`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", - "EvalCreateIndex": 35, - "JobModifyIndex": 34, - } - ``` - -
-
- -# /v1/job/\/evaluations -## GET - -
-
Description
-
- Query the evaluations belonging to a single job. -
- -
Method
-
GET
- -
URL
-
`/v1/job//evaluations`
- -
Parameters
-
- None -
- -
Returns
-
- - ```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 - }, - ... - ] - ``` - -
-
- diff --git a/website/source/docs/http/jobs.html.md b/website/source/docs/http/jobs.html.md index f724ce0ac..8f098b1ca 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 +
Blocking Queries
+
+ [Supported](/docs/http/index.html#blocking-queries) +
+
Returns
@@ -93,4 +98,3 @@ another region can be specified using the `?region=` query parameter.
- diff --git a/website/source/docs/http/node.html.md b/website/source/docs/http/node.html.md index f16131f97..df09426d6 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 +
Blocking Queries
+
+ [Supported](/docs/http/index.html#blocking-queries) +
+
Returns
@@ -82,9 +87,6 @@ be specified using the `?region=` query parameter.
-# /v1/node/\/allocations -## GET -
Description
@@ -102,6 +104,11 @@ be specified using the `?region=` query parameter. None
+
Blocking Queries
+
+ [Supported](/docs/http/index.html#blocking-queries) +
+
Returns
@@ -128,7 +135,6 @@ be specified using the `?region=` query parameter.
-# /v1/node/\/evaluate ## PUT / POST
@@ -163,9 +169,6 @@ be specified using the `?region=` query parameter.
-# /v1/node/\/drain -## PUT / POST -
Description
@@ -175,7 +178,7 @@ be specified using the `?region=` query parameter.
Method
-
PUT or POSt
+
PUT or POST
URL
`/v1/node//drain`
@@ -205,4 +208,3 @@ be specified using the `?region=` query parameter.
- diff --git a/website/source/docs/http/nodes.html.md b/website/source/docs/http/nodes.html.md index 36fa96fcd..b8e2b91a9 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 +
Blocking Queries
+
+ [Supported](/docs/http/index.html#blocking-queries) +
+
Returns
@@ -53,5 +58,3 @@ be specified using the `?region=` query parameter.
- -