ServiceStack: RESTful Resource Versioning

Question

I\'ve taken a read to the Advantages of message based web services article and am wondering if there is there a recommended style/practice to versioning Restful resources i

Answer 1

I am also trying to come with a solution for this and was thinking of doing something like the below. (Based on a lot of Googlling and StackOverflow querying so this is built on the shoulders of many others.)

First up, I don’t want to debate if the version should be in the URI or Request Header. There are pros/cons for both approaches so I think each of us need to use what meets our requirements best.

This is about how to design/architecture the Java Message Objects and the Resource Implementation classes.

So let’s get to it.

I would approach this in two steps. Minor Changes (e.g. 1.0 to 1.1) and Major Changes (e.g 1.1 to 2.0)

Approach for minor changes

So let’s say we go by the same example classes used by @mythz

Initially we have

class Foo {   string Name; }

We provide access to this resource as /V1.0/fooresource/{id}

In my use case, I use JAX-RS,

@Path("/{versionid}/fooresource")
public class FooResource {

    @GET
    @Path( "/{id}" )
    public Foo getFoo (@PathParam("versionid") String versionid, (@PathParam("id") String fooId) 
    {
      Foo foo = new Foo();
     //setters, load data from persistence, handle business logic etc                   
     Return foo;
    }
}

Now let’s say we add 2 additional properties to Foo.

class Foo { 
    string Name;   
    string DisplayName;   
    int Age; 
}

What I do at this point is annotate the properties with a @Version annotation

class Foo { 
    @Version(“V1.0")string Name;   
    @Version(“V1.1")string DisplayName;   
    @Version(“V1.1")int Age; 
}

Then I have a response filter that will based on the requested version, return back to the user only the properties that match that version. Note that for convenience, if there are properties that should be returned for all versions, then you just don’t annotate it and the filter will return it irrespective of the requested version

This is sort of like a mediation layer. What I have explained is a simplistic version and it can get very complicated but hope you get the idea.

Approach for Major Version

Now this can get quite complicated when there is a lot of changes been done from one version to another. That is when we need to move to 2nd option.

Option 2 is essentially to branch off the codebase and then do the changes on that code base and host both versions on different contexts. At this point we might have to refactor the code base a bit to remove version mediation complexity introduced in Approach one (i.e. make the code cleaner) This might mainly be in the filters.

Note that this is just want I am thinking and haven’t implemented it as yet and wonder if this is a good idea.

Also I was wondering if there are good mediation engines/ESB’s that could do this type of transformation without having to use filters but haven’t seen any that is as simple as using a filter. Maybe I haven’t searched enough.

Interested in knowing thoughts of others and if this solution will address the original question.