Doc Grafana client

src/grafana/client.go

@@ -8,13 +8,18 @@ import (
 	"strings"
 )
 
+// Client implements a Grafana API client, and contains the instance's base URL
+// and API key, along with an HTTP client used to request the API.
 type Client struct {
 	BaseURL    string
 	APIKey     string
 	httpClient *http.Client
 }
 
+// NewClient returns a new Grafana API client from a given base URL and API key.
 func NewClient(baseURL string, apiKey string) (c *Client) {
+	// Grafana doesn't support double slashes in the API routes, so we strip the
+	// last slash if there's one, because request() will append one anyway.
 	if strings.HasSuffix(baseURL, "/") {
 		baseURL = baseURL[:len(baseURL)-1]
 	}
@@ -26,52 +31,81 @@ func NewClient(baseURL string, apiKey string) (c *Client) {
 	}
 }
 
+// request preforms an HTTP request on a given endpoint, with a given method and
+// body. The endpoint is the Grafana API route to request, without the "/api/"
+// part. If the request doesn't require a body, the function has to be called
+// with "nil" as the "body" parameter.
+// Returns the response body (as a []byte containing JSON data).
+// Returns an error if there was an issue initialising the request, performing
+// it or reading the response body. Also returns an error on non-200 response
+// status codes. If the status code is 404, a standard error is returned, if the
+// status code is neither 200 nor 404 an error of type httpUnkownError is
+// returned.
 func (c *Client) request(method string, endpoint string, body []byte) ([]byte, error) {
 	url := c.BaseURL + "/api/" + endpoint
 
+	// Create the request
 	req, err := http.NewRequest(method, url, bytes.NewBuffer(body))
 	if err != nil {
 		return nil, err
 	}
 
+	// Add the API key to the request as an Authorization HTTP header
 	authHeader := fmt.Sprintf("Bearer %s", c.APIKey)
 	req.Header.Add("Authorization", authHeader)
 
+	// If the request isn't a GET, the body will be sent as JSON, so we need to
+	// append the appropriate header
 	if method != "GET" {
 		req.Header.Add("Content-Type", "application/json")
 	}
 
+	// Perform the request
 	resp, err := c.httpClient.Do(req)
 	if err != nil {
 		return nil, err
 	}
 
+	// Read the response body
 	respBody, err := ioutil.ReadAll(resp.Body)
 	if err != nil {
 		return nil, err
 	}
 
+	// Return an error if the Grafana API responded with a non-200 status code.
+	// We perform this here because http.Client.Do() doesn't return with an
+	// error on non-200 status codes.
 	if resp.StatusCode != http.StatusOK {
 		if resp.StatusCode == http.StatusNotFound {
 			err = fmt.Errorf("%s not found (404)", url)
 		} else {
+			// Return an httpUnkownError error if the status code is neither 200
+			// nor 404
 			err = newHttpUnknownError(resp.StatusCode)
 		}
 	}
 
+	// Return the response body along with the error. This allows callers to
+	// process httpUnkownError errors by displaying an error message located in
+	// the response body along with the data contained in the error.
 	return respBody, err
 }
 
+// httpUnkownError represents an HTTP error, created from an HTTP response where
+// the status code is neither 200 nor 404.
 type httpUnkownError struct {
 	StatusCode int
 }
 
+// newHttpUnknownError creates and returns a new httpUnkownError error using
+// the provided status code.
 func newHttpUnknownError(statusCode int) *httpUnkownError {
 	return &httpUnkownError{
 		StatusCode: statusCode,
 	}
 }
 
+// Error implements error.Error().
 func (e *httpUnkownError) Error() string {
 	return fmt.Sprintf("Unknown HTTP error: %d", e.StatusCode)
 }

src/grafana/dashboards.go

@@ -5,6 +5,8 @@ import (
 	"fmt"
 )
 
