Merge branch 'master' into data-source-http-headers

Author: julienduchesne

README.md

@@ -1,17 +1,9 @@
-# DEPRECATED
+# Grafana HTTP API Client for Go
 
-:warning: :warning: :warning:
+This library provides a low-level client to access Grafana [HTTP API](https://grafana.com/docs/grafana/latest/http_api/).
 
-**This repository is no longer being maintained.**
-
-We're in the process of creating our next generation API clients.
-
-In the interim, further changes to this repository should only be to support
-[grafana/terraform-provider-grafana](https://github.com/grafana/terraform-provider-grafana).
-
----
-
-Grafana HTTP API Client for Go
+:warning: This repository is still active but not under heavy development.
+Contributions to this library offering support for the [Terraform provider for Grafana](https://github.com/grafana/terraform-provider-grafana) will be prioritized over generic ones.
 
 ## Tests
 

annotation.go

@@ -38,7 +38,7 @@ type GraphiteAnnotation struct {
 // Annotations fetches the annotations queried with the params it's passed
 func (c *Client) Annotations(params url.Values) ([]Annotation, error) {
 	result := []Annotation{}
-	err := c.request("GET", "/api/annotation", params, nil, &result)
+	err := c.request("GET", "/api/annotations", params, nil, &result)
 	if err != nil {
 		return nil, err
 	}

api_key.go

@@ -0,0 +1,67 @@
+package gapi
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"strconv"
+	"time"
+)
+
+type CreateAPIKeyRequest struct {
+	Name          string `json:"name"`
+	Role          string `json:"role"`
+	SecondsToLive int64  `json:"secondsToLive,omitempty"`
+}
+
+type CreateAPIKeyResponse struct {
+	// ID field only returned after Grafana v7.
+	ID   int64  `json:"id,omitempty"`
+	Name string `json:"name"`
+	Key  string `json:"key"`
+}
+
+type GetAPIKeysResponse struct {
+	ID         int64     `json:"id"`
+	Name       string    `json:"name"`
+	Role       string    `json:"role"`
+	Expiration time.Time `json:"expiration,omitempty"`
+}
+
+type DeleteAPIKeyResponse struct {
+	Message string `json:"message"`
+}
+
+// CreateAPIKey creates a new Grafana API key.
+func (c *Client) CreateAPIKey(request CreateAPIKeyRequest) (CreateAPIKeyResponse, error) {
+	response := CreateAPIKeyResponse{}
+
+	data, err := json.Marshal(request)
+	if err != nil {
+		return response, err
+	}
+
+	err = c.request("POST", "/api/auth/keys", nil, bytes.NewBuffer(data), &response)
+	return response, err
+}
+
+// GetAPIKeys retrieves a list of all API keys.
+func (c *Client) GetAPIKeys(includeExpired bool) ([]*GetAPIKeysResponse, error) {
+	response := make([]*GetAPIKeysResponse, 0)
+
+	query := url.Values{}
+	query.Add("includeExpired", strconv.FormatBool(includeExpired))
+
+	err := c.request("GET", "/api/auth/keys", query, nil, &response)
+	return response, err
+}
+
+// DeleteAPIKey deletes the Grafana API key with the specified ID.
+func (c *Client) DeleteAPIKey(id int64) (DeleteAPIKeyResponse, error) {
+	response := DeleteAPIKeyResponse{}
+
+	path := fmt.Sprintf("/api/auth/keys/%d", id)
+	err := c.request("DELETE", path, nil, nil, &response)
+	return response, err
+}

api_key_test.go

@@ -0,0 +1,68 @@
+package gapi
+
+import (
+	"testing"
+
+	"github.com/gobs/pretty"
+)
+
+const (
+	createAPIKeyJSON = `{"name":"key-name", "key":"mock-api-key"}`
+	deleteAPIKeyJSON = `{"message":"API key deleted"}`
+
+	getAPIKeysJSON = `[
+		{
+			"id": 1,
+			"name": "key-name-2",
+			"role": "Viewer"
+		},
+		{
+			"id": 2,
+			"name": "key-name-2",
+			"role": "Admin",
+			"expiration": "2021-10-30T10:52:03+03:00"
+		}
+	]`
+)
+
+func TestCreateAPIKey(t *testing.T) {
+	server, client := gapiTestTools(t, 200, createAPIKeyJSON)
+	defer server.Close()
+
+	req := CreateAPIKeyRequest{
+		Name:          "key-name",
+		Role:          "Viewer",
+		SecondsToLive: 0,
+	}
+
+	res, err := client.CreateAPIKey(req)
+	if err != nil {
+		t.Error(err)
+	}
+
+	t.Log(pretty.PrettyFormat(res))
+}
+
+func TestDeleteAPIKey(t *testing.T) {
+	server, client := gapiTestTools(t, 200, deleteAPIKeyJSON)
+	defer server.Close()
+
+	res, err := client.DeleteAPIKey(int64(1))
+	if err != nil {
+		t.Error(err)
+	}
+
+	t.Log(pretty.PrettyFormat(res))
+}
+
+func TestGetAPIKeys(t *testing.T) {
+	server, client := gapiTestTools(t, 200, getAPIKeysJSON)
+	defer server.Close()
+
+	res, err := client.GetAPIKeys(true)
+	if err != nil {
+		t.Error(err)
+	}
+
+	t.Log(pretty.PrettyFormat(res))
+}

client.go

@@ -12,6 +12,7 @@ import (
 	"os"
 	"path"
 	"strconv"
+	"time"
 
 	"github.com/hashicorp/go-cleanhttp"
 )
@@ -33,6 +34,8 @@ type Config struct {
 	Client *http.Client
 	// OrgID provides an optional organization ID, ignored when using APIKey, BasicAuth defaults to last used org
 	OrgID int64
+	// NumRetries contains the number of attempted retries
+	NumRetries int
 }
 
 // New creates a new Grafana client.
@@ -59,18 +62,49 @@ func New(baseURL string, cfg Config) (*Client, error) {
 }
 
 func (c *Client) request(method, requestPath string, query url.Values, body io.Reader, responseStruct interface{}) error {
-	r, err := c.newRequest(method, requestPath, query, body)
-	if err != nil {
-		return err
-	}
+	var (
+		req          *http.Request
+		resp         *http.Response
+		err          error
+		bodyContents []byte
+	)
+
+	// retry logic
+	for n := 0; n <= c.config.NumRetries; n++ {
+		req, err = c.newRequest(method, requestPath, query, body)
+		if err != nil {
+			return err
+		}
 
-	resp, err := c.client.Do(r)
-	if err != nil {
-		return err
-	}
-	defer resp.Body.Close()
+		// Wait a bit if that's not the first request
+		if n != 0 {
+			time.Sleep(time.Second * 5)
+		}
+
+		resp, err = c.client.Do(req)
 
-	bodyContents, err := ioutil.ReadAll(resp.Body)
+		// If err is not nil, retry again
+		// That's either caused by client policy, or failure to speak HTTP (such as network connectivity problem). A
+		// non-2xx status code doesn't cause an error.
+		if err != nil {
+			continue
+		}
+
+		defer resp.Body.Close()
+
+		// read the body (even on non-successful HTTP status codes), as that's what the unit tests expect
+		bodyContents, err = ioutil.ReadAll(resp.Body)
+
+		// if there was an error reading the body, try again
+		if err != nil {
+			continue
+		}
+
+		// Exit the loop if we have something final to return. This is anything < 500, if it's not a 429.
+		if resp.StatusCode < http.StatusInternalServerError && resp.StatusCode != http.StatusTooManyRequests {
+			break
+		}
+	}
 	if err != nil {
 		return err
 	}
@@ -79,6 +113,7 @@ func (c *Client) request(method, requestPath string, query url.Values, body io.R
 		log.Printf("response status %d with body %v", resp.StatusCode, string(bodyContents))
 	}
 
+	// check status code.
 	if resp.StatusCode >= 400 {
 		return fmt.Errorf("status: %d, body: %v", resp.StatusCode, string(bodyContents))
 	}

client_test.go

@@ -58,7 +58,7 @@ func TestNew_invalidURL(t *testing.T) {
 
 	expected := "parse \"://my-grafana.com\": missing protocol scheme"
 	if err.Error() != expected {
-		t.Errorf("expected error: %v; got: %s", expected, err.Error())
+		t.Errorf("expected error: %v; got: %s", expected, err)
 	}
 }
 
@@ -68,7 +68,7 @@ func TestRequest_200(t *testing.T) {
 
 	err := client.request("GET", "/foo", url.Values{}, nil, nil)
 	if err != nil {
-		t.Errorf(err.Error())
+		t.Error(err)
 	}
 }
 
@@ -78,7 +78,7 @@ func TestRequest_201(t *testing.T) {
 
 	err := client.request("GET", "/foo", url.Values{}, nil, nil)
 	if err != nil {
-		t.Errorf(err.Error())
+		t.Error(err)
 	}
 }
 
@@ -89,7 +89,7 @@ func TestRequest_400(t *testing.T) {
 	expected := `status: 400, body: {"foo":"bar"}`
 	err := client.request("GET", "/foo", url.Values{}, nil, nil)
 	if err.Error() != expected {
-		t.Errorf("expected error: %v; got: %s", expected, err.Error())
+		t.Errorf("expected error: %v; got: %s", expected, err)
 	}
 }
 
@@ -100,7 +100,23 @@ func TestRequest_500(t *testing.T) {
 	expected := `status: 500, body: {"foo":"bar"}`
 	err := client.request("GET", "/foo", url.Values{}, nil, nil)
 	if err.Error() != expected {
-		t.Errorf("expected error: %v; got: %s", expected, err.Error())
+		t.Errorf("expected error: %v; got: %s", expected, err)
+	}
+}
+
+func TestRequest_badURL(t *testing.T) {
+	server, client := gapiTestTools(t, 200, `{"foo":"bar"}`)
+	baseURL, err := url.Parse("bad-url")
+	if err != nil {
+		t.Fatal(err)
+	}
+	client.baseURL = *baseURL
+	defer server.Close()
+
+	expected := `Get "bad-url/foo": unsupported protocol scheme ""`
+	err = client.request("GET", "/foo", url.Values{}, nil, nil)
+	if err.Error() != expected {
+		t.Errorf("expected error: %v; got: %s", expected, err)
 	}
 }
 
@@ -113,7 +129,7 @@ func TestRequest_200Unmarshal(t *testing.T) {
 	}{}
 	err := client.request("GET", "/foo", url.Values{}, nil, &result)
 	if err != nil {
-		t.Fatal(err.Error())
+		t.Fatal(err)
 	}
 
 	if result.Foo != "bar" {
@@ -130,7 +146,7 @@ func TestRequest_200UnmarshalPut(t *testing.T) {
 	}
 	data, err := json.Marshal(u)
 	if err != nil {
-		t.Fatal(err.Error())
+		t.Fatal(err)
 	}
 
 	result := struct {
@@ -140,7 +156,7 @@ func TestRequest_200UnmarshalPut(t *testing.T) {
 	q.Add("a", "b")
 	err = client.request("PUT", "/foo", q, bytes.NewBuffer(data), &result)
 	if err != nil {
-		t.Errorf(err.Error())
+		t.Error(err)
 	}
 
 	if result.Name != "mike" {

dashboard.go

@@ -28,6 +28,9 @@ type Dashboard struct {
 	Model     map[string]interface{} `json:"dashboard"`
 	Folder    int64                  `json:"folderId"`
 	Overwrite bool                   `json:"overwrite"`
+
+	// This is only used when creating a new dashboard, it will always be empty when getting a dashboard.
+	Message string `json:"message"`
 }
 
 // SaveDashboard is a deprecated method for saving a Grafana dashboard. Use NewDashboard.

datasource.go

@@ -12,6 +12,7 @@ import (
 // DataSource represents a Grafana data source.
 type DataSource struct {
 	ID     int64  `json:"id,omitempty"`
+	UID    string `json:"uid,omitempty"`
 	Name   string `json:"name"`
 	Type   string `json:"type"`
 	URL    string `json:"url"`
@@ -84,7 +85,8 @@ type JSONData struct {
 	TimeInterval string `json:"timeInterval,omitempty"`
 
 	// Used by Elasticsearch
-	EsVersion                  int64  `json:"esVersion,omitempty"`
+	// From Grafana 8.x esVersion is the semantic version of Elasticsearch.
+	EsVersion                  string `json:"esVersion,omitempty"`
 	TimeField                  string `json:"timeField,omitempty"`
 	Interval                   string `json:"interval,omitempty"`
 	LogMessageField            string `json:"logMessageField,omitempty"`