icinga

commit 6456042b9dd325c6b9b1e246acac3a21bfae58fe
parent 9ea5152367e4cfb31a1d08d23200575dc64058c4
Author: Oliver Lowe <o@olowe.co>
Date:   Fri,  7 Jan 2022 09:30:44 +1100

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

Diffstat:
M
README.md
 | 
60
+++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
M
icinga.go
 | 
2
+-

2 files changed, 56 insertions(+), 6 deletions(-)
diff --git a/README.md b/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
+	}
+
+Methods on `Client` provide API actions like looking up users and creating hosts:
+
+	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`.
 
-## Why?
+But I'm not being paid ;)
 
-The terraform provider...
+[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
diff --git a/icinga.go b/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
 //	}