dev@jsr311.java.net

Re: General comments/questions/suggestions

From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Thu, 24 Jan 2008 12:08:21 -0500

On Jan 18, 2008, at 10:36 AM, Marc Hadley wrote:
>
>>
>> created(String path);
>>
>> This path should be concatenated to the base URI of the REST
>> engine. For example, if JAX-RS is deployed from a WAR under http://www.jboss.org/REST
>>
>> Then:
>>
>> created("/customers/3424234"); should send a location: http://www.jboss.org/REST/customers/3424234
>>
>> I believe redirects will be a common thing given it is a usage
>> pattern in books like Restful Web Services. We need an easy way to
>> create these URIs.
>>
> So essentially
>
> created("somepath")
>
> would be a shortcut for
>
> created(UriInfo.getBaseUriBuilder().path("somepath").build())
>
> For the example you give above (assuming you have a Customer
> resource with @Path("customers/{id}") you could also do something like
>
> created
> (UriInfo.getBaseUriBuilder().path(Customer.class).build("3424234"))
>
> which perhaps we could shorten to:
>
> created(Customer.class, "3424234")
>
I made a start down this road but it quickly became apparent that I
was duplicating a lot of the functionality already available in
UriBuilder. Currently the most I think we should do is to add String
alternates for the existing URI-based methods with a note that they
are equivalent to calling the URI method with the results of
URI.create(String). I.e.:

created(String) is equivalent to created(URI.create(String)).

I'd be interested in any feedback regarding the merit of such
alternate methods vs the potential "cluttering" effect on the API ?

I've addressed relative URI support as follows:

- for created() a relative URI is resolved against the request URI.
The rationale is that you'd commonly create a subresource of the
current resource, so e.g. a POST to /widgets would create a new widget
resource at /widgets/someid so its handy to be able to call
created("someid") rather than created("/widgets/someid").

- for redirections I think the relationship between the request and
the target of the redirection is less obvious so a relative URI is
resolved against the base URI of the application instead.

Make sense ?

Marc.

---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.