How to manage REST API versioning with spring data rest?

Question

• What is the way to go supporting API versioning in Spring Rest Data?
• Is it possible to do it with repository-resources or do I have to use RepositoryRestController instead?

I cannot find anything about API versioning in the oficial site of Spring Rest Data

I found a Joshua Long presentations about REST APIs with Spring

API versions can be implemented with one of two ways:

• Through API URIs: https://api.foo.com/v1
• Through media types: application/vnd.company.urapp-v3+json

The first approach have some problems described here

Answer 1

This is an interesting topic. The documentation of spring-data-rest does not mention best-practices for versioning.

From what I know about spring-data-rest it is not possible to implement media type versioning without implementing custom controllers.

But of course the current functionality allows for URI based versioning:

• always include a version in your entity - either in the package or class name - e.g. com.company.v1.MyEntity or com.company.MyEntityV1

• in the repository use @RepositoryRestResource to contain the version in the URI

  @RepositoryRestResource(path = "/v1/shops")

So you could always create a new entity version when you have breaking changes on the API and use a new repository to expose the new version on the API.

EDIT: We were discussing this topic in the team and a few new interesting thoughts on REST API versioning came up that I would like to share.

I think we all agree that the idea outlined above is not an elegant one. It introduces a lot of code duplication and when you switch off the old version you have to remove it from the code base - which can be harder than you think it is. In the meantime you have to maintain two versions in the code base. You would always want to avoid that.

So what are the alternatives. You could do what we often do in a microservices world - push complexity to the infrastructure. Creating and running new runtimes is fairly easy in a microservices infrastructure so we could choose to run two different versions of the same service. The old version providing the old API version and the new one supporting our new version. An API Gateway could take over the routing e.g. based on HTTP headers (Accept or Content-Type) or version information contained in the URI. And if you want to get rid of the old version you just have to switch off the runtimes that run the old version and you are done. I think this can be an elegant solution that keeps your code base clean.

There are chances that your infrastructure already supports running different versions of the same service to support blue-green deployment scenarios. Which means you already have some routing capabilities that you could build up on.

Also I think if you support blue-green deployment scenarios (which you should) you have to keep database schema versions compatible between releases (e.g. your old version of your service needs to be able to run on the new schema version). If you have to keep this level of compatibility it might not be too hard to avoid REST API versioning most of the times. So you are not forced to do it often - maybe only if you make fundamental changes (that you would not do in the same codebase anyway).