CODEWITHSUNDEEP
soapjaxbjax-wsjax-rsapi-design
Dobes Vandermeer
Dobes Vandermeer

Reputation: 8820

How do you create backwards compatible JAX-RS and JAX-WS APIs?

JAX-RS and JAX-WS are great for producing an API. However, they don't address the concern of backwards compatibility at all.

In order to avoid breaking old client when new capabilities are introduced to the API, you essentially have to accept and provide the exact same input and output format as you did before; many of the XML and JSON parsers out there seem to have a fit if they find a field that doesn't map to anything, or has the wrong type.

Some JSON libraries out there, such as Jackson and Gson, provide a feature where you can specify a different input/output representation for a given object based on a runtime setting, which seems like a suitable way to handle versioning for many cases. This makes it possible to provide backwards compatibility by annotating added and removed fields so they only appear according to the version of the API in use by the client.

Neither JAXB nor any other XML databinding library I have found to date has decent support for this concept, nevermind being able to re-use the same annotations for both JSON and XML. Adding it to the JAXB-RI or EclipseLink Moxy seems potentially possible, but daunting.

The other approach to versioning seems to be to version all the classes that have changed, often by creating a new package each time the API is published and making copies of all modified DTO, Service, and Resource classes in the new package so that all the type information is versioned for the binding and dispatch systems. This approach seems more laborious to me.

My question is: how have you designed your Jave API providers for backwards compatibility? What worked, what didn't?

Links to case studies or blog posts on the subject much appreciated; I've done some googling but haven't been finding much discussion of this.

Upvotes: 6

Views: 1301

Answers (1)

bdoughan
bdoughan

Reputation: 149047

I'm the tech lead for EclipseLink MOXy, I'm very interested in your versioning requirements. You can reach me through my blog:

MOXy offers a means to represent the JAXB metadata as an XML file. You can leverage this to create multiple mappings for the same object model:

Upvotes: 0

Related Questions