Iris: Versioning with accept headers

[chiquitawow]

I would like to version my routes by using Accept headers, however I can't seem to find any documentation on how Iris handles this.

[kataras]

You can do whatever you want with Iris, just accept the header and switch logic inside your handler, we can't implement everything here but I always liked this (although versioning can be done with Party("/v1" for example, a path prefix) so I am willing to discuss it for a built'n feature.
Give us an example code, how you imagine it? I can contribute to your idea by providing an API and make it reality.

i.e, via app.Get("/path", handler).Version("1.0") (Get/Post and so on returns the *Route so we can do that like this) or:

 app.Get('/path', iris.Versioning(iris.Map{"1.0": v1Handler, "~2.1.0": v2Handler, "default (or not found we will see)": unknownVersionHandler}))
// we can have a middleware to set a custom version getter as well, i.e:
// ctx.Values().Set("version", valueFromHeaderOrURLParam)
// to customize the version 

or something else inside the handler itself? You name it

[chiquitawow]

Yes. In the short term I'm planning to get the header and then use switch. A cleaner solution would indeed be to add to the Party functionality.

I'll have to think some more on this, but I think the version is :ok: to stay within the scope of Party.

[kataras]

Meanwhile, I am coding it and I will give you an example code which will work for both specific routes and group of them so we can compare our thoughts and find the most decent solution for this, sounds ok?

[kataras]

@chiquitawow You can see the progress at: https://github.com/kataras/iris/pull/1130, you can also fork the repo and work on that branch as well to push your own ideas but please discuss here first.

The current implementation (which is not ready yet, just a proposal) contains:

• per route version matching, a normal iris handler with "switch" cases via Map for version => handler
• 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
• deprecation options with customizable "X-API-Warn", "X-API-Deprecation-Date", "X-API-Deprecation-Info" headers via a simple handler wrapper
• simple tests

[chiquitawow]

Looks good. Thanks for the initial POC. I'll take a look at the implementation soon.