[1.2.4] Strategy for maintaining multiple versions of a REST API

[Kiran Rao]

I am using Play! framework for developing a RESTful API. I am exploring ways of including a version number in the API URL - like so:

/myapi/v1.0/dogs
This would fetch a list of all dogs using API version 1.0

Obviously, if I increment to a new version, I might still want to serve the old version alongside.
/myapi/v2.0/dogs

How would one go about doing this? I can think of two primary paths:

Single Controller across Versions:
In this approach, the controller actions receive the API version as an argument, and then take the appropriate action based on this version number

GET    /myapi/{version}/dogs        DogsController.list

And then:

static void list(String version){
    if("v1.0".equals(version)){
        //Do the version 1.0 logic
    } else { //if 2.0, then do the 2.0 logic
    }
}

Have separate Controllers for each version:
The routes file might look like this:
GET /myapi/v1.0/dogs        DogsControllerv1_0.list
GET /myapi/v2.0/dogs        DogsControllerv2_2.list


Is there a way these 2 approaches can be combined? i.e., is there a way I can write a piece of Java code which examines the version string and dynamically invokes a particular Controller?

[Manuel Bernhardt]

I wouldn't use the version as part of the path, but rather the Accept
header. Implementation-wise, you'd then use a single controller that
would call the various methods.

See http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http#i_want_my_api_to_be_versioned

> --
> You received this message because you are subscribed to the Google Groups
> "play-framework" group.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/play-framework/-/p0J0V6D80nIJ.
> To post to this group, send email to play-fr...@googlegroups.com.
> To unsubscribe from this group, send email to
> play-framewor...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/play-framework?hl=en.

[Kiran Rao]

Thanks for the link Manuel. This is really interesting. In combination with the vendor-specific MIME type it seems to be a powerful tool for maintaining version of a REST API.

I'm still unsure of the implementation aspect though. Really, from a long term maintenance perspective, I feel each version should have its own Controller (or at least Action), rather than adding if-else checks within each Controller. I agree this is arguable - but it is my opinion. Does Play! framework perform Conneg at this level? Will it invoke the appropriate Action based on non-standard Content-types and Accept Headers?