1 package icinga provides a client to the Icinga2 HTTP API.
2 
3 [![godocs.io](http://godocs.io/olowe.co/icinga?status.svg)](http://godocs.io/olowe.co/icinga)
4 
5 ## Quick Start
6 
7 A Client manages interaction with an Icinga2 server.
8 It is created using Dial. Provide the address, in `host:port` form, API username and password, and a `http.Client`:
9 
10 	client, err := icinga.Dial("icinga.example.com:5665", "icinga", "secret", http.DefaultClient)
11 	if err != nil {
12 		// handle error
13 	}
14 
15 Icinga2 servers in the wild often serve self-signed certificates which
16 fail verification by Go's tls client. To ignore the errors, Dial the server
17 with a modified `http.Client`:
18 
19 	t := http.DefaultTransport.(*http.Transport)
20 	t.TLSClientConfig = &tls.Config{InsecureSkipVerify: true}
21 	c := http.DefaultClient
22 	c.Transport = t
23 	client, err := icinga.Dial(addr, user, pass, c)
24 	if err != nil {
25 		// handle error
26 	}
27 
28 Methods on `Client` provide API actions like looking up users and creating hosts:
29 
30 	user, err := client.LookupUser("oliver")
31 	if err != nil {
32 		// handle error
33 	}
34 	host := Host{
35 		Name: "myserver.example.com",
36 		CheckCommand: "hostalive"
37 		Address: "192.0.2.1"
38 		Address6: "2001:db8::1"
39 	}
40 	if err := client.CreateHost(host); err != nil {
41 		// handle error
42 	}
43 
44 Not all functionality of the Icinga2 API is implemented.
45 For more detail, see the [godocs][godocs].
46 
47 [godocs]: https://godocs.io/olowe.co/icinga
48 
49 ## Why Another Package?
50 
51 The [icinga2 terraform provider][tf] uses the package [github.com/lrsmith/go-icinga2-api/iapi][lrsmith].
52 As I read the source code I felt I wasn't reading idiomatic Go as detailed in documents like [Effective Go][effectivego].
53 Other properties of `iapi` felt unusual to me:
54 
55 * The client to the API has the  confusing name `server`.
56 * Every HTTP request creates a new http.Client.
57 * Types have superfluous names like `HostStruct` instead of just `Host`.
58 * Every response body from the API is decoded from JSON into one data strucutre, marshalled into JSON again, then unmarshalled back into another.
59 * Every error returned from a function has a new name, rather than reusing the idiomatic name `err`.
60 
61 If I was being paid, I'd create a fork and contribute patches upstream to carefully avoid breaking functionality of existing users of `iapi`.
62 
63 But I'm not being paid ;)
64 
65 [effectivego]: https://go.dev/doc/effective_go
66 [tf]: https://registry.terraform.io/providers/Icinga/icinga2/latest
67 [lrsmith]: https://godocs.io/github.com/lrsmith/go-icinga2-api/iapi