Iris v11.1.0 Release Notes
Release Date: 2018-11-18 // over 5 years ago-
Su, 18 November 2018 | v11.1.0
PR: #1130
๐ This release contains a new feature for versioning your Iris APIs. The initial motivation and feature request came by #1129.
๐ฆ The versioning package provides semver versioning for your APIs. It implements all the suggestions written at api-guidelines and more.
๐ฆ The version comparison is done by the go-version package. It supports matching over patterns like
">= 1.0, < 3"
and etc.๐ Features
- per route version matching, a normal iris handler with "switch" cases via Map for version => handler
- ๐ per group versioned routes and deprecation API
- ๐ version matching like ">= 1.0, < 2.0" or just "2.0.1" and etc.
- ๐ version not found handler (can be customized by simply adding the versioning.NotFound: customNotMatchVersionHandler on the Map)
- ๐ version is retrieved from the "Accept" and "Accept-Version" headers (can be customized via middleware)
- respond with "X-API-Version" header, if version found.
- ๐ deprecation options with customizable "X-API-Warn", "X-API-Deprecation-Date", "X-API-Deprecation-Info" headers via
Deprecated
wrapper.
Get version
Current request version is retrieved by
versioning.GetVersion(ctx)
.0๏ธโฃ By default the
GetVersion
will try to read from:Accept
header, i.eAccept: "application/json; version=1.0"
Accept-Version
header, i.eAccept-Version: "1.0"
You can also set a custom version for a handler via a middleware by using the context's store values.
For example:func(ctx iris.Context) { ctx.Values().Set(versioning.Key, ctx.URLParamDefault("version", "1.0")) ctx.Next() }
Match version to handler
The
versioning.NewMatcher(versioning.Map) iris.Handler
creates a single handler which decides what handler need to be executed based on the requested version.app := iris.New()// middleware for all versions.myMiddleware := func(ctx iris.Context) { // [...] ctx.Next() }myCustomNotVersionFound := func(ctx iris.Context) { ctx.StatusCode(404) ctx.Writef("%s version not found", versioning.GetVersion(ctx)) }userAPI := app.Party("/api/user") userAPI.Get("/", myMiddleware, versioning.NewMatcher(versioning.Map{ "1.0": sendHandler(v10Response), "\>= 2, \< 3": sendHandler(v2Response), versioning.NotFound: myCustomNotVersionFound, }))
๐ Deprecation
๐ Using the
versioning.Deprecated(handler iris.Handler, options versioning.DeprecationOptions) iris.Handler
function you can mark a specific handler version as deprecated.v10Handler := versioning.Deprecated(sendHandler(v10Response), versioning.DeprecationOptions{ // if empty defaults to: "WARNING! You are using a deprecated version of this API."WarnMessage stringDeprecationDate time.TimeDeprecationInfo string}) userAPI.Get("/", versioning.NewMatcher(versioning.Map{ "1.0": v10Handler, // [...]}))
This will make the handler to send these headers to the client:
"X-API-Warn": options.WarnMessage
- ๐
"X-API-Deprecation-Date": context.FormatTime(ctx, options.DeprecationDate))
- ๐
"X-API-Deprecation-Info": options.DeprecationInfo
๐ > versioning.DefaultDeprecationOptions can be passed instead if you don't care about Date and Info.
Grouping routes by version
Grouping routes by version is possible as well.
Using the
versioning.NewGroup(version string) *versioning.Group
function you can create a group to register your versioned routes.
Theversioning.RegisterGroups(r iris.Party, versionNotFoundHandler iris.Handler, groups ...*versioning.Group)
must be called in the end in order to register the routes to a specificParty
.app := iris.New()userAPI := app.Party("/api/user")// [... static serving, middlewares and etc goes here].userAPIV10 := versioning.NewGroup("1.0") userAPIV10.Get("/", sendHandler(v10Response))userAPIV2 := versioning.NewGroup("\>= 2, \< 3") userAPIV2.Get("/", sendHandler(v2Response)) userAPIV2.Post("/", sendHandler(v2Response)) userAPIV2.Put("/other", sendHandler(v2Response)) versioning.RegisterGroups(userAPI, versioning.NotFoundHandler, userAPIV10, userAPIV2)
A middleware can be registered to the actual
iris.Party
only, using the methods we learnt above, i.e by using theversioning.Match
in order to detect what code/handler you want to be executed when "x" or no version is requested.๐ Deprecation for Group
๐ Just call the
Deprecated(versioning.DeprecationOptions)
on the group you want to notify your API consumers that this specific version is deprecated.userAPIV10 := versioning.NewGroup("1.0").Deprecated(versioning.DefaultDeprecationOptions)
Compare version manually from inside your handlers
// reports if the "version" is matching to the "is".// the "is" can be a constraint like "\>= 1, \< 3".If(version string, is string) bool // same as `If` but expects a Context to read the requested version.Match(ctx iris.Context, expectedVersion string) bool app.Get("/api/user", func(ctx iris.Context) { if versioning.Match(ctx, "\>= 2.2.3") { // [logic for \>= 2.2.3 version of your handler goes here]return } })
Example can be found here.