gotransip

README

gotransip - TransIP API client for Go

This is the Go client for the TransIP API. To use it you need an account with TransIP, enable API usage and setup a private API key.

NOTE: We keep the PHP version and golang version close as possible, but if something is not working 100% like you'd expect, please open an issue and of course: you're welcome to contribute!

Example usage

To print a list of your account's VPSes:

package main

import (
	"fmt"
	"github.com/transip/gotransip/v6"
	"github.com/transip/gotransip/v6/vps"
)

func main() {
	// create a new TransIP API client
	client, err := gotransip.NewClient(gotransip.ClientConfiguration{
		AccountName:    "accountName",
		PrivateKeyPath: "/path/to/api/private.key",
	})
	if err != nil {
		panic(err.Error())
	}
	vpsRepo := vps.Repository{Client: client}

	// get a list of your VPSes
	vpss, err := vpsRepo.GetAll()
	if err != nil {
		panic(err.Error())
	}

	pnRepo := vps.PrivateNetworkRepository{Client: client}
	// get a list of your private networks
	pns, err := pnRepo.GetAll()
	if err != nil {
		panic(err.Error())
	}

	// print name and description for each VPS
	for _, v := range vpss {
		fmt.Printf("vps: %s (%s)\n", v.Name, v.Description)
	}

	// print name and description for each private network
	for _, pn := range pns {
		fmt.Printf("privatenetwork: %s (%s)\n", pn.Name, pn.Description)
	}

	// order a new ubuntu 18.04 x8 vps, specifying a custom description,
	// so we can find out when the vps is delivered
	err = vpsRepo.Order(vps.Order{
		ProductName:       "vps-bladevps-x8",
		OperatingSystem:   "ubuntu-18.04",
		AvailabilityZone:  "ams0",
		Hostname:          "webserver01",
		Description:       "my-unique-description",
	})
	if err != nil {
		panic(err.Error())
	}
}

Documentation

For detailed descriptions of all functions, check out the TransIP API documentation. Details about the usage of the Go client can be found on pkg.go.dev.

Documentation

Overview

Package gotransip implements a client for the TransIP Rest API. This package is a complete implementation for communicating with the TransIP RestAPI. It covers resource calls available in the TransIP RestAPI Docs and it allows your project(s) to connect to the TransIP RestAPI easily. Using this package you can order, update and remove products from your TransIP account.

As of version 6.0 this package is no longer compatible with TransIP SOAP API because the library is now organized around REST. The SOAP API library versions 5.* are now deprecated and will no longer receive future updates.

Example

The following example uses the transip demo token in order to call the api with the test repository. For more information about authenticating with your own credentials, see the Authentication section.

package main

import (
	"github.com/transip/gotransip/v6"
	"github.com/transip/gotransip/v6/test"
	"log"
)

func main() {
	// Create a new client with the default demo client config, using the demo token
	client, err := gotransip.NewClient(gotransip.DemoClientConfiguration)
	if err != nil {
		panic(err)
	}

	testRepo := test.Repository{Client: client}
	log.Println("Executing test call to the api server")
	if err := testRepo.Test(); err != nil {
		panic(err)
	}
	log.Println("Test successful")
}

Authentication

If you want to tinker out with the api first without setting up your authentication, we defined a static DemoClientConfiguration. Which can be used to create a new client:

client, err := gotransip.NewClient(gotransip.DemoClientConfiguration)

Create a new client using a token:

client, err := gotransip.NewClient(gotransip.ClientConfiguration{
	Token:      "this_is_where_your_token_goes",
})

As tokens have a limited expiry time you can also request new tokens using the private key acquired from your transip control panel:

client, err := gotransip.NewClient(gotransip.ClientConfiguration{
	AccountName:    "accountName",
	PrivateKeyPath: "/path/to/api/private.key",
})

We also implemented a PrivateKeyReader option, for users that want to store their key elsewhere, not on a filesystem but on X datastore:

file, err := os.Open("/path/to/api/private.key")
if err != nil {
	panic(err.Error())
}
client, err := gotransip.NewClient(gotransip.ClientConfiguration{
	AccountName:      "accountName",
	PrivateKeyReader: file,
})

TokenCache

If you would like to keep a token between multiple client instantiations, you can provide the client with a token cache. If the file does not exist, it creates one for you

cache, err := authenticator.NewFileTokenCache("/tmp/path/to/gotransip_token_cache")
if err != nil {
	panic(err.Error())
}
client, err := gotransip.NewClient(gotransip.ClientConfiguration{
	AccountName:    "accountName",
	PrivateKeyPath: "/path/to/api/private.key",
	TokenCache:     cache
})

