update dockercloud events api doc with filters

fchunbo · Dec 7, 2016 · 261c8d2 · 261c8d2
1 parent 69b3a3d
commit 261c8d2
Show file tree

Hide file tree

Showing 4 changed files with 126 additions and 28 deletions.
diff --git a/apidocs/cloud-api-source/source/includes/dockercloud-events.md b/apidocs/cloud-api-source/source/includes/dockercloud-events.md
@@ -83,17 +83,23 @@ events.run_forever()
 ```go
 import "github.com/docker/go-dockercloud/dockercloud"
 
-c := make(chan dockercloud.Event)
-e := make(chan error)
+// Listens for container events only
+myFilter := dockercloud.NewStreamFilter(&dockercloud.EventFilter{Type: "container"})
 
-go dockercloud.Events(c, e)
+stream := dockercloud.NewStream(myFilter)
+
+if err := stream.Connect(); err == nil {
+	go stream.RunForever()
+} else {
+	log.Print("Connect err: " + err.Error())
+}
 
 for {
 	select {
-		case event := <-c:
-			log.Println(event)
-		case err := <-e:
-			log.Println(err)
+	case event := <-stream.MessageChan:
+		log.Println(event)
+	case err := <-stream.ErrorChan:
+		log.Println(err)
 	}
 }
 ```
@@ -119,3 +125,11 @@ Available in Docker Cloud's **STREAM API**
 ### HTTP Request
 
 `GET /api/audit/v1/[optional_namespace/]events/`
+
+### Query Parameters
+
+Parameter | Description
+--------- | -----------
+type | Filter by type
+object | Filter by object resource URI
+parent | Filter by object parents
diff --git a/apidocs/docker-cloud/includes/dockercloud-events.html b/apidocs/docker-cloud/includes/dockercloud-events.html
@@ -183,17 +183,23 @@ <h2 id="listen-to-new-docker-cloud-events">Listen to new Docker Cloud Events</h2
 </code></pre>
 <pre class="highlight go"><code><span class="k">import</span><span class="x"> </span><span class="s">"github.com/docker/go-dockercloud/dockercloud"</span><span class="x">
 
-</span><span class="n">c</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="nb">make</span><span class="p">(</span><span class="k">chan</span><span class="x"> </span><span class="n">dockercloud</span><span class="o">.</span><span class="n">Event</span><span class="p">)</span><span class="x">
-</span><span class="n">e</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="nb">make</span><span class="p">(</span><span class="k">chan</span><span class="x"> </span><span class="kt">error</span><span class="p">)</span><span class="x">
+</span><span class="c">// Listens for container events only</span><span class="x">
+</span><span class="n">myFilter</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="n">dockercloud</span><span class="o">.</span><span class="n">NewStreamFilter</span><span class="p">(</span><span class="o">&amp;</span><span class="n">dockercloud</span><span class="o">.</span><span class="n">EventFilter</span><span class="p">{</span><span class="n">Type</span><span class="o">:</span><span class="x"> </span><span class="s">"container"</span><span class="p">})</span><span class="x">
 
