Best practices (examples?) on organizing versioned REST API code in Java/Spring project?

Question

I am curios if anybody can point me to a good example/best practice of organizing REST API code with versioning (uri-based, means "/v1/zzz" and "/v2/xxx" or even better something relying on Accept header) -- in Java/Spring project? I am afraid I am making it too complicated in my project right now, so it'd be nice to learn from others.

Clarification: not sure if I should do it through filters, and then use some design pattern to change the behavior, but this will make my filter pretty complicated.. or may be I am not thinking about some trick with spring and DI, so I can make my code cleaner. the simplest approach is some strategy pattern in every method which will have different versioning, but it doesn't seem to be too clean neither :-(

It would help a great deal if you could first show us what you're currently doing, lest we end up giving you a suggestion that's just as complicated. Or are you just referring to the URL pattern? What makes you think it's too complicated? Consider adding this info via an edit to your question for clarity. Thank you. — jmort253
Also, how do you know when you have a new version of your API? I'm assuming you're actively modifying your code, but what criteria do you use to determine when to move from v1 to v2? — jmort253

ams ams · Accepted Answer · 2012-07-30T06:09:50

I highly recommend reading the book and blogs on Apigee http://offers.apigee.com/api-design-ebook-bw/ I found that it gave me really practical advice for designing the urls and doing error handling.

http://www.stormpath.com/blog/spring-mvc-rest-exception-handling-best-practices-part-2 has a really great article on how to configure spring mvc to do generic error handling for restful applications.

As for filtering on accept headrs that is pretty easy to do since spring lets you narrow a handler method mapping based on the filter, as in the headers= in the request mapping below.

@RequestMapping(value="/narrow/headers/{name}/{email}/{customerNumber}",
        method={RequestMethod.POST,RequestMethod.GET},
        headers="Referer=http://localhost:8080/SpringMVC/request-mappings.html")
public ResponseEntity<String> narrowOnHeaders(
        @PathVariable("name")String name, 
        @PathVariable("email") String email, 
        @PathVariable("customerNumber") Integer customerNumber,
        @RequestHeader("Referer") String referer
    )

Best practices (examples?) on organizing versioned REST API code in Java/Spring project?

1 Answers