Iris v11.1.0 Release Notes

Release Date: 2018-11-18 // almost 3 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.e Accept: "application/json; version=1.0"
    • Accept-Version header, i.e Accept-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.
    The versioning.RegisterGroups(r iris.Party, versionNotFoundHandler iris.Handler, groups ...*versioning.Group) must be called in the end in order to register the routes to a specific Party.

    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 the versioning.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.