URI API Versioning with Kotlin/SpringBoot: How to version model, DTO, repository and service

[Geane Norm]

Hi,
I have been working with a Kotlin/SpringBoot and opted for the URI API Versioning approach. I am, however, very unsure on how to go about versioning model, DTO, repository and service classes. What is the best approach to follow. I give you an example from my controller:

@RestController
@RequestMapping("/customers")
@Api("/customers", description = "customers endpoints")
class CustomerController(
  private val customerService: CustomerService
) {


  @GetMapping("/customers/v1", produces = [MediaType.APPLICATION_JSON_VALUE])
  @ResponseStatus(value = HttpStatus.OK)
  @ApiOperation(value = "Get all customers")
  fun getCustomersV1(
    @RequestParam(required = false) email: String? = null,
    @RequestParam(required = false) customerId: Customer.Status? = null,
    pageable: Pageable
  ): Page<CustomerDto> {
    return userService.getCustomersV1(
      pageable = pageable,
      email = email,
      customerId = customerId
    )
  }

  @GetMapping("/customers/v2", produces = [MediaType.APPLICATION_JSON_VALUE])
  @ResponseStatus(value = HttpStatus.OK)
  @ApiOperation(value = "Get all customers")
  fun getCustomersV2(
    @RequestParam(required = false) email: String? = null,
    @RequestParam(required = false) customerId: Customer.Status? = null,
    @RequestParam(required = false) username: String? = null,
    pageable: Pageable
  ): Page<CustomerDtoV2> {
    return userService.getCustomersV2(
      pageable = pageable,
      email = email,
      customerId = status,
      username = username
    )
  }

As you can see, I have two @GetMapping with two versions of the service method getCustomers (V1 and V2). I also have a change in the model (one additional field), so I have created a new version of CustomerDto (v2). Is this the correct approach? Change in the model also required me to modify the Dto converter as well as the Repository. Is it good norm to have multiple versions of the repository considering that there has been a change in the model?

[Tim Cooke]

I would only consider applying a versioning strategy to the public API of your system as a courtesy to your users providing backwards compatibility. How you organise your code behind that API is entirely up to you so do whatever makes the most sense to you and the other maintainers of the code (if any).