From 52b2f837af61639a29c39fce0f3a19bbeca3ecd7 Mon Sep 17 00:00:00 2001
From: Kevin McCarthy <me@kevinmccarthy.org>
Date: Mon, 20 Oct 2014 02:58:17 +0000
Subject: [PATCH] Document client

---
 README.md        | 10 ++++++++++
 client/README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+)
 create mode 100644 client/README.md

diff --git a/README.md b/README.md
index 6f2028df..af337c21 100644
--- a/README.md
+++ b/README.md
@@ -126,6 +126,16 @@ This resource is read-only. The machine information is returned as a JSON object
 
 The actual object is the marshalled JSON of the `MachineInfo` struct found in [info/machine.go](info/machine.go)
 
+## REST API Clients
+
+There is an example Go client under [client/](client/) - you can use it on your own Go project by including it like this:
+
+```go
+import "github.com/google/cadvisor/client"
+client, err = client.NewClient("http://192.168.59.103:8080/")
+mInfo, _ := client.MachineInfo()
+```
+
 ## Roadmap
 
 cAdvisor aims to improve the resource usage and performance characteristics of running containers. Today, we gather and expose this information to users. In our roadmap:
diff --git a/client/README.md b/client/README.md
new file mode 100644
index 00000000..56ea9613
--- /dev/null
+++ b/client/README.md
@@ -0,0 +1,52 @@
+# Example REST API Client
+
+This is an implementation of a cadvisor REST API in Go.  You can use it like this:
+
+```go
+client, err := client.NewClient("http://192.168.59.103:8080/")
+```
+
+Obviously, replace the URL with the path to your actual cadvisor REST endpoint.
+
+
+### MachineInfo
+
+```go
+client.MachineInfo()
+```
+
+This method returns a cadvisor/info.MachineInfo struct with all the fields filled in.  Here is an example return value:
+
+```
+(*info.MachineInfo)(0xc208022b10)({
+ NumCores: (int) 4,
+ MemoryCapacity: (int64) 2106028032,
+ Filesystems: ([]info.FsInfo) (len=1 cap=4) {
+  (info.FsInfo) {
+   Device: (string) (len=9) "/dev/sda1",
+   Capacity: (uint64) 19507089408
+  }
+ }
+})
+```
+
+### ContainerInfo
+
+Given a container name and a ContainerInfoRequest, will return all information about the specified container.  The ContainerInfoRequest struct just has one field, NumStats, which is the number of stat entries that you want returned.
+
+```go
+request := info.ContainerInfoRequest{10}
+sInfo, err := client.ContainerInfo("/docker/d9d3eb10179e6f93a...", &request)
+```
+Returns a [ContainerInfo struct](../info/container.go)
+
+### SubcontainersInfo
+
+Given a container name and a ContainerInfoRequest, will recursively return all info about the container and all subcontainers contained within the container.  The ContainerInfoRequest struct just has one field, NumStats, which is the number of stat entries that you want returned.
+
+```go
+request := info.ContainerInfoRequest{10}
+sInfo, err := client.SubcontainersInfo("/docker", &request)
+```
+
+Returns a [ContainerInfo struct](../info/container.go) with the Subcontainers field populated.