6.18 API Versioning

Since 1.1.x, Micronaut supports API versioning via a dedicated @Version annotation.

The following example demonstrates how to version an API:

Versioning an API

import io.micronaut.core.version.annotation.Version;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
@Controller("/versioned")
class VersionedController {
    @Version("1") (1)
    @Get("/hello")
    String helloV1() {
        return "helloV1";
    }
    @Version("2") (2)
    @Get("/hello")
    String helloV2() {
        return "helloV2";
    }

Versioning an API

import io.micronaut.core.version.annotation.Version
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
@Controller("/versioned")
class VersionedController {
    @Version("1") (1)
    @Get("/hello")
    String helloV1() {
        "helloV1"
    }
    @Version("2") (2)
    @Get("/hello")
    String helloV2() {
        "helloV2"
    }

Versioning an API

import io.micronaut.core.version.annotation.Version
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
@Controller("/versioned")
internal class VersionedController {
    @Version("1") (1)
    @Get("/hello")
    fun helloV1(): String {
        return "helloV1"
    }
    @Version("2") (2)
    @Get("/hello")
    fun helloV2(): String {
        return "helloV2"
    }

Then enable versioning by setting micronaut.router.versioning.enabled to true in application.yml:

Enabling Versioning

micronaut:
  router:
    versioning:
      enabled: true

By default Micronaut has two strategies for resolving the version based on an HTTP header named X-API-VERSION or a request parameter named api-version, however this is configurable. A full configuration example can be seen below:

Configuring Versioning

micronaut:
  router:
    versioning:
      enabled: true (1)
      parameter:
        enabled: false (2)
        names: 'v,api-version' (3)
      header:
        enabled: true (4)
        names: (5)
          - 'X-API-VERSION'
          - 'Accept-Version'

If this is not enough you can also implement the RequestVersionResolver interface which receives the HttpRequest and can implement any strategy you choose.

Default Version

It is possible to supply a default version through configuration.

Configuring Default Version

micronaut:
  router:
    versioning:
      enabled: true
      default-version: 3 (1)

A route is not matched if the following conditions are met:

• The default version is configured

• No version is found in the request

• The route defines a version

• The route version does not match the default version

If the incoming request specifies a version, the default version has no effect.

Versioning Client Requests

Micronaut’s Declarative HTTP client also supports automatic versioning of outgoing requests via the @Version annotation.

By default, if you annotate a client interface with @Version, the value supplied to the annotation is included using the X-API-VERSION header.

For example:

import io.micronaut.core.version.annotation.Version;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.client.annotation.Client;
import org.reactivestreams.Publisher;
import io.micronaut.core.async.annotation.SingleResult;
@Client("/hello")
@Version("1") (1)
public interface HelloClient {
    @Get("/greeting/{name}")
    String sayHello(String name);
    @Version("2")
    @Get("/greeting/{name}")
    @SingleResult
    Publisher<String> sayHelloTwo(String name); (2)
}

import io.micronaut.core.version.annotation.Version
import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
import reactor.core.publisher.Mono
@Client("/hello")
@Version("1") (1)
interface HelloClient {
    @Get("/greeting/{name}")
    String sayHello(String name)
    @Version("2")
    @Get("/greeting/{name}")
    Mono<String> sayHelloTwo(String name) (2)
}

import io.micronaut.core.version.annotation.Version
import io.micronaut.http.annotation.Get
import io.micronaut.http.client.annotation.Client
import reactor.core.publisher.Mono
@Client("/hello")
@Version("1") (1)
interface HelloClient {
    @Get("/greeting/{name}")
    fun sayHello(name : String) : String
    @Version("2")
    @Get("/greeting/{name}")
    fun sayHelloTwo(name : String) : Mono<String>  (2)
}

The default behaviour for how the version is sent for each call can be configured with DefaultClientVersioningConfiguration:

🔗

For example to use Accept-Version as the header name:

Configuring Client Versioning

micronaut:
  http:
    client:
      versioning:
        default:
          headers:
            - 'Accept-Version'
            - 'X-API-VERSION'

The default key refers to the default configuration. You can specify client-specific configuration by using the value passed to @Client (typically the service ID). For example:

Configuring Versioning

micronaut:
  http:
    client:
      versioning:
        greeting-service:
          headers:
            - 'Accept-Version'
            - 'X-API-VERSION'

The above uses a key named greeting-service which can be used to configure a client annotated with @Client('greeting-service').