sdk

README

Turnkey GO SDK

The Turnkey Go SDK is an early tool for interacting with the Turnkey API.

There is much work to be done, but it is completly usable in its current form. The main thing to keep in mind is that each requests needs to be manually provided the client.Authenticator.

Usage

API key

In order to use the SDK, you will need an API key. When creating API keys, the private key never leaves the local system, but the public key must be registered to your Turnkey account.

The easiest way to manage your API keys is with the Turnkey CLI, but you can also create one using this SDK. See this example.

Example

import (
	"fmt"
	"log"

	"github.com/mkhoatd/go-sdk2"
	"github.com/mkhoatd/go-sdk2/pkg/api/client/sessions"
	"github.com/mkhoatd/go-sdk2/pkg/api/models"
)

func main() {
	// NB: make sure to create and register an API key, first.
	client, err := sdk.New("") // your local API key name
	if err != nil {
		log.Fatal("failed to create new SDK client:", err)
	}

	p := sessions.NewGetWhoamiParams().WithBody(&models.GetWhoamiRequest{
		OrganizationID: client.DefaultOrganization(),
	})

	resp, err := client.V0().Sessions.GetWhoami(p, client.Authenticator)
	if err != nil {
		log.Fatal("failed to make WhoAmI request:", err)
	}

	fmt.Println("UserID: ", *resp.Payload.UserID)
}

Development

Updating the SDK

With Nix

1. Install Nix: https://nixos.org/download.html
2. Run nix develop to get a new nix shell
3. Update the swagger file in api/ with a new one
4. Run make generate

Without Nix

The following assumes you have Go 1.20 installed locally:

1. Install go-swagger:

brew tap go-swagger/go-swagger
brew install go-swagger

1. Update the swagger file in api/ with a new one
2. Run make generate

Custom Templates

While custom templates should be avoided where possible, sometimes it's worth the extra maintenance burden to provide a more streamlined UX. To use a custom template, copy the original template from the go-swagger repo to the templates directory

Current Modifications

// file: schemavalidator.gotmpl

// mod: less verbose enum variants
// note: seems strange, but there's an edgecase with the current logic where '_' is not supported leading to names like AllCapsALLCAPSALLTHETIME
-      {{- $variant := print $gotype (pascalize (cleanupEnumVariant .)) }}
+      {{- $variant := print ( pascalize ( camelcase (printf "%q" . ))) }}

// mod: typed and iterable enum variants
-var {{ camelize .Name }}Enum []interface{}
+var {{ pascalize .Name }}Enum []{{ template "dereffedSchemaType" . }}
-    {{ camelize .Name }}Enum = append({{ camelize .Name }}Enum, v)
+    {{ pascalize .Name }}Enum = append({{ pascalize .Name }}Enum, v)
-  if err := validate.EnumCase(path, location, value, {{ camelize .Name }}Enum, {{ if .IsEnumCI }}false{{ else }}true{{ end }}); err != nil {
+  if err := validate.EnumCase(path, location, value, {{ pascalize .Name }}Enum, {{ if .IsEnumCI }}false{{ else }}true{{ end }}); err != nil {

Documentation

Overview

Package sdk provides a Go SDK with which to interact with the Turnkey API service.

Index

• func NewHTTPClient(formats strfmt.Registry) *client.TurnkeyAPI
• type Authenticator
  • func (auth *Authenticator) AuthenticateRequest(req runtime.ClientRequest, reg strfmt.Registry) (err error)
• type Client
  • func New(keyname string) (*Client, error)
  • func (c *Client) DefaultOrganization() *string
  • func (c *Client) V0() *client.TurnkeyAPI

Functions

func NewHTTPClient

func NewHTTPClient(formats strfmt.Registry) *client.TurnkeyAPI

NewHTTPClient returns a new base HTTP API client. Most users will call New() instead.

Types

type Authenticator

type Authenticator struct {
	// Key optionally overrides the globally-parsed APIKeypair with a custom key.
	Key *apikey.Key
}

Authenticator provides a runtime.ClientAuthInfoWriter for use with the swagger API client.

func (*Authenticator) AuthenticateRequest

func (auth *Authenticator) AuthenticateRequest(req runtime.ClientRequest, reg strfmt.Registry) (err error)

AuthenticateRequest implements runtime.ClientAuthInfoWriter. It adds the X-Stamp header to the request based by generating the Stamp with the request body and API key.

type Client

type Client struct {
	// Client is the base HTTP API Client.
	Client *client.TurnkeyAPI

	// Authenticator provides a client option authentication provider which should be attached to every API request as a clientOption.
	Authenticator *Authenticator

	// APIKey is the API key to be used for API request signing.
	APIKey *apikey.Key
}

Client provides a handle by which to interact with the Turnkey API.

func New

func New(keyname string) (*Client, error)

New returns a new API Client with the given API key name from the default keystore.

func (*Client) DefaultOrganization

func (c *Client) DefaultOrganization() *string

DefaultOrganization returns the first organization found in the APIKey's set of organizations.

func (*Client) V0

func (c *Client) V0() *client.TurnkeyAPI

V0 returns the raw initial Turnkey API client. WARNING: this is a temporary API which requires a bit more work to use than the one which will be eventually offered.