improve documentation

README.md

@@ -4,4 +4,50 @@
 
 # golark
 
-Golark is a go client for Skylark CMS APIs.
+Golark makes it easy to build Skylark API requests in golang.
+
+```go
+package main
+
+import (
+	"github.com/SoMuchForSubtlety/golark"
+)
+
+type episode struct {
+	Title        string   `json:"title"`
+	Subtitle     string   `json:"subtitle"`
+	UID          string   `json:"uid"`
+	DataSourceID string   `json:"data_source_id"`
+	Items        []string `json:"items"`
+}
+
+func main() {
+	var ep episode
+
+	// request an object
+	golark.NewRequest("https://test.com/api/", "episodes", "ep_123").
+		Execute(&ep)
+
+	// request an object with only certain fields
+	golark.NewRequest("https://test.com/api/", "episodes", "ep_123").
+		AddField(golark.NewField("title")).
+		AddField(golark.NewField("subtitle")).
+		AddField(golark.NewField("uid")).
+		Execute(&ep)
+
+	type container struct {
+		Objects []episode `json:"objects"`
+	}
+
+	var eps container
+
+	// request all members of a collection
+	golark.NewRequest("https://test.com/api/", "episodes", "").
+		Execute(&eps)
+
+	// request all members of a collection with certain properties
+	golark.NewRequest("https://test.com/api/", "episodes", "").
+		WithFilter("title", golark.NewFilter(golark.Equals, "test episode title")).
+		Execute(&eps)
+}
+```

exaple_test.go

@@ -39,3 +39,46 @@ func ExampleRequest_all() {
 		log.Fatal(err)
 	}
 }
+
+// AddField lets you limit requests to certain fields, this can speed them up significanty.
+func ExampleRequest_AddField() {
+	NewRequest("https://test.com/api/", "person", "pers_123").
+		AddField(NewField("first_name")).
+		AddField(NewField("last_name"))
+}
+
+func ExampleRequest_Expand() {
+	NewRequest("https://test.com/api/", "person", "pers_123").
+		Expand(NewField("team_url"))
+}
+
+func ExampleRequest_OrderBy() {
+	NewRequest("https://test.com/api/", "person", "").
+		OrderBy(NewField("first_name"))
+}
+
+// Filters are helpful to search for onjects with knowing their ID
+func ExampleRequest_WithFilter() {
+	NewRequest("https://test.com/api/", "person", "").
+		WithFilter("first_name", NewFilter(Equals, "Bob"))
+}
+
+func ExampleRequest_WithFilter_greater_than() {
+	NewRequest("https://test.com/api/", "person", "").
+		WithFilter("salary", NewFilter(GreaterThan, "10000"))
+}
+
+// You can use comma separated lists to query multiple objects at once.
+func ExampleRequest_WithFilter_multiple() {
+	NewRequest("https://test.com/api/", "person", "").
+		WithFilter("first_name", NewFilter(Equals, "Bob,Lucas,Sue"))
+}
+
+func ExampleField_WithSubField() {
+	NewRequest("https://test.com/api/", "person", "").
+		AddField(NewField("first_name")).
+		AddField(NewField("team_url").
+			WithSubField(NewField("name")).
+			WithSubField(NewField("nation_url").
+				WithSubField(NewField("name"))))
+}