From fa215ede1ab71bd461e5d3db37d10203310d4afb Mon Sep 17 00:00:00 2001
From: Chelsea Holland Komlo <me@chelseakomlo.com>
Date: Thu, 24 Aug 2017 22:33:28 +0000
Subject: [PATCH 1/2] add HTTP documentation for search api

---
 website/source/api/search.html.md | 109 ++++++++++++++++++++++++++++++
 website/source/layouts/api.erb    |   4 ++
 2 files changed, 113 insertions(+)
 create mode 100644 website/source/api/search.html.md

diff --git a/website/source/api/search.html.md b/website/source/api/search.html.md
new file mode 100644
index 000000000..ea52785d5
--- /dev/null
+++ b/website/source/api/search.html.md
@@ -0,0 +1,109 @@
+---
+layout: api
+page_title: Search - HTTP API
+sidebar_current: api-search
+description: |-
+  The /search endpoint returns matches for a given prefix and context
+---
+
+# Search HTTP API
+
+The `/search` endpoint returns matches for a given prefix and context, where a
+context can be jobs, allocations, evaluations, nodes, or deployments.
+Additionally, a prefix can be searched for within every context.
+
+| Method  | Path                         | Produces                   |
+| ------- | ---------------------------- | -------------------------- |
+| `POST`  | `/v1/search                 | `application/json`         |
+
+The table below shows this endpoint's support for
+[blocking queries](/api/index.html#blocking-queries) and
+[required ACLs](/api/index.html#acls).
+
+| Blocking Queries | ACL Required |
+| ---------------- | ------------ |
+| `NO`             | `none`       |
+
+### Parameters
+
+- `Prefix` `(string: <required>)` - Specifies the identifer against which
+  matches will be found. For example, if the given prefix were "a", potential
+  matches might be "abcd", or "aabb".
+- `Context` `(string: <required>)` - Defines the scope in which a search for a
+  prefix operates. Contexts can be: "jobs", "evals", "allocs", "nodes",
+  "deployment" or "all", meaning every context will be searched for that
+  identifier.
+
+### Sample Payload (for a specific context)
+
+```javascript
+{
+  "Prefix": "abc",
+  "Context": "evals"
+}
+```
+
+### Sample Request
+
+```text
+$ curl \
+    --request POST \
+    --data @payload.json \
+    https://nomad.rocks/v1/search
+```
+
+### Sample Response
+
+```json
+{ "Matches": {
+    "evals": [
+      "abc2fdc0-e1fd-2536-67d8-43af8ca798ac"
+    ]
+  },
+  "Truncations": {
+    "evals": "false"
+  }
+}
+```
+
+### Sample Payload (for all contexts)
+
+```javascript
+{
+  "Prefix": "abc",
+  "Context": "all"
+}
+```
+
+### Sample Request
+
+```text
+$ curl \
+    --request POST \
+    --data @payload.json \
+    https://nomad.rocks/v1/search
+```
+
+### Sample Response
+
+```json
+{ "Matches": {
+    "allocs": [],
+    "deployment": [],
+    "evals": [
+      "abc2fdc0-e1fd-2536-67d8-43af8ca798ac"
+    ],
+    "jobs": [
+      "abcde"
+    ],
+    "nodes": []
+  },
+  "Truncations": {
+    "allocs": "false",
+    "deployment": "false",
+    "evals": "false",
+    "jobs": "false",
+    "nodes": "false"
+  }
+}
+```
diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb
index cf0f9fbdd..94f2e91e2 100644
--- a/website/source/layouts/api.erb
+++ b/website/source/layouts/api.erb
@@ -51,6 +51,10 @@
         <a href="/api/regions.html">Regions</a>
       </li>
 
+      <li<%= sidebar_current("api-search") %>>
+        <a href="/api/search.html">Search</a>
+      </li>
+
       <li<%= sidebar_current("api-status") %>>
         <a href="/api/status.html">Status</a>
       </li>

From 004f98414732dd71dc4804256f8899005d5d654b Mon Sep 17 00:00:00 2001
From: Chelsea Holland Komlo <me@chelseakomlo.com>
Date: Fri, 25 Aug 2017 14:08:22 +0000
Subject: [PATCH 2/2] alignment and fixups from  code review

---
 website/source/api/search.html.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/website/source/api/search.html.md b/website/source/api/search.html.md
index ea52785d5..b3b79731d 100644
--- a/website/source/api/search.html.md
+++ b/website/source/api/search.html.md
@@ -3,7 +3,7 @@ layout: api
 page_title: Search - HTTP API
 sidebar_current: api-search
 description: |-
-  The /search endpoint returns matches for a given prefix and context
+  The /search endpoint is used to search for Nomad objects
 ---
 
 # Search HTTP API
@@ -14,7 +14,7 @@ Additionally, a prefix can be searched for within every context.
 
 | Method  | Path                         | Produces                   |
 | ------- | ---------------------------- | -------------------------- |
-| `POST`  | `/v1/search                 | `application/json`         |
+| `POST`  | `/v1/search                  | `application/json`         |
 
 The table below shows this endpoint's support for
 [blocking queries](/api/index.html#blocking-queries) and
@@ -31,8 +31,8 @@ The table below shows this endpoint's support for
   matches might be "abcd", or "aabb".
 - `Context` `(string: <required>)` - Defines the scope in which a search for a
   prefix operates. Contexts can be: "jobs", "evals", "allocs", "nodes",
-  "deployment" or "all", meaning every context will be searched for that
-  identifier.
+  "deployment" or an empty string, in which every context will be searched for
+  the identifier.
 
 ### Sample Payload (for a specific context)
 
@@ -71,7 +71,7 @@ $ curl \
 ```javascript
 {
   "Prefix": "abc",
-  "Context": "all"
+  "Context": ""
 }
 ```