URI Templates in JAX-RS

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).