Manifold API Client Bindings

View the API swagger doc.

Go Bindings

Sample client:

manifold-api/example/main.go

Lines 3 to 64 in 8c3b8df

	package main
	import (
	"context"
	"flag"
	"fmt"
	"log"
	"os"
	"github.com/softiron/manifold-api/client"
	"github.com/softiron/manifold-api/manifold"
	)
	func main() {
	fs := flag.NewFlagSet("example", flag.ExitOnError)
	// Both flag.FlagSet and cobra's pflag.FlagSet implement client.flagSet.
	// NewOptions adds the flags that all REST clients will need.
	opts := client.NewOptions(fs, "", manifold.PortNumber)
	if err := fs.Parse(os.Args[1:]); err != nil {
	log.Fatal(err)
	}
	// If running on the same host as the dashboard and running as the admin (or
	// root) user, it is possible to grab HC admin username and password and use
	// that to Login.
	//
	// But this is not an option for opensource code as the auth package is part
	// of the sifi module.
	//
	// opts.Username, opts.Password, err = auth.DashboardAdmin()
	// if err != nil {
	// log.Fatal(err)
	// }
	c := manifold.NewClient(opts)
	// Set c.Logger to attach a logger to the client. The slog package
	// implements this interface (structured logger new to Go 1.21). All REST
	// calls are logged at the debug level.
	// The Login call is optional as any unauthorized call will trigger a Login.
	//
	// c.Login(context.Background())
	// Request information about the first instance.
	resp, err := c.Cloud.Instance(context.Background(), 0)
	if err != nil {
	log.Fatal(err)
	}
	// This could also be written as below. The manifold.Client is composed of
	// more than a dozen services to organize calls into logical groups. It is
	// possible to pass a single service to a function to limit what groups of
	// calls are available.
	//
	// resp, err := c.Cloud.InstanceService.Instance(context.Background(), 0)
	fmt.Printf("Instance %v is called: %v", 0, resp.Instance.Name)
	}

Manual Use

Login

The API uses Basic Authentication where the client does a GET login and includes a username and password in the Authorization header.

Included in the response is an access token in the form of a JSON Web Token with a 10 minute TTL.

Tokens

Access Token

All subsequest requests must use the access token in the Authorization header, for example:

Authorization: Bearer dht467bv4570flw2r

If a request uses an expired token the request will return HTTP code 401 (unauthorized). This is a hint to the client to re-login and obtain a new access token.

Refresh Token

The following is true for development releases of the API only, and is not a released feature.

In addition to returning an access token, a login will also return a refresh token in the form of a JSON Web Token with a one year TTL. This token can be used in place of Basic Authentication to re-login and obtain a new access and refresh token.

Refresh tokens are single use, so once used the server will reject it (401) even if the TTL has not expired. If the refresh token has expired or was lost a re-login must use Basic Authentication with a username and password.

Usage of refresh tokens is optional, and the client can instead re-login using Basic Authentication.