api

Documentation

Overview

Package api provides an way to interact with Elastic Cloud APIs, including ESS, ECE and ESSP.

The preferred way to interact with the Elastic Cloud APIs is by creating a new API pointer by using the `api.NewAPI()` constructor. To do so, you'll need to pass an `auth.Writer` as the API.Config parameter, and an `http.Client`, optionally the API endpoint (Host), if not specified it defaults to ESS API. To create a new `auth.Writer`, you can use one of (APIKey or UserLogin) from the auth package ("github.com/elastic/cloud-sdk-go/auth"). Optionally, `auth.NewAuthWriter()` can be used in applications where the credentials are specified by the user.

ess, err := api.NewAPI(api.Config{
	Client:        new(http.Client),
	AuthWriter:    auth.APIKey("some-apikey"),
})

if err != nil {
	panic(err)
}

// List the user's deployments via the `deploymentapi` package (Recommended).

res, err := deploymentapi.List(deploymentapi.ListParams{API: ess.V1API})

if err != nil {
	panic(err)
}

var encoder = json.NewEncoder(os.Stdout)

if err := encoder.Encode(res); err != nil {
	panic(err)
}

// List the user's deployments using the autogenerated APIs.

res, err = ess.V1API.Deployments.ListDeployments(

deployments.NewListDeploymentsParams(),
ess.AuthWriter,

)

if err != nil {
	// Errors returned by the auto-generated API should be unpacked
	// with `api.UnwrapError`.
	panic(api.UnwrapError(err))
}

if err := encoder.Encode(res.Payload); err != nil {
	panic(err)
}

// APIs which are region-bound, need that region to be specified as a // `context.Context` in the API operation when using the auto-generated APIs // directly.

res, err := ess.V1API.Stack.GetVersionStacks(

stack.NewGetVersionStacksParams().
WithContext(api.WithRegion(context.Background(), "us-east-1")),

ess.AuthWriter, )

if err != nil {
	panic(api.UnwrapError(err))
}

if err := encoder.Encode(res.Payload); err != nil {
	panic(err)
}

Index

• Constants
• Variables
• func AddTypeConsumers(rtime *client.Runtime) *client.Runtime
• func GetContextRegion(ctx context.Context) (string, bool)
• func LoginUser(instance *API, writer io.Writer) error
• func NewTransport(rt http.RoundTripper, cfg TransportConfig) http.RoundTripper
• func ReturnErrOnly(_ interface{}, err error) error
• func UnwrapError(err error) error
• func WithRegion(ctx context.Context, region string) context.Context
• type API
  • func NewAPI(c Config) (*API, error)
  • func NewDebugMock(o io.Writer, res ...mock.Response) *API
  • func NewMock(res ...mock.Response) *API
• type AuthWriter
• type CloudClientRuntime
  • func NewCloudClientRuntime(c Config) (*CloudClientRuntime, error)
  • func (r *CloudClientRuntime) Submit(op *runtime.ClientOperation) (interface{}, error)
• type Config
  • func (c *Config) Validate() error
• type DebugTransport
  • func NewDebugTransport(transport http.RoundTripper, o io.Writer, obscure bool) *DebugTransport
  • func (t *DebugTransport) RoundTrip(rreq *http.Request) (*http.Response, error)
• type ErrCatchTransport
  • func NewErrCatchTransport(rt http.RoundTripper) *ErrCatchTransport
  • func (e *ErrCatchTransport) RoundTrip(req *http.Request) (*http.Response, error)
• type TransportConfig
• type UserAgentTransport
  • func NewUserAgentTransport(rt http.RoundTripper, agent string) *UserAgentTransport
  • func (ua *UserAgentTransport) RoundTrip(req *http.Request) (*http.Response, error)
• type VerboseSettings
  • func (settings VerboseSettings) Validate() error

Constants

const ESSEndpoint = "https://api.elastic-cloud.com"

ESSEndpoint is the Elasticsearch Service endpoint.

const (
	// RegionBasePath is for /platform operations which require a Region to be
	// passed as of an API call context.Context. Previously used to create a
	// global client per API instance, now used on a per-operation basis.
	RegionBasePath = "/api/v1/regions/%s"
)

const Version = "2.6.0"

Version contains the ECE API version compatibility for the current auto-generated client and models. This needs to be updated every time a new "api/apidocs.json" file added and the client and models are re-generated. Even though the Bugfix version is specified, the general support statement is on the minor version, i.e: 2.4.2 means that all the 2.4 branch is supported, expecting some potentially unfixed bugs when ECE version is the same feature version bug higher bugfix version.