-</span><span class="k">go</span><span class="x"> </span><span class="n">dockercloud</span><span class="o">.</span><span class="n">Events</span><span class="p">(</span><span class="n">c</span><span class="p">,</span><span class="x"> </span><span class="n">e</span><span class="p">)</span><span class="x">
+</span><span class="n">stream</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="n">dockercloud</span><span class="o">.</span><span class="n">NewStream</span><span class="p">(</span><span class="n">myFilter</span><span class="p">)</span><span class="x">
+
+</span><span class="k">if</span><span class="x"> </span><span class="n">err</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="n">stream</span><span class="o">.</span><span class="n">Connect</span><span class="p">();</span><span class="x"> </span><span class="n">err</span><span class="x"> </span><span class="o">==</span><span class="x"> </span><span class="no">nil</span><span class="x"> </span><span class="p">{</span><span class="x">
+    </span><span class="k">go</span><span class="x"> </span><span class="n">stream</span><span class="o">.</span><span class="n">RunForever</span><span class="p">()</span><span class="x">
+</span><span class="p">}</span><span class="x"> </span><span class="k">else</span><span class="x"> </span><span class="p">{</span><span class="x">
+    </span><span class="n">log</span><span class="o">.</span><span class="n">Print</span><span class="p">(</span><span class="s">"Connect err: "</span><span class="x"> </span><span class="o">+</span><span class="x"> </span><span class="n">err</span><span class="o">.</span><span class="n">Error</span><span class="p">())</span><span class="x">
+</span><span class="p">}</span><span class="x">
 
 </span><span class="k">for</span><span class="x"> </span><span class="p">{</span><span class="x">
     </span><span class="k">select</span><span class="x"> </span><span class="p">{</span><span class="x">
-        </span><span class="k">case</span><span class="x"> </span><span class="n">event</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="o">&lt;-</span><span class="n">c</span><span class="o">:</span><span class="x">
-            </span><span class="n">log</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="n">event</span><span class="p">)</span><span class="x">
-        </span><span class="k">case</span><span class="x"> </span><span class="n">err</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="o">&lt;-</span><span class="n">e</span><span class="o">:</span><span class="x">
-            </span><span class="n">log</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="n">err</span><span class="p">)</span><span class="x">
+    </span><span class="k">case</span><span class="x"> </span><span class="n">event</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="o">&lt;-</span><span class="n">stream</span><span class="o">.</span><span class="n">MessageChan</span><span class="o">:</span><span class="x">
+        </span><span class="n">log</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="n">event</span><span class="p">)</span><span class="x">
+    </span><span class="k">case</span><span class="x"> </span><span class="n">err</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="o">&lt;-</span><span class="n">stream</span><span class="o">.</span><span class="n">ErrorChan</span><span class="o">:</span><span class="x">
+        </span><span class="n">log</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="n">err</span><span class="p">)</span><span class="x">
     </span><span class="p">}</span><span class="x">
 </span><span class="p">}</span><span class="x">
 </span></code></pre>
@@ -216,6 +222,28 @@ <h3 id="http-request">HTTP Request</h3>
 
 <p><code class="prettyprint">GET /api/audit/v1/[optional_namespace/]events/</code></p>
 
+<h3 id="query-parameters">Query Parameters</h3>
+
+<table><thead>
+<tr>
+<th>Parameter</th>
+<th>Description</th>
+</tr>
+</thead><tbody>
+<tr>
+<td>type</td>
+<td>Filter by type</td>
+</tr>
+<tr>
+<td>object</td>
+<td>Filter by object resource URI</td>
+</tr>
+<tr>
+<td>parent</td>
+<td>Filter by object parents</td>
+</tr>
+</tbody></table>
+
       </div>
       <div class="dark-box">
       </div>

diff --git a/apidocs/docker-cloud/index.html b/apidocs/docker-cloud/index.html
@@ -6465,17 +6465,23 @@ <h2 id="listen-to-new-docker-cloud-events">Listen to new Docker Cloud Events</h2
 </code></pre>
 <pre class="highlight go"><code><span class="k">import</span><span class="x"> </span><span class="s">"github.com/docker/go-dockercloud/dockercloud"</span><span class="x">
 
-</span><span class="n">c</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="nb">make</span><span class="p">(</span><span class="k">chan</span><span class="x"> </span><span class="n">dockercloud</span><span class="o">.</span><span class="n">Event</span><span class="p">)</span><span class="x">
-</span><span class="n">e</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="nb">make</span><span class="p">(</span><span class="k">chan</span><span class="x"> </span><span class="kt">error</span><span class="p">)</span><span class="x">
+</span><span class="c">// Listens for container events only</span><span class="x">
+</span><span class="n">myFilter</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="n">dockercloud</span><span class="o">.</span><span class="n">NewStreamFilter</span><span class="p">(</span><span class="o">&amp;</span><span class="n">dockercloud</span><span class="o">.</span><span class="n">EventFilter</span><span class="p">{</span><span class="n">Type</span><span class="o">:</span><span class="x"> </span><span class="s">"container"</span><span class="p">})</span><span class="x">
 
