versioning: github.com/kataras/versioning Index | Files

package versioning

import "github.com/kataras/versioning"

Index

Package Files

deprecation.go doc.go group.go version.go versioning.go

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 Uses

❖
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 Uses

❖
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 Uses

❖
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 Uses

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

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

func NewMatcher Uses

❖
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 Uses

❖
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 Uses

❖
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 Uses

❖
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 Uses

❖
func (opts DeprecationOptions) ShouldHandle() bool

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

type Group Uses

❖
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 Uses

❖
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 Uses

❖
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 Uses

❖
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 Uses

❖
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 Uses

❖
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 Uses

❖
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`.

Package versioning imports 5 packages (graph). Updated 2019-12-23. Refresh now. Tools for package owners.