commit 6456042b9dd325c6b9b1e246acac3a21bfae58fe
from: Oliver Lowe <o@olowe.co>
date: Thu Jan  6 22:30:44 2022 UTC

Complete the README with a tutorial and a "why?"

commit - 9ea5152367e4cfb31a1d08d23200575dc64058c4
commit + 6456042b9dd325c6b9b1e246acac3a21bfae58fe
blob - 38eb8ee27d388ef042f6b81cc611f709bbcb0cd2
blob + 78f3060f0579f6a1d8864e12180a78cf336c87ba
--- README.md
+++ README.md
@@ -1,17 +1,67 @@
+package icinga provides a client to the Icinga2 HTTP API.
+
+[![godocs.io](http://godocs.io/olowe.co/icinga?status.svg)](http://godocs.io/olowe.co/icinga)
+
+## Quick Start
+
+A Client manages interaction with an Icinga2 server.
+It is created using Dial. Provide the address, in `host:port` form, API username and password, and a `http.Client`:
+
+	client, err := icinga.Dial("icinga.example.com:5665", "icinga", "secret", http.DefaultClient)
+	if err != nil {
+		// handle error
+	}
+
 Icinga2 servers in the wild often serve self-signed certificates which
 fail verification by Go's tls client. To ignore the errors, Dial the server
-with a modified http.Client:
+with a modified `http.Client`:
 
 	t := http.DefaultTransport.(*http.Transport)
 	t.TLSClientConfig = &tls.Config{InsecureSkipVerify: true}
 	c := http.DefaultClient
 	c.Transport = t
-	client, err := icinga.Dial(host, user, pass, c)
+	client, err := icinga.Dial(addr, user, pass, c)
 	if err != nil {
 		// handle error
 	}
-	...
 
-## Why?
+Methods on `Client` provide API actions like looking up users and creating hosts:
 
-The terraform provider...
+	user, err := client.LookupUser("oliver")
+	if err != nil {
+		// handle error
+	}
+	host := Host{
+		Name: "myserver.example.com",
+		CheckCommand: "hostalive"
+		Address: "192.0.2.1"
+		Address6: "2001:db8::1"
+	}
+	if err := client.CreateHost(host); err != nil {
+		// handle error
+	}
+
+Not all functionality of the Icinga2 API is implemented.
+For more detail, see the [godocs][godocs].
+
+[godocs]: https://godocs.io/olowe.co/icinga
+
+## Why Another Package?
+
+The [icinga2 terraform provider][tf] uses the package [github.com/lrsmith/go-icinga2-api/iapi][lrsmith].
+As I read the source code I felt I wasn't reading idiomatic Go as detailed in documents like [Effective Go][effectivego].
+Other properties of `iapi` felt unusual to me:
+
+* The client to the API has the  confusing name `server`.
+* Every HTTP request creates a new http.Client.
+* Types have superfluous names like `HostStruct` instead of just `Host`.
+* Every response body from the API is decoded from JSON into one data strucutre, marshalled into JSON again, then unmarshalled back into another.
+* Every error returned from a function has a new name, rather than reusing the idiomatic name `err`.
+
+If I was being paid, I'd create a fork and contribute patches upstream to carefully avoid breaking functionality of existing users of `iapi`.
+
+But I'm not being paid ;)
+
+[effectivego]: https://go.dev/doc/effective_go
+[tf]: https://registry.terraform.io/providers/Icinga/icinga2/latest
+[lrsmith]: https://godocs.io/github.com/lrsmith/go-icinga2-api/iapi
blob - 192b34d6811b50bb362732c15399eae8ab09f608
blob + 2ccea26cf1583b0a427e2c2edda3753be3558ac8
--- icinga.go
+++ icinga.go
@@ -7,7 +7,7 @@
 //	if err != nil {
 //		// handle error
 //	}
-//	host, err := icinga.LookupHost("myserver.example.com")
+//	host, err := client.LookupHost("myserver.example.com")
 //	if err != nil {
 //		// handle error
 //	}