Clarify that API versioning for the client is not inferred from the server configuration

[belyaev-andrey]

Assume that we have a versioned REST API:

@RestController
@RequestMapping("/api")
class QuoteController {

    @GetMapping(path = "/quote", produces = "application/json", version = "1.0+")
    ResponseEntity<Quote> getQuote() {
       //...
    }

    @GetMapping(path = "/quote", produces = "application/json", version = "2.0")
    ResponseEntity<List<Quote>> getQuotes() {
       //...
    }

It is configured like this:

spring:
  mvc:
    apiversion:
      use:
        header: API-Version

To test it properly, we need to invoke all endpoints with a proper version header:

        mockMvc.perform(get("/api/quote")
                        .accept(MediaType.APPLICATION_JSON)
                        .header("API-Version", "1.0")
                )
                .andExpect(status().isOk())

With Spring 7, we can use apiVersion method, which is more convenient and explicit

        mockMvc.perform(get("/api/quote")
                        .accept(MediaType.APPLICATION_JSON)
                        .apiVersion("1.0")
                )
                .andExpect(status().isOk())

The problem is that this approach doesn't work by default, error No ApiVersionInserter appears:

[ERROR] com.test.boot4.server.quote.QuoteControllerTest.getQuote_returnsJsonFromService -- Time elapsed: 0.025 s <<< ERROR!
java.lang.IllegalStateException: No ApiVersionInserter
        at org.springframework.util.Assert.state(Assert.java:80)
        at org.springframework.test.web.servlet.request.AbstractMockHttpServletRequestBuilder.buildRequest(AbstractMockHttpServletRequestBuilder.java:751)
        at org.springframework.test.web.servlet.MockMvc.perform(MockMvc.java:170)

To fix this, we need to add a bit of boilerplate:

    @TestConfiguration
    static class QuoteControllerAddTestConfig implements MockMvcBuilderCustomizer {
        @Override
        public void customize(ConfigurableMockMvcBuilder<?> builder) {
            builder.apiVersionInserter(ApiVersionInserter.useHeader("API-Version"));
        }
    }

Suggestion:

Is it possible to perform this customization in a auto-configurer based on the application configuration? Basically, all the information we need is there, so why don't we reuse it?

[bclozel]

I discussed this yesterday with @snicoll and we found several reasons not to apply this automatically. Conceptually, this configuration is applied to the REST controller endpoints when a version is used for mapping purposes. The client can have a different configuration, for many reasons.

• there are many endpoints that clients might want to test where versioning does not apply (non-versioned REST endpoints, views, resource handling)
• developers might have different testing strategies in their test suites: not specifying a version and using the default version implicitly, only using a version for some endpoints. This really depends on how developers intend to evolve their APIs and test for backwards compatibility
• custom insertion strategies would not work

We'll discuss that as a team and reconsider our initial position.

[snicoll]

On top of what Brian said, I disagree with

Is it possible to perform this customization in a auto-configurer based on the application configuration? Basically, all the information we need is there, so why don't we reuse it?

That's a bit of a shortcut. There are other ways that you can configure the ApiVersionInserter. You could have a WebMvcConfigurer that configures something programmatically for instance. In fact this might be the main use case for those who have several things to configure.

As such, us doing something that can be inaccurate (or incomplete) is worse than the status quo.

[belyaev-andrey]

My impression was that ApiVersioningInserter applies only if I invoke .apiVersion("1.0") method. It means that the code for non-versioned endpoints should stay the same and won't be affected.

As for custom strategies - it is fair point, but I'm not saying we should get rid of programmatic configuration. If there is a programmatic configuration, we should override properties.

Basically, when we're dealing with testing versioned API, we need either:

• Copy-paste this boilerplate configuration code from other projects (nobody remembers it)
• Add versioning parameter manually to the request (I guess, it's going to be the most popular case)

I might definitely miss something, but it would be so "magical" if versioned API testing work out-of-the-box without any boilerplate code as soon as it is configured in the app.

I'm also OK with a special configuraion properties for MockMvcBuilderCustomizer, just to avoid writing code.

[snicoll]

As for custom strategies - it is fair point, but I'm not saying we should get rid of programmatic configuration. If there is a programmatic configuration, we should override properties.

who is "we"? Technically you could set the property and have a configurer that overrides it. If "we" is the user then we can auto-configure something we shouldn't and break them. If "we" is us, then we have no way to know what was configured programmatically as we get a ApiVersionStrategy that doesn't expose that information (and it should not).

I might definitely miss something, but it would be so "magical" if versioned API testing work out-of-the-box without any boilerplate code as soon as it is configured in the app.

See above, and let me know if I've missed something.

I'm also OK with a special configuraion properties for MockMvcBuilderCustomizer, just to avoid writing code.

Customizer don't have configuration properties. I suppose you mean an attribute on @AutoConfigureMockMvc? What would it look like considering there are four ways to specify the version at the moment.

[belyaev-andrey]

After the second consideration I tend to agree with you. Maybe it is not feasible to do this and it adds more confusion. I believe there is a way to simplify test configuration, but I cannot imagine a better approach now. At the moment, a section in the documentation should be enough I guess. Thanks!

[snicoll]

Thanks for following-up. I think we should at least explore ways to make the setup simpler.

[snicoll]

@rstoyanchev and I brainstormed and spring-projects/spring-framework#35565 provides a shortcut in terms of programmatic API. We'll use this issue to document what the options are to specify the strategy.

For MockMvc, I'd envision something like this:

@Configuration(proxyBeanMethods = false)
class ApiVersioningTestConfig {

	@Bean
	public MockMvcBuilderCustomizer apiVersioningMockMvcCustomizer() {
		return (builder) -> builder.apiVersionInserter(apiVersionBuilder -> apiVersionBuilder.useHeader("API-Version"));
	}

}

How such a test class will be picked up is still TBD.

We've also discussed the use case you've reported here. For that to work we'd need to retrieve the server-side configuration for API versioning (that's doable) and then we'd need to translate it so that it matches what the client expects in terms of configuration. While it might work now, it's certainly restricting our ability to expand the server-side API in ways that makes it impossible to automatically translate the client-side strategy. We also believe that auto-configuring such strategy can lead to confusing situation and we think it is better as an opt-in option.