Easy REST resource versioning in JAX-RS based implementations?

Question

Best practice for REST resource versioning is putting version information into Accept/Content-Type headers of HTTP request leaving URI intact.

Here is the sample request/response to REST API for retrieving system information:

==>
GET /api/system-info HTTP/1.1
Accept: application/vnd.COMPANY.systeminfo-v1+json

<==
HTTP/1.1 200 OK
Content-Type: application/vnd.COMPANY.systeminfo-v1+json
{
  “session-count”: 19
}

Pay attention that version is specified in MIME type.

Here is another request/response for version 2:

==>
GET /api/system-info HTTP/1.1
Accept: application/vnd.COMPANY.systeminfo-v2+json

<==
HTTP/1.1 200 OK
Content-Type: application/vnd.COMPANY.systeminfo-v2+json
{
  “uptime”: 234564300,
  “session-count”: 19
}

See http://barelyenough.org/blog/tag/rest-versioning/ for more explanation and examples.

Is it possible to implement this approach easily in Java-targeted JAX-RS based implementations, such as Jersey or Apache CXF?

The goal is to have several @Resource classes with the same @Path value, but serving the request based on actual version specified in MIME type?

I've looked into JAX-RS in general and Jersey in particlaur and found no support for that. Jersey doesn't give a chance to register two resources with the same path. Replacement for WebApplicationImpl class needs to implemented to support that.

Can you suggest something?

NOTE: It is required for multiple versions of the same resource needs to be available simultaneously. New versions may introduce incompatibale changes.

Solution 1

JAX-RS dispatches to methods annotated with @Produces via the Accept header. So, if you want JAX-RS to do your dispatching, you'll need to leverage this mechanism. Without any extra work, you would have to create a method (and Provider) for every media type you wish to support.

There's nothing stopping you from having several methods based on media type that all call a common method to do that work, but you'd have to update that and add code every time you added a new media type.

One idea is to add a filter that "normalizes" your Accept header specifically for dispatch. That is, perhaps, taking your:

Accept: application/vnd.COMPANY.systeminfo-v1+json

And converting that to, simply:

Accept: application/vnd.COMPANY.systeminfo+json

At the same time, you extract the version information for later use (perhaps in the request, or some other ad hoc mechanism).

Then, JAX-RS will dispatch to the single method that handles "application/vnd.COMPANY.systeminfo+json".

THAT method then takes the "out of band" versioning information to handle details in processing (such as selecting the proper class to load via OSGi).

Next, you then create a Provider with an appropriate MessageBodyWriter. The provider will be selected by JAX-RS for the application/vnd.COMPANY.systeminfo+json media type. It will be up to your MBW to figure out the actual media type (based again on that version information) and to create the proper output format (again, perhaps dispatching to the correct OSGi loaded class).

I don't know if an MBW can overwrite the Content-Type header or not. If not, then you can delegate the earlier filter to rewrite that part for you on the way out.

It's a little convoluted, but if you want to leverage JAX-RS dispatch, and not create methods for every version of your media type, then this is a possible path to do that.

Edit in response to comment:

Yea, essentially, you want JAX-RS to dispatch to the proper class based on both Path and Accept type. It is unlikely that JAX-RS will do this out of the box, as it's a bit of an edge case. I have not looked at any of the JAX-RS implementations, but you may be able to do what you want by tweaking one of the at the infrastructure level.

Possibly another less invasive option is to use an age old trick from the Apache world, and simply create a filter that rewrites your path based on the Accept header.

So, when the system gets:

GET /resource
Accept: application/vnd.COMPANY.systeminfo-v1+json

You rewrite it to:

GET /resource-v1
Accept: application/vnd.COMPANY.systeminfo-v1+json

Then, in your JAX-RS class:

@Path("resource-v1")
@Produces("application/vnd.COMPANY.systeminfo-v1+json")
public class ResourceV1 {
    ...
}

So, your clients get the correct view, but your classes get dispatched properly by JAX-RS. The only other issue is that your classes, if they look, will see the modified Path, not the original path (but your filter can stuff that in the request as a reference if you like).

It's not ideal, but it's (mostly) free.

This is an existing filter that might do what you want to do, if not it perhaps can act as an inspiration for you to do it yourself.

Solution 2

With current version of Jersey, I would suggest an implementation with two different API methods and two different return values that are automatically serialised to the applicable MIME type. Once the requests to the different versions of the API are received, common code can be used underneath.

Example:

import javax.ws.rs.*;
import javax.ws.rs.core.MediaType;

@GET
@Path("/{id}")
@Produces(MediaType.APPLICATION_JSON)
public VersionOneDTO get(@PathParam("id") final String id) {

    return new VersionOneDTO( ... );

}

@GET
@Path("/{id}")
@Produces("application/vnd.COMPANY.systeminfo-v2+json;qs=0.9")
public VersionTwoDTO get_v2(@PathParam("id") final String id) {

    return new VersionTwoDTO( ... );

}

If method get(...) and get_v2(...) use common logic, I would suggest to put that in a common private method if it's API related (such as session or JWT handling) or else in a common public method of a Service Layer that you access via inheritance or Dependency Injection. By having two different methods with different return types, you ensure that the structure returned is of correct type for the different versions of the API.

