GUIDES
GUIDESDOCS
These docs are for v0.12. Click to read the latest docs for v0.13.

Versioning

There are three strategies in which clients can reach your API's endpoints: :path, :accept_version_header and :param.
There are two differences from grape:

  1. :header is unsupported.
  2. strategy is bind to server, you should set it in config.exs like this:
config :maru, API,
  versioning: [
    using: :path
  ],
  http: [port: 4000]

Path

Using this versioning strategy, clients should pass the desired version in the URL.

version "v1"

get "/foo/bar" do
	"hello"
end
curl -H http://127.0.0.1:4000/v1/foo/bar

Accept-Version Header

Using this versioning strategy, clients should pass the desired version in the HTTP Accept-Version header.

version "v1"

resource "/foo/bar" do
  get do
		"hello"
  end
end
curl -H "Accept-Version:v1" http://127.0.0.1:4000/foo/bar

Param

Using this versioning strategy, clients should pass the desired version as a request parameter, either in the URL query string or in the request body.

version "v1" do
  get "/foo/bar" do
    "hello"
  end
end
curl -H http://127.0.0.1:4000/foo/bar?apiver=v1

The default name for the query parameter is apiver but can be specified using the :parameter option.

config :maru, API,
  versioning: [
    using: :param,
    parameter: "v",
  ],
  http: [port: 4000]
curl -H http://127.0.0.1:4000/foo/bar?v=v1

Version Extend

Sometime we change or abandon few APIs in a new version and keep rest compatible with old version, use version extend.
Just like import, you can choose what you want to extend by :only and :except options.

version "v2", extend: "v1", at: Router.v1
version "v2", extend: "v1", at: Router.v1, only: [
  get: "/foo", 
  match: "/bar"
]
version "v2", extend: "v1", at: Router.v1, except: [
  get: "/foo/*"
]