-</span><span class="k">go</span><span class="x"> </span><span class="n">dockercloud</span><span class="o">.</span><span class="n">Events</span><span class="p">(</span><span class="n">c</span><span class="p">,</span><span class="x"> </span><span class="n">e</span><span class="p">)</span><span class="x">
+</span><span class="n">stream</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="n">dockercloud</span><span class="o">.</span><span class="n">NewStream</span><span class="p">(</span><span class="n">myFilter</span><span class="p">)</span><span class="x">
+
+</span><span class="k">if</span><span class="x"> </span><span class="n">err</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="n">stream</span><span class="o">.</span><span class="n">Connect</span><span class="p">();</span><span class="x"> </span><span class="n">err</span><span class="x"> </span><span class="o">==</span><span class="x"> </span><span class="no">nil</span><span class="x"> </span><span class="p">{</span><span class="x">
+    </span><span class="k">go</span><span class="x"> </span><span class="n">stream</span><span class="o">.</span><span class="n">RunForever</span><span class="p">()</span><span class="x">
+</span><span class="p">}</span><span class="x"> </span><span class="k">else</span><span class="x"> </span><span class="p">{</span><span class="x">
+    </span><span class="n">log</span><span class="o">.</span><span class="n">Print</span><span class="p">(</span><span class="s">"Connect err: "</span><span class="x"> </span><span class="o">+</span><span class="x"> </span><span class="n">err</span><span class="o">.</span><span class="n">Error</span><span class="p">())</span><span class="x">
+</span><span class="p">}</span><span class="x">
 
 </span><span class="k">for</span><span class="x"> </span><span class="p">{</span><span class="x">
     </span><span class="k">select</span><span class="x"> </span><span class="p">{</span><span class="x">
-        </span><span class="k">case</span><span class="x"> </span><span class="n">event</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="o">&lt;-</span><span class="n">c</span><span class="o">:</span><span class="x">
-            </span><span class="n">log</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="n">event</span><span class="p">)</span><span class="x">
-        </span><span class="k">case</span><span class="x"> </span><span class="n">err</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="o">&lt;-</span><span class="n">e</span><span class="o">:</span><span class="x">
-            </span><span class="n">log</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="n">err</span><span class="p">)</span><span class="x">
+    </span><span class="k">case</span><span class="x"> </span><span class="n">event</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="o">&lt;-</span><span class="n">stream</span><span class="o">.</span><span class="n">MessageChan</span><span class="o">:</span><span class="x">
+        </span><span class="n">log</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="n">event</span><span class="p">)</span><span class="x">
+    </span><span class="k">case</span><span class="x"> </span><span class="n">err</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="o">&lt;-</span><span class="n">stream</span><span class="o">.</span><span class="n">ErrorChan</span><span class="o">:</span><span class="x">
+        </span><span class="n">log</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="n">err</span><span class="p">)</span><span class="x">
     </span><span class="p">}</span><span class="x">
 </span><span class="p">}</span><span class="x">
 </span></code></pre>
@@ -6498,6 +6504,28 @@ <h3 id="http-request">HTTP Request</h3>
 
 <p><code class="prettyprint">GET /api/audit/v1/[optional_namespace/]events/</code></p>
 
+<h3 id="query-parameters">Query Parameters</h3>
+
+<table><thead>
+<tr>
+<th>Parameter</th>
+<th>Description</th>
+</tr>
+</thead><tbody>
+<tr>
+<td>type</td>
+<td>Filter by type</td>
+</tr>
+<tr>
+<td>object</td>
+<td>Filter by object resource URI</td>
+</tr>
+<tr>
+<td>parent</td>
+<td>Filter by object parents</td>
+</tr>
+</tbody></table>
+
           <h1 id="errors">Errors</h1>
 
 <blockquote>

diff --git a/apidocs/layouts/single.html b/apidocs/layouts/single.html
@@ -6465,17 +6465,23 @@ <h2 id="listen-to-new-docker-cloud-events">Listen to new Docker Cloud Events</h2
 </code></pre>
 <pre class="highlight go"><code><span class="k">import</span><span class="x"> </span><span class="s">"github.com/docker/go-dockercloud/dockercloud"</span><span class="x">
 
