Merge pull request #31 from octokit/philosophy

Documenting `go-octokit`'s philosophy

README.md

@@ -2,9 +2,22 @@
 
 Go toolkit for the GitHub API.
 
-## Hypermedia-driven client
+## Status
 
-### Show a user
+Very experimental. APIs are subject to change.
+
+## Motivation
+
+`go-octokit` is designed to be a hypermedia API client that [wraps](http://wynnnetherland.com/journal/what-makes-a-good-api-wrapper) the [GitHub API](http://developer.github.com/).
+
+## Hypermedia agent
+
+`go-octokit` is hypermedia-driven by default.
+Under the hood, it uses [`go-sawyer`](https://github.com/lostisland/go-sawyer), the Go version of [Ruby Sawyer](https://github.com/lostisland/sawyer).
+
+### Hypermedia in go-octokit
+
+Resources in `go-octokit` contain not only data but hypermedia links:
 
 ```go
 package main
@@ -23,7 +36,41 @@ func main() {
       // Handle error
     }
 
-    // Do something with user
+    fmt.Println(user.ReposURL) // https://api.github.com/users/jingweno/repos
+}
+```
+
+### URI templates
+
+Many hypermedia links have variable placeholders. `go-octokit` supports [URI Templates](http://tools.ietf.org/html/rfc6570) for parameterized URI expansion:
+
+```go
+package main
+
+import "github.com/octokit/go-octokit/octokit"
+
+func main() {
+    url, _ := octokit.UserURL.Expand(octokit.M{"user": "jingweno"})
+    fmt.Println(url) // https://api.github.com/users/jingweno
+}
+```
+
+### The Full Hypermedia Experience™
+
+If you want to use `go-octokit` as a pure hypermedia API client, you can
+start at the API root and follow hypermedia links which drive the application state transitions:
+
+```go
+package main
+
+import "github.com/octokit/go-octokit/octokit"
+
+func main() {
+  rootService, _ := client.Root(nil)
+  root, _ := rootService.Get()
+
+  usersService, _ := client.Users(root.UserURL, octokit.M{"users": "jingweno"})
+  user, _ := usersService.Get()
 }
 ```
 
@@ -59,15 +106,10 @@ func main() {
 
 ```
 
-### Exploring hypermedia APIs
-
-```go
-rootService, _ := client.Root(nil)
-root, _ := rootService.Get()
+### Caching
 
-usersService, _ := client.Users(root.UserURL, octokit.M{"users": "jingweno"})
-user, _ := usersService.Get()
-```
+Client-side caching is the #1 thing to do to make a hypermedia client more performant.
+We plan to support this in the near future.
 
 More [examples](https://github.com/octokit/go-octokit/blob/master/examples/example.go) are available.