Back to godoc.org
github.com/kataras/versioning

Package versioning

v0.0.0 (cdabd69)
Latest Go to latest
Published: Dec 22, 2019 | License: MIT | Module: github.com/kataras/versioning

Index

Package Files

Constants

const (
	// AcceptVersionHeaderKey is the header key of "Accept-Version".
	AcceptVersionHeaderKey = "Accept-Version"
	// AcceptHeaderKey is the header key of "Accept".
	AcceptHeaderKey = "Accept"
	// AcceptHeaderVersionValue is the Accept's header value search term the requested version.
	AcceptHeaderVersionValue = "version"
)

Variables

var DefaultDeprecationOptions = DeprecationOptions{
	WarnMessage: "WARNING! You are using a deprecated version of this API.",
}

DefaultDeprecationOptions are the default deprecation options, it defaults the "X-API-Warn" header to a generic message.

var HeaderTimeFormat = "Mon, 02 Jan 2006 15:04:05 GMT"

HeaderTimeFormat is the time format that will be used to send DeprecationOptions's DeprectationDate time.

var (

	// NotFound is the key that can be used inside a `Map` or inside `context.WithValue(r.Context(), versioning.contextKey, versioning.NotFound)`
	// to tell that a version wasn't found, therefore the not found handler should handle the request instead.
	NotFound = contextKey.(string) + ".notfound"
)
var NotFoundHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

	w.WriteHeader(http.StatusNotImplemented)
	w.Write(versionNotFoundText)
})

NotFoundHandler is the default version not found handler that is executed from `NewMatcher` when no version is registered as available to dispatch a resource.

func Deprecated

func Deprecated(handler http.Handler, options DeprecationOptions) http.Handler

Deprecated marks a specific handler as a deprecated. Deprecated can be used to tell the clients that a newer version of that specific resource is available instead.

func GetVersion

func GetVersion(r *http.Request) string

GetVersion returns the current request version.

By default the `GetVersion` will try to read from: - "Accept" header, i.e Accept: "application/json; version=1.0" - "Accept-Version" header, i.e Accept-Version: "1.0"

However, the end developer can also set a custom version for a handler trough a middleware by using the request's context's value for versions (see `WithVersion` for further details on that).

func If

func If(v string, is string) bool

If reports whether the "version" is a valid match to the "is". The "is" should be a version constraint like ">= 1, < 3".

func Match

func Match(r *http.Request, expectedVersion string) bool

Match reports whether the current version matches the "expectedVersion".

func NewMatcher

func NewMatcher(versions Map) http.Handler

NewMatcher creates a single handler which decides what handler should be executed based on the requested version.

Use the `NewGroup` if you want to add many routes under a specific version.

See `Map` and `NewGroup` too.

func RegisterGroups

func RegisterGroups(mux StdMux, notFoundHandler http.Handler, groups ...*Group) map[string]http.Handler

RegisterGroups registers one or more groups to an `net/http#ServeMux` if not nil, and returns the routes. Map's key is the request path from `Group#Handle` and value is the `http.Handler`. See `NewGroup` and `NotFoundHandler` too.

func WithVersion

func WithVersion(ctx context.Context, version string) context.Context

WithVersion creates the new context that contains a passed version. Example of how you can change the default behavior to extract a requested version (which is by headers) from a "version" url parameter instead: func(w http.ResponseWriter, r *http.Request) { // &version=1

r = r.WithContext(versioning.WithVersion(r.Context(), r.URL.Query().Get("version")))
nextHandler.ServeHTTP(w,r)

}

type DeprecationOptions

type DeprecationOptions struct {
	WarnMessage     string
	DeprecationDate time.Time
	DeprecationInfo string
}

DeprecationOptions describes the deprecation headers key-values. - "X-API-Warn": options.WarnMessage - "X-API-Deprecation-Date": time.Now().Format("Mon, 02 Jan 2006 15:04:05 GMT") - "X-API-Deprecation-Info": options.DeprecationInfo

func (DeprecationOptions) ShouldHandle

func (opts DeprecationOptions) ShouldHandle() bool

ShouldHandle reports whether the deprecation headers should be present or no.

type Group

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

Group is a group of version-based routes. One version per one or more routes.

func NewGroup

func NewGroup(version string) *Group

NewGroup returns a ptr to Group based on the given "version".

See `Handle` and `RegisterGroups` for more.

func (*Group) Deprecated

func (g *Group) Deprecated(options DeprecationOptions) *Group

Deprecated marks this group and all its versioned routes as deprecated versions of that endpoint. It can be called in the end just before `RegisterGroups` or first by `NewGroup(...).Deprecated(...)`. It returns itself.

func (*Group) Handle

func (g *Group) Handle(path string, handler http.Handler)

Handle registers a versioned route to the group. A call of `RegisterGroups` is necessary in order to register the actual routes when the group is complete.

See `RegisterGroups` for more.

func (*Group) HandleFunc

func (g *Group) HandleFunc(path string, handlerFn func(w http.ResponseWriter, r *http.Request))

HandleFunc registers a versioned route to the group. A call of `RegisterGroups` is necessary in order to register the actual routes when the group is complete.

See `RegisterGroups` for more.

type Map

type Map map[string]http.Handler

Map is a map of version to handler. A handler per version or constraint, the key can be something like ">1, <=2" or just "1".

type StdMux

type StdMux interface{ Handle(string, http.Handler) }

StdMux is an interface which types like `net/http#ServeMux` implements in order to register handlers per path.

See `RegisterGroups`.

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier