versionware

Documentation

Overview

Package versionware provides routing and middleware for building versioned HTTP services.

Index

• Constants
• type Handler
  • func NewHandler(vhs ...VersionHandler) *Handler
  • func (h *Handler) HandleErrors(errFunc VersionErrorHandler)
  • func (h *Handler) Resolve(requested vervet.Version) (*vervet.Version, http.Handler, error)
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type VersionErrorHandler
• type VersionHandler

Examples

• Handler

Constants

const (
	// HeaderSnykVersionRequested is a response header acknowledging the API
	// version that was requested.
	HeaderSnykVersionRequested = "snyk-version-requested"

	// HeaderSnykVersionServed is a response header indicating the actual API
	// version that was matched and served the response.
	HeaderSnykVersionServed = "snyk-version-served"
)

Types

type Handler

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

Handler is a multiplexing http.Handler that dispatches requests based on the version query parameter according to vervet's API version matching rules.

Example

package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
	"net/http/httptest"

	"github.com/snyk/vervet"
	"github.com/snyk/vervet/versionware"
)

func main() {
	h := versionware.NewHandler([]versionware.VersionHandler{{
		Version: vervet.MustParseVersion("2021-10-01"),
		Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			if _, err := w.Write([]byte("oct")); err != nil {
				panic(err)
			}
		}),
	}, {
		Version: vervet.MustParseVersion("2021-11-01"),
		Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			if _, err := w.Write([]byte("nov")); err != nil {
				panic(err)
			}
		}),
	}, {
		Version: vervet.MustParseVersion("2021-09-01"),
		Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			if _, err := w.Write([]byte("sept")); err != nil {
				panic(err)
			}
		}),
	}}...)

	s := httptest.NewServer(h)
	defer s.Close()

	resp, err := s.Client().Get(s.URL + "?version=2021-10-31")
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	respBody, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}

	fmt.Print(string(respBody))
}

Output:

oct

func NewHandler

func NewHandler(vhs ...VersionHandler) *Handler

NewHandler returns a new Handler instance, which handles versioned requests with the matching version handler.

func (*Handler) HandleErrors

func (h *Handler) HandleErrors(errFunc VersionErrorHandler)

HandleErrors changes the default error handler to the provided function. It may be used to control the format of versioning error responses.

func (*Handler) Resolve

func (h *Handler) Resolve(requested vervet.Version) (*vervet.Version, http.Handler, error)

Resolve returns the resolved version and its associated http.Handler for the requested version.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements http.Handler with the handler matching the version query parameter on the request. If no matching version is found, responds 404.

type VersionErrorHandler

type VersionErrorHandler func(w http.ResponseWriter, r *http.Request, status int, err error)

VersionErrorHandler defines a function which handles versioning error responses in requests.

type VersionHandler

type VersionHandler struct {
	Version vervet.Version
	Handler http.Handler
}

VersionHandler expresses a pairing of Version and http.Handler.