Variables

var (
	// DefaultWriteMockHeaders can be used for test assertions.
	DefaultWriteMockHeaders = map[string][]string{
		"Accept":        {"application/json"},
		"Authorization": {"ApiKey dummy"},
		"Content-Type":  {"application/json"},
		"User-Agent":    {fmt.Sprint("cloud-sdk-go/", Version)},
	}

	// DefaultReadMockHeaders can be used for test assertions.
	DefaultReadMockHeaders = map[string][]string{
		"Accept":        {"application/json"},
		"Authorization": {"ApiKey dummy"},
		"User-Agent":    {fmt.Sprint("cloud-sdk-go/", Version)},
	}

	// DefaultMockHost can be used for test assertions
	DefaultMockHost = "mock.elastic.co"
)

var DefaultBasePath = client.DefaultBasePath

DefaultBasePath is used as the base prefix for the API.

var (
	// DefaultTimeout is used when TransportConfig.Transport is not specified.
	DefaultTimeout = 30 * time.Second
)

var DefaultTransport = new(ErrCatchTransport)

DefaultTransport can be used by clients which rely on the apierror.Unwrap Can obtain the underlying http.Response is returned with a StatusCode not defined within the swagger spec from which the models have been generated. Meaning this is a small hack which allows http.Response.Body to be accessed. See pkg/api/apierror for details on how apierror.Unwrap works. Note that using this variable directly won't allow any of the http.Transport settings to be overridden. To customize the transport further, please use NewTransport()

var DefaultUserAgent = "cloud-sdk-go/" + Version

DefaultUserAgent is used in UserAgentTransport when the agent is not set. It defaults to the project name + the current committed version.

Functions

func AddTypeConsumers

func AddTypeConsumers(rtime *client.Runtime) *client.Runtime

AddTypeConsumers adds the missing consumers and producers to the client.Runtime. Even though a pointer is passed it is returned too.

func GetContextRegion

func GetContextRegion(ctx context.Context) (string, bool)

GetContextRegion returns the region from a specified context, if any.

func LoginUser

func LoginUser(instance *API, writer io.Writer) error

LoginUser logs in a user when its AuthWriter is of type *auth.UserLogin. Additionally, calls the RefreshToken pethod in *auth.UserLogin launching a background Go routine which will keep the JWT token always valid.

func NewTransport

func NewTransport(rt http.RoundTripper, cfg TransportConfig) http.RoundTripper

NewTransport constructs a new http.RoundTripper from its config. If rt is *http.Transport then it will be wrapped with *ErrCatchTransport. See more information on the GoDoc help for that type. Additionally, that transport is wrapped in *UserAgentTransport to be able to configure a User-Agent for all outgoing requests.

func ReturnErrOnly

func ReturnErrOnly(_ interface{}, err error) error

ReturnErrOnly is used to strip the first return argument of a function call

func UnwrapError

func UnwrapError(err error) error

UnwrapError Deprecated: unpacks an error message returned from a client API call. Deprecated: in favour of apierror.Unwrap().

func WithRegion

func WithRegion(ctx context.Context, region string) context.Context

WithRegion creates a new context with a region value. This needs to be used when calling any auto-generated platform APIs directly. client..Stack.GetVersionStacks(stack.NewGetVersionStacksParams().

WithContext(api.WithRegion(context.Background(), "us-east-1")), nil)

Types

type API

type API struct {
	V1API      *client.Rest
	AuthWriter auth.Writer
}

API contains all of the API clients and authentication objects necessary for the EC API

func NewAPI

func NewAPI(c Config) (*API, error)

NewAPI initializes the API clients from an API config that it receives

func NewDebugMock

func NewDebugMock(o io.Writer, res ...mock.Response) *API

NewDebugMock creates a new api.API from a list of Responses. Defaults to a dummy APIKey for authentication, which is not checked. Additionally adds the DebugTransport so that the responses go to the configured io.Writer.

func NewMock

func NewMock(res ...mock.Response) *API

NewMock creates a new api.API from a list of Responses. Defaults to a dummy APIKey for authentication, which is not checked

type AuthWriter

type AuthWriter auth.Writer

AuthWriter wraps the runtime.ClientAuthInfoWriter interface adding a method to Auth generic http.Request. This type alias is used to maintain API compatibility.