+// dbSearchResponse represents an element of the response to a dashboard search
+// query
 type dbSearchResponse struct {
 	ID      int      `json:"id"`
 	Title   string   `json:"title"`
@@ -14,24 +16,36 @@ type dbSearchResponse struct {
 	Starred bool     `json:"isStarred"`
 }
 
-type dbUpdateRequest struct {
+// dbCreateOrUpdateRequest represents the request sent to create or update a
+// dashboard
+type dbCreateOrUpdateRequest struct {
 	Dashboard rawJSON `json:"dashboard"`
 	Overwrite bool    `json:"overwrite"`
 }
 
-type dbUpdateResponse struct {
+// dbCreateOrUpdateResponse represents the response sent by the Grafana API to
+// a dashboard creation or update. All fields described from the Grafana
+// documentation aren't located in this structure because there are some we
+// don't need.
+type dbCreateOrUpdateResponse struct {
 	Status  string `json:"success"`
 	Version int    `json:"version,omitempty"`
 	Message string `json:"message,omitempty"`
 }
 
+// Dashboard represents a Grafana dashboard, with its JSON definition, slug and
+// current version.
 type Dashboard struct {
 	RawJSON []byte
 	Slug    string
 	Version int
 }
 
+// UnmarshalJSON tells the JSON parser how to unmarshal JSON data into an
+// instance of the Dashboard structure.
+// Returns an error if there was an issue unmarshalling the JSON.
 func (d *Dashboard) UnmarshalJSON(b []byte) (err error) {
+	// Define the structure of what we want to parse
 	var body struct {
 		Dashboard rawJSON `json:"dashboard"`
 		Meta      struct {
@@ -40,9 +54,11 @@ func (d *Dashboard) UnmarshalJSON(b []byte) (err error) {
 		} `json:"meta"`
 	}
 
+	// Unmarshal the JSON into the newly defined structure
 	if err = json.Unmarshal(b, &body); err != nil {
 		return
 	}
+	// Define all fields with their corresponding value.
 	d.Slug = body.Meta.Slug
 	d.Version = body.Meta.Version
 	d.RawJSON = body.Dashboard
@@ -50,6 +66,10 @@ func (d *Dashboard) UnmarshalJSON(b []byte) (err error) {
 	return
 }
 
+// GetDashboardsURIs requests the Grafana API for the list of all dashboards,
+// then returns the dashboards' URIs. An URI will look like "db/[dashboard slug]".
+// Returns an error if there was an issue requesting the URIs or parsing the
+// response body.
 func (c *Client) GetDashboardsURIs() (URIs []string, err error) {
 	resp, err := c.request("GET", "search", nil)
 
@@ -66,6 +86,11 @@ func (c *Client) GetDashboardsURIs() (URIs []string, err error) {
 	return
 }
 
+// GetDashboard requests the Grafana API for a dashboard identified by a given
+// URI (using the same format as GetDashboardsURIs).
+// Returns the dashboard as an instance of the Dashboard structure.
+// Returns an error if there was an issue requesting the dashboard or parsing
+// the response body.
 func (c *Client) GetDashboard(URI string) (db *Dashboard, err error) {
 	body, err := c.request("GET", "dashboards/"+URI, nil)
 	if err != nil {
@@ -77,8 +102,18 @@ func (c *Client) GetDashboard(URI string) (db *Dashboard, err error) {
 	return
 }
 
+// CreateOrUpdateDashboard takes a given JSON content (as []byte) and create the
+// dashboard if it doesn't exist on the Grafana instance, else updates the
+// existing one. The Grafana API decides whether to create or update based on the
+// "id" attribute in the dashboard's JSON: If it's unkown or null, it's a
+// creation, else it's an update.
+// The slug is only used for error reporting, and can differ from the
+// dashboard's actual slug in its JSON content. However, it's recommended to use
+// the same in both places.
+// Returns an error if there was an issue generating the request body, performing
+// the request or decoding the response's body.
 func (c *Client) CreateOrUpdateDashboard(slug string, contentJSON []byte) (err error) {
-	reqBody := dbUpdateRequest{
+	reqBody := dbCreateOrUpdateRequest{
 		Dashboard: rawJSON(contentJSON),
 		Overwrite: true,
 	}
@@ -99,7 +134,7 @@ func (c *Client) CreateOrUpdateDashboard(slug string, contentJSON []byte) (err e
 		}
 	}
 
-	var respBody dbUpdateResponse
+	var respBody dbCreateOrUpdateResponse
 	if err = json.Unmarshal(respBodyJSON, &respBody); err != nil {
 		return
 	}