Grafana HTTP OpenAPI Client for Go

This HTTP Go client for Grafana is generated from Grafana's OpenAPI specification using swagger for Go.

Both code and non-code contributions are very welcome - please feel free to open an issue or PR in this repository if you spot a possible improvement!

Dependencies

This project uses bingo (located in .bingo/), a tool to automate the versioning of Go packages. Here, bingo manages verison of swagger for Go version so that the client generation is consistent.

[Required] In order to generate the client, you must have installed bingo locally. Then, get swagger at the version specified in bingo's swagger.mod.

go install github.com/bwplotka/bingo@latest
bingo get swagger

Generate the client

Once bingo & swagger are installed (see Dependencies), generate the client for all Grafana APIs, with the following make command:

make generate-client

This runs the Swagger generation command.

To generate the client for a specific Grafana API, find the name of its tag and model in the Grafana OpenAPI specification. Then, set those as environment variables and run the command to generate it:

export API_TAG=folders
export MODEL=Folder
make generate-client

How to use custom templates

In order to generate the client, go-swagger uses default templates. These templates can be customised to add custom configuration that are applied each time the client is generated.

For more information, check out the go-swagger docs on how to use custom templates. The default template definitions for the client can be found in go-swagger/generator/templates/client/.

In this project, the custom templates can be found in templates/. They are provided to the generation command through the flag --template-dir=templates.

The custom templates provide added functionality for things such as authentication, TLS/SSL, retries, and custom error handling.

Build the client

Configuration

The client has the following friendly configuration options:

import goapi "github.com/grafana/grafana-openapi-client-go/client"

cfg := &goapi.TransportConfig{
    // Host is the doman name or IP address of the host that serves the API.
    Host:       "localhost:3000",
    // BasePath is the URL prefix for all API paths, relative to the host root.
    BasePath:   "/api",
    // Schemes are the transfer protocols used by the API (http or https).
    Schemes:    []string{"http"},
    // APIKey is an optional API key or service account token.
    APIKey:     os.Getenv("API_ACCESS_TOKEN"),
    // BasicAuth is optional basic auth credentials.
    BasicAuth:  url.UserPassword("admin", "admin"),
    // OrgID provides an optional organization ID.
    // OrgID is only supported with BasicAuth since API keys are already org-scoped.
    OrgID:      1,
    // TLSConfig provides an optional configuration for a TLS client
    TLSConfig:  &tls.Config{},
    // NumRetries contains the optional number of attempted retries
    NumRetries: 3,
    // RetryTimeout sets an optional time to wait before retrying a request
    RetryTimeout: 0,
    // RetryStatusCodes contains the optional list of status codes to retry
    // Use "x" as a wildcard for a single digit (default: [429, 5xx])
    RetryStatusCodes: []string{"420", "5xx"},
    // HTTPHeaders contains an optional map of HTTP headers to add to each request
    HTTPHeaders: map[string]string{},
}

client := goapi.NewHTTPClientWithConfig(strfmt.Default, cfg)

Examples

Checkout how the Grafana Terraform Provider initialises and uses the client here.

The goswagger documentation have more information about how to build a client.

Roadmap

We are planning a few improvements around processes such as automation, testing, release, and integration into other dependencies. Some of this work is tracked here.