The Spring framework provides excellent support for building REST
web services in a service-oriented architecture (SOA), as I have demonstrated in a previous
post, but what is not immediately obvious is how best to deal with errors. Instead of throwing raw exceptions to the client, one would prefer to return a well-formed response consisting of an appropriate HTTP status code and a meaningul response body containing a structured error message in the response form (JSON, XML, ...) requested by the client.
For example, assuming you have a basic REST endpoint such as:
@RequestMapping(value = "/samples", method = {RequestMethod.GET})
@ResponseBody
public SampleList findAllSamples() throws SampleException {
return new SampleList(service.findAllSamples());
}
It is good practice in general to not let implementation exceptions leave the service tier, so you might use aspects to catch these and rethrow them as service exceptions. The code below catches a ReferenceNotFoundException from the data access tier and throws a service exception with the reference number and setting the desired http status code. Another good practice is to avoid sending free text error messages to a service client, and instead to send structured messages that can be dealt with or rendered as the client sees fit.
@Aspect
@Component("exceptionHandler")
public class ExceptionHandler {
/**
* Exception handler for ReferenceNotFoundExceptions
*
* @param nfe the exception being handled
*/
@AfterThrowing(pointcut = "execution (* com.sample.service.*.*(..))",
throwing = "nfe")
public void handleNotFoundException(ReferenceNotFoundException nfe) {
throw new SampleException(
new ReferenceNotFoundError(nfe.getReference()),
HttpStatus.NOT_FOUND);
}
Now to map the service exception (SampleException) to a meaningful HTTP response using the Spring 3 @ExceptionHandler annotation:
@ExceptionHandler(SampleException.class)
@ResponseBody
public SampleErrorList exceptionHandler(SampleException se,
HttpServletRequest req,
HttpServletResponse res) throws IOException {
res.setStatus(se.getHttpStatus());
return new SampleErrorList(se.getErrors());
}
It is also possible to set the HTTP status code using an annotation, but in this example the exception determines this, so the handler sets it programmatically.
See
here for a downloadable working sample.
REST Web Service Spring Error Handling