Note that some old client may not specify Accept header at all. That means implicitly that they would accept any content type, thus any version of your API. In practice, this is most often not the truth. For this reason you should specify a weight to newer versions of the API using the qs extension of the MIME type as shown in the @Produces annotation in the example above.

If you are testing with restAssured it would look something like this:

import static com.jayway.restassured.RestAssured.get;
import static com.jayway.restassured.RestAssured.given;

@Test
public void testGetEntityV1() {
    given()
        .header("Accept", MediaType.APPLICATION_JSON)
    .when()
        .get("/basepath/1")
    .then()
        .assertThat()
        ... // Some check that Version 1 was called
    ;
}

@Test
public void testGetEntityV1OldClientNoAcceptHeader() {
    get("/basepath/1")
        .then()
        .assertThat()
        ... // Some check that Version 1 was called
    ;
}

@Test
public void testGetEntityV2() {
    given()
        .header("Accept", "application/vnd.COMPANY.systeminfo-v2+json")
    .when()
        .get("/basepath/1")
    .then()
        .assertThat()
        ... // Some check that Version 2 was called
    ;
}

Comments

[Jochen Bedersdorfer]

This definitely NOT best practice for versioning an API. The best practice is to NOT have versions and only make compatible changes. Artificially creating new MIME types for changes that every sensible client should deal with automatically (adding new tags/keys to your data) is not RESTful at all in my book.

[Volodymyr Tsukur]

Well, it is NOT always possible to make compatible changes. Moreover,, in my case multiple REST resource versions need to be supported simultaneously. As far as resource identity must be preserved URI must change the same. New version is the new representation of the resource, i.e. new MIME type.

[Darrel Miller]

@Jochen Ideally you should never have to version. That should be the goal. However, if it does become necessary then I would say this is best way to handle it.

[StaxMan]

Darrel: this is exactly how URLs are used by specifications by IETF for example, as well as many public web services. It is an obvious and simple solution for versioning. Nothing evil in there whatsoever. It may not work for this use case, but is used by everyone else.

[Asela Liyanage]

@StaxMan the nice thing about doing versions in the MIME type is that you can pass a URL over to a different client which is on a newer version of the API, and it will still work. (this is just one example where it is clearly a benefit)

[Volodymyr Tsukur]

The problem is that I don't want to move version-specific logic right inside the method implementation. I want that to be handled outside.

[Diego Dias]

Either way you will have to "create a layer to choose which method to call". The way you are proposing this layer will call a specific method based on the @Consumes content. The solution I posted you will have just one @Consumes and choose the method to call inside it. For me its just the same, one way you handle with annotations and replicate on methods. The other way you replicate method calls.

[Volodymyr Tsukur]

Well, the problem is that there HAVE to be multiple resource classes with the same @Path. All these classes should be provided by OSGi bundles of different versions, all of them may be active. Resource class cannot be the entry point for versioning-selector logic.

[StaxMan]

I think it is basically a bad idea to use same URI (path) for incompatible versions; even if it seems like more convenient way to do things. Instead of trying to fight this, maybe you could refactor things to reduce duplication, and just consider entry method to be simple wrapper, delegating to shared functionality.

[Volodymyr Tsukur]

Thank you very much for the answer. This is getting closer to what I need. Transforming MIME will do the part of the job. However I don't want the Resource method to deal with versioning information. Whole Resource class should represent specific Resource version AND there will be several Resource classes in the runtime, e.g. RestService in bundle 1.0 and RestService in bundle 2.0, both having @Path('/rest'). I want to instruct Jersey to differenciate between the two without rewriting WebApplicationImpl if possible. (if not possible then I will move on and rewrite / extend it)

[Volodymyr Tsukur]

@StaxMan Unfortunately, simple wrapper that delegates to shared functionality will not resolve the issue here

[Volodymyr Tsukur]

Donal, thank you for the response. You've pointed at hint to serialization provider, which is part of the output preparation. More important question is how to make process input and how to register several Resource class under the same path.

[StaxMan]

Ah. I guess I should have guessed that problem to solve is rather complex, given suggested solution. I hope you will figure it out either way.

[Volodymyr Tsukur]

This is probably the best answer up till now. Ideally, I will not have versions in @Path, @Produces and resource class names for my class since version should be taken from OSGi bundle version specifier. But again, that's IDEAL scenario. You gave you very useful hints here. Thank you!

[Donal Fellows]

@Volodymyr: Register several resource classes under the same path? That surely can't be RESTful! The whole point is that you're exposing many views of the same underlying resource. Those different JSON presentations must be simply different ways of viewing the one thing. (The serializers have to be taught how to construct the different views, but that's what you get for going to this sort of complexity.)

[Donal Fellows]

And for input (i.e., the @Consumes annotation) you just have to deal with what you've been given. Clients tend to hate it if you throw what they've sent back in their face though (when I had code that did that, it caused great conniptions for my colleague who was writing the companion client library…)

[Volodymyr Tsukur]

Resource should be the same, that's true. I am not violating REST. In my case each Resource class is aimed to provide different representations. Versioning is tied to representations in this case. But new representations (Resource classes) can come in from OSGi bundles. Even class name may br the same. This is a very dynamic system. I don't want to introduce my own framework around that since levereging JAX-RS is very useful.