API Versioning
Gin uses the HTTP header Accept
to version your API. The header has the format:
application/vnd.{application-name}.v{version}+json
So for instance, if your application name (as defined in the file ./config/application.lua
) is demo
, a client trying to access the version 1
of your API will have to send the header:
Accept: application/vnd.demo.v1+json
Gin only accepts requests that provide JSON in the body, hence the
+json
portion of theAccept
header.
Major versioning is baked into Gin. You only need to define your version routes, and ensure that the controllers that respond to them are inside the correspondant directory ./app/controllers/{major-version}
. For example, all controllers responding to version 1
need to be placed in the ./app/controllers/1
directory.
Minor versioning support
If you need to provide support for minor versioning of your APIs, a client can specify a minor version like 1.0.13-beta
by providing the header:
Accept: application/vnd.demo.v1.0.13-beta+json
While support for major version numbers is baked into Gin by calling the controllers that correspond to a major version number, minor versioning can be supported at controllers' level. Please see controllers on how to do so.
API Console
Please note that to provide developers with an easy way to play with their API, Gin comes with a handy API Console that takes care of API Versioning in a browser.