Good tools for versioning REST models for Java

Question

I am looking for good tools to support support changing the version of the model used in REST services. My dream tools would do something like:

• My pojo + version 1.0 config/transformer => Service available with 1.0 of my model
• My pojo + version 1.1 config/transformer => Service available with 1.1 of my model

In my particular case I do not need to do the reverse transformation as my REST service will only provide lookup of data and never store stuff, but I don't mind using a tool doing both:-)

A solution I am considering is adding custom annotations in my pojo (version + name) and make a code generator that will generate JSON/XML based on my pojo based on the version number. Though here I feel like I am re-inventing the wheel.

Edit: Here is an example of a change that can be done from version 1 to version 1.1:

Version 1: Person firstname lastname

Version 1.1 Person firstname lastname birthdate

If you access the API with version 1.0 you do not get the birthdate attribute - it is only available in version 1.1. I want tool support for making these services available, where I can configure that granted that my pojo (which is currently like the 1.1 version), I want to make available a 1.0 version that does not show these values.

Other legal changes to the model could be to delete an attribute or to rename an attribute (or even rename an entity).

Edit 2: Digital Joel mentioned in a comment that for a discussion on versioning the API you should go read https://stackoverflow.com/posts/9789756/.

The easy way out of versioning is ofcourse to not make backward breaking API changes, but business change so this is not always possible. My interest is on how to make these changes simpler to handle, therefore my question.

Edit 3: I've looked for tools that might help the process, but still nothing that connects this in a good way with rest. Here are the links that I have found so far:

• http://wiki.pmease.com/display/xmt/What%27s+XMT (Looks like a library for helping with serialization pojos to xml with versioning)

Answer 1

As mentioned in one answer, there may be no tools available for which does automatic versioning of APIs.

We can address this challenge with two step approach :

1) Versioning info of API There are many debates on best practice. two most popular are :

(i) URI redesign - putting version info in URI like
http://something.com/v1.0/resource1/ or
http://something.com/resource1?ver=1.0

(ii) Using HTTP Header - putting version info in Accept/Content-Type
header keeping URI intact like 
#
GET /something/ HTTP/1.1 
Accept: application/resource1-v1.0+json

2) Multiple versions of same pojo using json/xml library

Once version info is with us we have to generate resource accordingly. There are many json and xml library with which we can maintain multiple versions of same pojo and serialize only required attributes based on version. Google gson java library works great in this. Check https://sites.google.com/site/gson/gson-user-guide#TOC-Versioning-Support

public class Person{

@Since(1.0)
private String firstname;

@Since(1.0)
private String lastname;

@Since(1.1)
private String birthdate;

}

Answer 2

I'm not aware of any tools for automatically versioning your RESTful API. For a big discussion on versioning REST you should read Best practices for API versioning?.

I spent a fair amount of time looking into this when planning a RESTful API, and we came to the conclusion that we would evolve in a manner that does not introduce breaking changes. If a breaking change is required then we would expose it as a new resource rather than try to use version information in a custom header or mime type. But, to your question, that means work on my side, which is even more incentive to keep from making breaking changes.

When it comes to tools, I seriously doubt you are going to find something that can automagically make the changes required for supporting multiple versions of your RESTful API. It would require a tool that understands the differences between 2 versions of your model, and all of the interactions in your API.

If you are conforming to the HATEOAS principle of REST then all destinations from a given location are also included in the response, in which case you could use something like the REST support the request mappings in Spring MVC to keep the version number in all of your URLS given a single entry point from the client, but you would still need to maintain the controllers and model for each version.