versioning

Documentation

Index

• Constants
• Variables
• func Deprecated(handler context.Handler, options DeprecationOptions) context.Handler
• func GetVersion(ctx *context.Context) string
• func Handler(version string) context.Handler
• func If(v string, is string) bool
• func Match(ctx *context.Context, expectedVersion string) bool
• func NewMatcher(versions Map) context.Handler
• func SetVersion(ctx *context.Context, constraint string)
• func WriteDeprecated(ctx *context.Context, options DeprecationOptions)
• type DeprecationOptions
  • func (opts DeprecationOptions) ShouldHandle() bool
• type Group
  • func NewGroup(r router.Party, version string) *Group
  • func (g *Group) Deprecated(options DeprecationOptions) *Group
• type Map

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"

	// Key is the context key of the version, can be used to manually modify the "requested" 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(ctx iris.Context) { // &version=1
	// 	ctx.Values().Set(versioning.Key, ctx.URLParamDefault("version", "1"))
	// 	ctx.Next()
	// }
	//
	// DEPRECATED: Use:
	// version := ctx.URLParamDefault("version", "1")
	// versioning.SetVersion(ctx, version) instead.
	Key = "iris.api.version"
	// NotFound is the key that can be used inside a `Map` or inside `ctx.SetVersion(versioning.NotFound)`
	// to tell that a version wasn't found, therefore the not found handler should handle the request instead.
	NotFound = "iris.api.version.notfound"
)

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 ErrNotFound = errors.New("version not found")

ErrNotFound reports whether a requested version does not match with any of the server's implemented ones.

var NotFoundHandler = func(ctx *context.Context) {

	ctx.StopWithPlainError(501, ErrNotFound)
}

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

Functions

func Deprecated

func Deprecated(handler context.Handler, options DeprecationOptions) context.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(ctx *context.Context) 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 via a middleware by using the context's store key for versions (see `Key` for further details on that).

See `SetVersion` too.

func Handler

func Handler(version string) context.Handler

Handler returns a handler which stop the execution when the given "version" does not match with the requested one.

func If

func If(v string, is string) bool

If reports whether the "version" is matching to the "is". the "is" can be a constraint like ">= 1, < 3".

func Match

func Match(ctx *context.Context, expectedVersion string) bool

Match acts exactly the same as `If` does but instead it accepts a Context, so it can be called by a handler to determinate the requested version.

If matched then it sets the "X-API-Version" response header and stores the matched version into Context (see `GetVersion` too).

func NewMatcher

func NewMatcher(versions Map) context.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 SetVersion

func SetVersion(ctx *context.Context, constraint string)

SetVersion force-sets the API Version. It can be used inside a middleware. See `GetVersion` too.

func WriteDeprecated

func WriteDeprecated(ctx *context.Context, options DeprecationOptions)

WriteDeprecated writes the deprecated response headers based on the given "options". It can be used inside a middleware.

See `Deprecated` to wrap an existing handler instead.

Types

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": context.FormatTime(ctx, options.DeprecationDate)) - "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 {
	router.Party
	// contains filtered or unexported fields
}

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

func NewGroup

func NewGroup(r router.Party, version string) *Group

NewGroup returns a ptr to Group based on the given "version". It sets the API Version for the "r" Party.

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.

type Map

type Map map[string]context.Handler

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