As long as a provided TokenCache adheres to the following interface, the client's authenticator is able to use it. This means you can also provide your own token cacher: for example, one that caches to etcd

type TokenCache interface {
	// Set will save a token by name
	Set(key string, token jwt.Token) error
	// Get returns a previously acquired token by name returned as jwt.Token
	// jwt is a subpackage in the gotransip package
	Get(key string) (jwt.Token, error)
}

Repositories

All resource calls as can be seen on https://api.transip.nl/rest/docs.html have been grouped in the following repositories, these are subpackages under the gotransip package:

availabilityzone.Repository
colocation.Repository
domain.Repository
haip.Repository
invoice.Repository
ipaddress.Repository
mailservice.Repository
kubernetes.Repository
product.Repository
test.Repository
traffic.Repository
vps.BigstorageRepository
vps.BlockstorageRepository
vps.PrivateNetworkRepository
vps.Repository

Such a repository can be initialised with a client as follows:

domainRepo := domain.Repository{Client: client}

Each repository has a bunch methods you can use to call get/modify/update resources in that specific subpackage. For example, here we get a list of domains from a transip account:

domains, err := domainRepo.GetAll()

Index

• Variables
• func NewClient(config ClientConfiguration) (repository.Client, error)
• type APIMode
• type CancellationRequest
• type CancellationTime
• type ClientConfiguration

Variables

var DemoClientConfiguration = ClientConfiguration{Token: authenticator.DemoToken}

DemoClientConfiguration is the default configuration to use when testing the demo mode of the transip api. Demo mode allows users to test without authenticating with their own credentials.

Functions

func NewClient

func NewClient(config ClientConfiguration) (repository.Client, error)

NewClient creates a new API client. optionally you could put a custom http.client in the configuration struct to allow for advanced features such as caching.

Types

type APIMode

type APIMode string

APIMode specifies in which mode the API is used. Currently this is only supports either readonly or readwrite

var (
	// APIModeReadOnly specifies that no changes can be made from API calls.
	// If you do try to order a product or change some data, the api will return an error.
	APIModeReadOnly APIMode = "readonly"
	// APIModeReadWrite specifies that changes can be made from API calls
	APIModeReadWrite APIMode = "readwrite"
)

type CancellationRequest

type CancellationRequest struct {
	EndTime CancellationTime `json:"endTime"`
}

CancellationRequest is used to generate a json body that contains the endTime property the endTime could either be 'end' or 'immediately'

type CancellationTime

type CancellationTime string

CancellationTime represents the possible ways of canceling a contract

var (
	// CancellationTimeEnd specifies to cancel the contract when the contract was
	// due to end anyway
	CancellationTimeEnd CancellationTime = "end"
	// CancellationTimeImmediately specifies to cancel the contract immediately
	CancellationTimeImmediately CancellationTime = "immediately"
)

type ClientConfiguration

type ClientConfiguration struct {
	// AccountName is the name of the account of the user, this is used in combination with a private key.
	// When requesting a new token, the account name will be part of the token request body
	AccountName string
	// URL is set by default to the transip api server
	// this is mainly used in tests to point to a mock server
	URL string
	// PrivateKeyPath is the filesystem location to the private key
	PrivateKeyPath string
	// For users that want the possibility to store their key elsewhere,
	// not on a filesystem but on X datastore
	PrivateKeyReader io.Reader
	// Token field gives users the option of providing their own acquired token,
	// for example when generated in the transip control panel
	Token string
	// TestMode is used when users want to tinker with the api without touching their real data.
	// So you can view your own data, order new products, but the actual order never happens.
	TestMode bool
	// optionally you can set your own HTTPClient
	// to set extra non default settings
	HTTPClient *http.Client
	// APIMode specifies in which mode the API is used. Currently this is only
	// supports either readonly or readwrite
	Mode APIMode
	// TokenCache is used to retrieve previously acquired tokens and saving new ones
	// If not set we do not use a cache to store the new acquired tokens
	TokenCache authenticator.TokenCache
	// TokenExpiration defines the lifetime of new tokens requested by the authenticator.
	// If unspecified, the default is 1 day.
	// This has no effect for tokens provided via the Token field.
	TokenExpiration time.Duration
	// TokenWhitelisted is used to indicate only whitelisted IP's may use the new tokens requested by the authenticator.
	// This has no effect for tokens provided via the Token field.
	TokenWhitelisted bool
}

ClientConfiguration stores the configuration of the API client