speakeasy

README

speakeasy-go-sdk

Speakeasy is your API Platform team as a service. Use our drop in SDK to manage all your API Operations including embeds for request logs and usage dashboards, test case generation from traffic, and understanding API drift.

The Speakeasy Go SDK for evaluating API requests/responses. Compatible with any API framework implemented on top of Go's native http library.

Requirements

Supported routers:

• gorilla/mux
• go-chi/chi
• http.DefaultServerMux

We also support custom HTTP frameworks:

• gin-gonic/gin
• labstack/echo

Usage

Speakeasy uses Go Modules to manage dependencies.

go get github.com/speakeasy-api/speakeasy-go-sdk

Minimum configuration

Sign up for free on our platform. After you've created a workspace and generated an API key enable Speakeasy in your API as follows:

Configure Speakeasy at the start of your main() function:

import "github.com/speakeasy-api/speakeasy-go-sdk"

func main() {
	// Configure the Global SDK
	speakeasy.Configure(speakeasy.Config {
		APIKey:		"YOUR API KEY HERE",	// retrieve from Speakeasy API dashboard.
		ApiID:		"YOUR API ID HERE", 	// custom Api ID to associate captured requests with.
		VersionID:	"YOUR VERSION ID HERE",	// custom Version ID to associate captured requests with.
	})

    // Associate the SDK's middleware with your router
	r := mux.NewRouter()
	r.Use(speakeasy.Middleware)
}

Build and deploy your app and that's it. Your API is being tracked in the Speakeasy workspace you just created and will be visible on the dashboard next time you log in. Visit our docs site to learn more.

Advanced configuration

The Speakeasy SDK provides both a global and per Api configuration option. If you want to use the SDK to track multiple Apis or Versions from the same service you can configure individual instances of the SDK, like so:

import "github.com/speakeasy-api/speakeasy-go-sdk"

func main() {
	// Configure a new instance of the SDK
	sdkInstance := speakeasy.New(speakeasy.Config {
		APIKey:		"YOUR API KEY HERE",	// retrieve from Speakeasy API dashboard.
		ApiID:		"YOUR API ID HERE", 	// custom Api ID to associate captured requests with.
		VersionID:	"YOUR VERSION ID HERE",	// custom Version ID to associate captured requests with.
	})

    // Associate the SDK's middleware with your router
	r := mux.NewRouter()
	r.Use(sdkInstance.Middleware)
}

This allows multiple instances of the SDK to be associated with different routers or routes within your service.

On-Premise Configuration

The SDK provides a way to redirect the requests it captures to an on-premise deployment of the Speakeasy Platform. This is done through the use of environment variables listed below. These are to be set in the environment of your services that have integrated the SDK:

• SPEAKEASY_SERVER_URL - The url of the on-premise Speakeasy Platform's GRPC Endpoint. By default this is grpc.prod.speakeasyapi.dev:443.
• SPEAKEASY_SERVER_SECURE - Whether or not to use TLS for the on-premise Speakeasy Platform. By default this is true set to SPEAKEASY_SERVER_SECURE="false" if you are using an insecure connection.

Request Matching

The Speakeasy SDK out of the box will do its best to match requests to your provided OpenAPI Schema. It does this by extracting the path template used by one of the supported routers or frameworks above for each request captured and attempting to match it to the paths defined in the OpenAPI Schema, for example:

r := mux.NewRouter()
r.Use(sdkInstance.Middleware)
r.HandleFunc("/v1/users/{id}", MyHandler) // The path template "/v1/users/{id}" is captured automatically by the SDK

This isn't always successful or even possible, meaning requests received by Speakeasy will be marked as unmatched, and potentially not associated with your Api, Version or ApiEndpoints in the Speakeasy Dashboard.

To help the SDK in these situations you can provide path hints per request handler that match the paths in your OpenAPI Schema:

func MyHandler(w http.ResponseWriter, r *http.Request) {
	// Provide a path hint for the request using the OpenAPI Path Templating format: https://swagger.io/specification/#path-templating-matching
	ctrl := speakeasy.MiddlewareController(req)
	ctrl.PathHint("/v1/users/{id}")
	
	// the rest of your handlers code
}

Notes:
Wildcard path matching in Echo & Chi will end up with a OpenAPI path paramater called {wildcard} which will only match single level values represented by the wildcard. This is a restriction of the OpenAPI spec (Detail Here). For example:

chi template: /user/{id}/path/* => openapi template: /user/{id}/path/{wildcard}

And in the above example a path like /user/1/path/some/sub/path won't match but /user/1/path/somesubpathstring will, as / characters are not matched in path paramters by the OpenAPI spec.

Capturing Customer IDs

To help associate requests with customers/users of your APIs you can provide a customer ID per request handler:

func MyHandler(w http.ResponseWriter, r *http.Request) {
	ctrl := speakeasy.MiddlewareController(req)
	ctrl.CustomerID("a-customers-id") // This customer ID will be used to associate this instance of a request with your customers/users
	
	// the rest of your handlers code
}

Note: This is not required, but is highly recommended. By setting a customer ID you can easily associate requests with your customers/users in the Speakeasy Dashboard, powering filters in the Request Viewer (Coming soon).

Documentation

Index

• Variables
• func Configure(config Config)
• func EchoMiddleware(next echo.HandlerFunc) echo.HandlerFunc
• func GinMiddleware(c *gin.Context)
• func Middleware(next http.Handler) http.Handler
• func MiddlewareController(r *http.Request) *controller
• func NewCaptureWriter(origResW http.ResponseWriter, maxBuffer int) *captureWriter
• type Config
• type Speakeasy
  • func New(config Config) *Speakeasy
  • func (s *Speakeasy) EchoMiddleware(next echo.HandlerFunc) echo.HandlerFunc
  • func (s *Speakeasy) GinMiddleware(c *gin.Context)
  • func (s *Speakeasy) Middleware(next http.Handler) http.Handler

Variables

var (
	// ErrAPIKeyMissing is returned when the API Key is not provided at configuration time.
	ErrAPIKeyMissing = errors.New("API key is required")
	// ErrAPIIdMissing is returned when the Api ID is not provided at configuration time.
	ErrApiIDMissing = errors.New("ApiID is required")
	// ErrApiIDMalformed is returned when the Api ID is invalid.
	ErrApiIDMalformed = errors.New("ApiID is malformed")
	// ErrVersionIDMissing is returned when the Version ID is not provided at configuration time.
	ErrVersionIDMissing = errors.New("VersionID is required")
	// ErrVersionIDMalformed is returned when the Version ID is invalid.
	ErrVersionIDMalformed = errors.New("VersionID is malformed")
)

Functions

func Configure

func Configure(config Config)

Configure allows you to configure the default instance of the Speakeasy SDK. Use this if you will use the same API Key for all connected APIs.

func EchoMiddleware

func EchoMiddleware(next echo.HandlerFunc) echo.HandlerFunc

EchoMiddleware setups up the default SDK instance to start capturing requests from the echo http framework.

func GinMiddleware

func GinMiddleware(c *gin.Context)

GinMiddleware setups up the default SDK instance to start capturing requests from the gin http framework.

func Middleware

func Middleware(next http.Handler) http.Handler

Middleware setups up the default SDK instance to start capturing requests from routers that support http.Handlers. Currently only gorilla/mux, go-chi/chi routers and the http.DefaultServerMux are supported for automatically capturing path hints. Otherwise path hints can be supplied by a handler through the speakeasy MiddlewareController.

func MiddlewareController

func MiddlewareController(r *http.Request) *controller

MiddlewareController will return the speakeasy middleware controller from the current request, if the current request is monitored by the speakeasy middleware.

func NewCaptureWriter

func NewCaptureWriter(origResW http.ResponseWriter, maxBuffer int) *captureWriter

Types

type Config

type Config struct {
	// APIKey is the API Key obtained from the Speakeasy platform for capturing requests to a particular workspace.
	APIKey string
	// ApiID is the ID of the Api to associate any requests captured by this instance of the SDK to.
	ApiID string
	// VersionID is the ID of the Api Version to associate any requests captured by this instance of the SDK to.
	VersionID  string
	GRPCDialer func() func(context.Context, string) (net.Conn, error)
}

Config provides configuration for the Speakeasy SDK.

type Speakeasy

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

Speakeasy is the concrete type for the Speakeasy SDK. Don't instantiate this directly, use Configure() or New() instead.

func New

func New(config Config) *Speakeasy

New creates a new instance of the Speakeasy SDK. This allows you to create multiple instances of the SDK for specifying different API Keys for different APIs.

func (*Speakeasy) EchoMiddleware

func (s *Speakeasy) EchoMiddleware(next echo.HandlerFunc) echo.HandlerFunc

EchoMiddleware setups the current instance of the SDK to start capturing requests from the echo http framework.

func (*Speakeasy) GinMiddleware

func (s *Speakeasy) GinMiddleware(c *gin.Context)

GinMiddleware setups the current instance of the SDK to start capturing requests from the gin http framework.

func (*Speakeasy) Middleware

func (s *Speakeasy) Middleware(next http.Handler) http.Handler

Middleware setups the current instance of the SDK to start capturing requests from routers that support http.Handlers. Currently only gorilla/mux, go-chi/chi routers and the http.DefaultServerMux are supported for automatically capturing path hints. Otherwise path hints can be supplied by a handler through the speakeasy MiddlewareController.