import "github.com/kataras/versioning"
deprecation.go doc.go group.go version.go versioning.go
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" )
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.
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.
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).
If reports whether the "version" is a valid match to the "is". The "is" should be a version constraint like ">= 1, < 3".
Match reports whether the current version matches the "expectedVersion".
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(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.
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 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 (opts DeprecationOptions) ShouldHandle() bool
ShouldHandle reports whether the deprecation headers should be present or no.
type Group struct {
// contains filtered or unexported fields
}
Group is a group of version-based routes. One version per one or more routes.
NewGroup returns a ptr to Group based on the given "version".
See `Handle` and `RegisterGroups` for more.
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.
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.
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.
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".
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.