URI Templates in JAX-RS
The JAX-RS - The Java API for RESTful Web Services JSR has much potential -- it's always refreshing to see innovative APIs. As an improvement to the @Path and @PathParams annotations, I think we can strengthen the grantees of how URI templates are managed and defined. As always, I follow the conviction that an API-proposal needs to fit on one piece of page. So let me contrast JAX-RS' current design with a DRY approach by providing an example. I propose a distinct unit (here ResourceURI) which know about the internal URI contract requirements. In code,
/**
* Abstraction for a URI template.
*/
@Path("{path}/{urn}")
CoolResourceURI implements ResourceURI {
@Variable("path")
private final String path;
@Variable("urn", "urn:\\.*")
private final URI urn;
getPath() {
return path;
}
getURN() {
return urn;
}
...
}
/**
* Associate a {@code CoolResource} with the {@code CoolResourceURI} contract.
*/
class CoolResource implements Resource<CoolResourceURI>.Get {
/**
* Handle {@code GET} HTTP/1.1 request for resources that map to {path}/{urn}
*
* @see Resource<T extends ResourceURI>.Get#get(T)
*/
get(CoolResourceURI uri) {
// do something with the URI components
// Ex: "/some/path/urn:cool:cow"
// --> path="/some/path", urn="urn:cool:cow"
...(uri.getPath(), uri.getURN());
}
...
}
Notice how this different design strategy would strengthen the weakly-typed approach that we currently see in the JSR draft. I tried to demonstrate an improvement to the API by showing REST components that use ResourceURIs (see CoolResourceURI) as a means to encapsulate the URI contract to which the REST service must adhere. This is what we would expect from a DRY design.
Also note how the get(CoolResourceURI) is a type-strong and an expressive way of saying that only GET HTTP/1.1 requests for a specific URI contract should be fulfilled. I would expect this design to simplify the JAX-RS implementation because all URI parsing logic would be directed by the annotations found in the ResourceURI class (i.e. CoolResourceURI).