mittwaldv2

Documentation

Index

• func New(ctx context.Context, opts ...ClientOption) (generatedv2.Client, error)
• type ClientOption
  • func WithAccessToken(token string) ClientOption
  • func WithAccessTokenAndRefresh(token, refreshToken string, expiration time.Time) ClientOption
  • func WithAccessTokenAndRefreshFunc(token string, expiration time.Time, refreshFunc httpclient.RefreshFunc) ClientOption
  • func WithAccessTokenFromEnv() ClientOption
  • func WithAccessTokenRetrievalKey(userID string, accessTokenRetrievalKey string) ClientOption
  • func WithBaseURL(baseURL string) ClientOption
  • func WithEventualConsistency() ClientOption
  • func WithExtensionSecret(extensionInstanceID string, extensionSecret string) ClientOption
  • func WithHTTPClient(client httpclient.RequestRunner) ClientOption
  • func WithRequestLogging(logger *slog.Logger, logRequestBodies, logResponseBodies bool) ClientOption
  • func WithUsernamePassword(email, password string) ClientOption

Examples

• New (AccessTokenFromEnvironment)

Functions

func New

func New(ctx context.Context, opts ...ClientOption) (generatedv2.Client, error)

New creates a new mittwaldv2 API client.

Use the "opts" parameter to configure things like authentication and other specific client-side behaviours.

Please note that this function may fail with an error, because some authentication mechanisms actively communicate with the API

Example (AccessTokenFromEnvironment)

package main

import (
	"context"
	"fmt"

	"github.com/mittwald/api-client-go/mittwaldv2"
	"github.com/mittwald/api-client-go/mittwaldv2/generated/clients/userclientv2"
)

func main() {
	ctx := context.Background()

	client, err := mittwaldv2.New(ctx, mittwaldv2.WithAccessTokenFromEnv())
	if err != nil {
		panic(err)
	}

	me, _, err := client.User().GetUser(ctx, userclientv2.GetUserRequest{UserID: "self"})
	if err != nil {
		panic(err)
	}

	fmt.Printf("Hello %s!", me.Person.FirstName)
}

Types

type ClientOption

type ClientOption func(ctx context.Context, runner httpclient.RequestRunner) (httpclient.RequestRunner, error)

ClientOption defines a generic data type for modifying the behaviour of the mittwald v2 API client.

Client behaviours are implemented as a chain of middlewares that are wrapped around a HTTP client implementation (or more precisely, any implementation of the httpclient.RequestRunner interface, which is also implemented by the default *http.Client type).

func WithAccessToken

func WithAccessToken(token string) ClientOption

WithAccessToken adds a static access token to all executed requests. The access token needs to be obtained ahead-of-time.

func WithAccessTokenAndRefresh

func WithAccessTokenAndRefresh(token, refreshToken string, expiration time.Time) ClientOption

WithAccessTokenAndRefresh supports automatically refreshing API tokens.

Clients with this option will refresh API tokens automatically when they expire.

func WithAccessTokenAndRefreshFunc

func WithAccessTokenAndRefreshFunc(token string, expiration time.Time, refreshFunc httpclient.RefreshFunc) ClientOption

WithAccessTokenAndRefreshFunc supports automatically refreshing API tokens.

Clients with this option will refresh API tokens automatically when they expire.

func WithAccessTokenFromEnv

func WithAccessTokenFromEnv() ClientOption

WithAccessTokenFromEnv is a convenience wrapper around WithAccessToken that automatically retrieves the API token from the process environment variables.

func WithAccessTokenRetrievalKey

func WithAccessTokenRetrievalKey(userID string, accessTokenRetrievalKey string) ClientOption

WithAccessTokenRetrievalKey authenticates a user using an "access token retrieval key".

This is a special mechanism for one-click-authenticating users that are redirected to an mStudio extension 1.

Clients authenticated with this method will refresh their API tokens automatically.

func WithBaseURL

func WithBaseURL(baseURL string) ClientOption

WithBaseURL allows you to override the base URL that is used for HTTP requests.

If omitted, this will default to "https://api.mittwald.de/v2" as base URL. During regular usage, there should be no need to change the base URL, but it may be useful during testing.

func WithEventualConsistency

func WithEventualConsistency() ClientOption

WithEventualConsistency enables client-side support for the eventual-consistency behaviour as documented in 1.

func WithExtensionSecret

func WithExtensionSecret(extensionInstanceID string, extensionSecret string) ClientOption

WithExtensionSecret authenticates an mStudio extension (i.e. not a user).

Clients authenticated with this method will refresh their API tokens automatically.

func WithHTTPClient

func WithHTTPClient(client httpclient.RequestRunner) ClientOption

WithHTTPClient allows you to override the base HTTP client to use for all requests.

In the simplest case, this may be an *http.Client, which implements the httpclient.RequestRunner interface. However, the interface also allows you to supply your own implementation.

NOTE: When used with other ClientOption's, this one must be the first.

func WithRequestLogging

func WithRequestLogging(logger *slog.Logger, logRequestBodies, logResponseBodies bool) ClientOption

WithRequestLogging adds a logging middleware to the request runner chain allowing you to log all executed HTTP requests in a slog.Logger of your choice.

Be mindful of the log{Request,Response}Bodies parameters; these will cause the logger to print the full request bodies without redaction, which may easily leak sensitive data.

func WithUsernamePassword

func WithUsernamePassword(email, password string) ClientOption

WithUsernamePassword authenticates the API user using their actual email address+password combination.

NOTE: This will only work then MFA is *not* activated for a user. In general, it is recommended to use API tokens, instead of username+password.