-</span><span class="n">c</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="nb">make</span><span class="p">(</span><span class="k">chan</span><span class="x"> </span><span class="n">dockercloud</span><span class="o">.</span><span class="n">Event</span><span class="p">)</span><span class="x">
-</span><span class="n">e</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="nb">make</span><span class="p">(</span><span class="k">chan</span><span class="x"> </span><span class="kt">error</span><span class="p">)</span><span class="x">
+</span><span class="c">// Listens for container events only</span><span class="x">
+</span><span class="n">myFilter</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="n">dockercloud</span><span class="o">.</span><span class="n">NewStreamFilter</span><span class="p">(</span><span class="o">&amp;</span><span class="n">dockercloud</span><span class="o">.</span><span class="n">EventFilter</span><span class="p">{</span><span class="n">Type</span><span class="o">:</span><span class="x"> </span><span class="s">"container"</span><span class="p">})</span><span class="x">
 
-</span><span class="k">go</span><span class="x"> </span><span class="n">dockercloud</span><span class="o">.</span><span class="n">Events</span><span class="p">(</span><span class="n">c</span><span class="p">,</span><span class="x"> </span><span class="n">e</span><span class="p">)</span><span class="x">
+</span><span class="n">stream</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="n">dockercloud</span><span class="o">.</span><span class="n">NewStream</span><span class="p">(</span><span class="n">myFilter</span><span class="p">)</span><span class="x">
+
+</span><span class="k">if</span><span class="x"> </span><span class="n">err</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="n">stream</span><span class="o">.</span><span class="n">Connect</span><span class="p">();</span><span class="x"> </span><span class="n">err</span><span class="x"> </span><span class="o">==</span><span class="x"> </span><span class="no">nil</span><span class="x"> </span><span class="p">{</span><span class="x">
+    </span><span class="k">go</span><span class="x"> </span><span class="n">stream</span><span class="o">.</span><span class="n">RunForever</span><span class="p">()</span><span class="x">
+</span><span class="p">}</span><span class="x"> </span><span class="k">else</span><span class="x"> </span><span class="p">{</span><span class="x">
+    </span><span class="n">log</span><span class="o">.</span><span class="n">Print</span><span class="p">(</span><span class="s">"Connect err: "</span><span class="x"> </span><span class="o">+</span><span class="x"> </span><span class="n">err</span><span class="o">.</span><span class="n">Error</span><span class="p">())</span><span class="x">
+</span><span class="p">}</span><span class="x">
 
 </span><span class="k">for</span><span class="x"> </span><span class="p">{</span><span class="x">
     </span><span class="k">select</span><span class="x"> </span><span class="p">{</span><span class="x">
-        </span><span class="k">case</span><span class="x"> </span><span class="n">event</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="o">&lt;-</span><span class="n">c</span><span class="o">:</span><span class="x">
-            </span><span class="n">log</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="n">event</span><span class="p">)</span><span class="x">
-        </span><span class="k">case</span><span class="x"> </span><span class="n">err</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="o">&lt;-</span><span class="n">e</span><span class="o">:</span><span class="x">
-            </span><span class="n">log</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="n">err</span><span class="p">)</span><span class="x">
+    </span><span class="k">case</span><span class="x"> </span><span class="n">event</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="o">&lt;-</span><span class="n">stream</span><span class="o">.</span><span class="n">MessageChan</span><span class="o">:</span><span class="x">
+        </span><span class="n">log</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="n">event</span><span class="p">)</span><span class="x">
+    </span><span class="k">case</span><span class="x"> </span><span class="n">err</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="o">&lt;-</span><span class="n">stream</span><span class="o">.</span><span class="n">ErrorChan</span><span class="o">:</span><span class="x">
+        </span><span class="n">log</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="n">err</span><span class="p">)</span><span class="x">
     </span><span class="p">}</span><span class="x">
 </span><span class="p">}</span><span class="x">
 </span></code></pre>
@@ -6498,6 +6504,28 @@ <h3 id="http-request">HTTP Request</h3>
 
 <p><code class="prettyprint">GET /api/audit/v1/[optional_namespace/]events/</code></p>
 
+<h3 id="query-parameters">Query Parameters</h3>
+
+<table><thead>
+<tr>
+<th>Parameter</th>
+<th>Description</th>
+</tr>
+</thead><tbody>
+<tr>
+<td>type</td>
+<td>Filter by type</td>
+</tr>
+<tr>
+<td>object</td>
+<td>Filter by object resource URI</td>
+</tr>
+<tr>
+<td>parent</td>
+<td>Filter by object parents</td>
+</tr>
+</tbody></table>
+
           <h1 id="errors">Errors</h1>
 
 <blockquote>