type CloudClientRuntime

type CloudClientRuntime struct {
	// contains filtered or unexported fields
}

CloudClientRuntime wraps runtimeclient.Runtime to allow operations to use a transport depending on the operation which is being performed.

func NewCloudClientRuntime

func NewCloudClientRuntime(c Config) (*CloudClientRuntime, error)

NewCloudClientRuntime creates a CloudClientRuntime from the config. Using the configured region (if any) to instantiate two different client.Runtime. If there's no region specified in the config then both are regionless.

func (*CloudClientRuntime) Submit

func (r *CloudClientRuntime) Submit(op *runtime.ClientOperation) (interface{}, error)

Submit calls either the regionRuntime or the regionless runtime depending on which operation is being performed. Any API call to /deployments will use a regionless runtime while all others will use a region (if specified).

type Config

type Config struct {
	Client     *http.Client
	AuthWriter auth.Writer
	Host       string

	// SkipTLSVerify will not perform any TLS/SSL verification.
	SkipTLSVerify bool

	// SkipLogin skips validating the user / password with the instanced API
	// when AuthWriter equals *auth.UserLogin.
	SkipLogin bool

	// ErrorDevice is used to send errors to prevent cluttering the output.
	ErrorDevice io.Writer

	VerboseSettings

	// Timeout for all of the API calls performed through the API structure.
	Timeout time.Duration

	// UserAgent if specified, it sets the user agent on all outgoing requests.
	UserAgent string
}

Config contains the API config

func (*Config) Validate

func (c *Config) Validate() error

Validate returns an error if the config is invalid

type DebugTransport

type DebugTransport struct {
	// contains filtered or unexported fields
}

DebugTransport is an http.RoundTripper that keeps track of the in-flight request and implements hooks to report HTTP tracing events.

func NewDebugTransport

func NewDebugTransport(transport http.RoundTripper, o io.Writer, obscure bool) *DebugTransport

NewDebugTransport factory for DebugTransport

func (*DebugTransport) RoundTrip

func (t *DebugTransport) RoundTrip(rreq *http.Request) (*http.Response, error)

RoundTrip wraps http.DefaultTransport.RoundTrip to keep track of the current request.

type ErrCatchTransport

type ErrCatchTransport struct {
	// contains filtered or unexported fields
}

ErrCatchTransport is an http.RoundTripper that which allows the http.Response to be accessed in certain types of wrapped errors returned by autogenerated code. See pkg/api/apierror for details on how apierror.Unwrap works.

func NewErrCatchTransport

func NewErrCatchTransport(rt http.RoundTripper) *ErrCatchTransport

NewErrCatchTransport initialises an ErrCatchTransport. See GoDoc for more help on this type.

func (*ErrCatchTransport) RoundTrip

func (e *ErrCatchTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip wraps http.DefaultTransport.RoundTrip to keep track of the current request.

type TransportConfig

type TransportConfig struct {
	// When SkipTLSVerify the TLS verification is completely skipped.
	SkipTLSVerify bool

	// ErrorDevice where any error or notices will be sent.
	ErrorDevice io.Writer

	// Can enable a debug RoundTripper which dumps the request and responses to
	// the configured device.
	VerboseSettings

	// Timeout for the Transport net.Dialer.
	Timeout time.Duration

	// UserAgent if specified, it sets the user agent on all outgoing requests.
	UserAgent string
}

TransportConfig is meant to be used so an http.RoundTripper is constructed with the appropriate settings.

type UserAgentTransport

type UserAgentTransport struct {
	// contains filtered or unexported fields
}

UserAgentTransport wraps an http.RoundTripper and adds an User-Agent header to all requests which are processed through the structure.

func NewUserAgentTransport

func NewUserAgentTransport(rt http.RoundTripper, agent string) *UserAgentTransport

NewUserAgentTransport initializes a new UserAgentTransport

func (*UserAgentTransport) RoundTrip

func (ua *UserAgentTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip wraps http.DefaultTransport.RoundTrip to keep track of the current request.

type VerboseSettings

type VerboseSettings struct {
	Device  io.Writer
	Verbose bool

	// RedactAuth replaces the contents of the Authorization header with:
	// "[REDACTED]".
	RedactAuth bool
}

VerboseSettings define the behaviour of verbosity.

func (VerboseSettings) Validate

func (settings VerboseSettings) Validate() error

Validate ensures the settings are usable.